{"openapi":"3.1.0","info":{"title":"Ranked AI REST API","description":"Public REST API for Ranked AI SEO platform. Provides programmatic access to projects, keyword rankings, AI visibility tracking, site audits, backlink monitoring, content calendar, reports, and webhooks.","version":"1.1.0","contact":{"name":"Ranked AI","url":"https://ranked.ai"}},"servers":[{"url":"https://app.ranked.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Projects","description":"Manage SEO projects"},{"name":"Keywords","description":"Track keyword rankings across devices"},{"name":"AI Visibility","description":"Monitor brand visibility in AI model responses"},{"name":"Audits","description":"Run and view SEO site audits"},{"name":"Backlinks","description":"Monitor backlink profiles and referring domains"},{"name":"Content","description":"Content calendar and preferences"},{"name":"Reports","description":"Generate and manage shareable SEO reports"},{"name":"Webhooks","description":"Subscribe to real-time event notifications"}],"paths":{"/projects":{"get":{"operationId":"listProjects","summary":"List projects","description":"Returns all active SEO projects owned by the API key holder (statuses trial, active, past_due). Every project carries `productMode` (managed or software); filter with `product_mode`.","tags":["Projects"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"name":"product_mode","in":"query","required":false,"description":"Only return projects of one product mode.","schema":{"type":"string","enum":["managed","software"]}}],"responses":{"200":{"description":"Paginated list of projects","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createProject","summary":"Create a software project","description":"Creates a self-serve SEO Software project from a website URL. The only project type that can be created through the API: no plan or payment is needed and the project exists immediately. Adding keywords/prompts and running scans requires a live SEO Software plan on the account ($4.99/month per 100 tracked keywords and per 100 AI prompts, prepaid, one plan per account); `plan.active` in the response says whether one exists and `plan.manageUrl` is where to add it. Managed-service projects start from the dashboard. Requires `write:all` scope.","tags":["Projects"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectRequest"}}}},"responses":{"201":{"description":"Project created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedProject"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/rankings/keywords":{"get":{"operationId":"listKeywords","summary":"List tracked keywords","description":"Returns tracked keywords with current position data for a project. Supports filtering by device and date range.","tags":["Keywords"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/DateFrom"},{"$ref":"#/components/parameters/DateTo"},{"name":"device","in":"query","description":"Filter keywords by device type.","schema":{"type":"string","enum":["all","desktop","mobile"],"default":"all"}}],"responses":{"200":{"description":"Paginated list of keywords with ranking data","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KeywordRanking"}},"meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/rankings/keywords/{keywordId}/history":{"get":{"operationId":"getKeywordHistory","summary":"Get keyword position history","description":"Returns historical position data for a specific keyword. Defaults to the last 90 days if no date range is specified.","tags":["Keywords"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"keywordId","in":"path","required":true,"description":"UUID of the keyword.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/DateFrom"},{"$ref":"#/components/parameters/DateTo"}],"responses":{"200":{"description":"Keyword history with summary statistics","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KeywordHistory"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/prompts":{"get":{"operationId":"listPrompts","summary":"List AI prompts","description":"Returns AI prompts with visibility and response data for a project.","tags":["AI Visibility"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Paginated list of AI prompts","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Prompt"}},"meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/prompts/{promptId}":{"get":{"operationId":"getPrompt","summary":"Get AI prompt details","description":"Returns detailed data for a specific AI prompt including per-model responses.","tags":["AI Visibility"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"promptId","in":"path","required":true,"description":"UUID of the prompt.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Prompt details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptDetail"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/prompts/{promptId}/history":{"get":{"operationId":"getPromptHistory","summary":"Get AI prompt response history","description":"Returns response history from each AI model for a specific prompt. Defaults to the last 90 days if no date range is specified.","tags":["AI Visibility"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"promptId","in":"path","required":true,"description":"UUID of the prompt.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/DateFrom"},{"$ref":"#/components/parameters/DateTo"}],"responses":{"200":{"description":"Prompt response history","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptHistory"},"meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/audits":{"get":{"operationId":"listAudits","summary":"List audits","description":"Returns a list of SEO audit tasks for a project.","tags":["Audits"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"name":"status","in":"query","description":"Filter audits by status.","schema":{"type":"string","enum":["all","pending","crawling","processing","completed","failed"],"default":"all"}}],"responses":{"200":{"description":"Paginated list of audit summaries","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditSummary"}},"meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/audits/latest":{"get":{"operationId":"getLatestAudit","summary":"Get latest completed audit","description":"Returns the most recent completed audit for a project, including active issue counts (excluding dismissed issues).","tags":["Audits"],"parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Latest audit details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AuditDetail"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/audits/{auditId}/issues":{"get":{"operationId":"listAuditIssues","summary":"List audit issues","description":"Returns issues for a specific audit. Issues are sorted by severity (critical > warning > notice), then by affected count. Dismissed issues are returned with status `passed`.","tags":["Audits"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"auditId","in":"path","required":true,"description":"UUID of the audit.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"name":"severity","in":"query","description":"Filter issues by severity.","schema":{"type":"string","enum":["all","critical","warning","notice"],"default":"all"}},{"name":"status","in":"query","description":"Filter issues by status.","schema":{"type":"string","enum":["all","passed","failed"],"default":"all"}}],"responses":{"200":{"description":"Paginated list of audit issues","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditIssue"}},"meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/backlinks":{"get":{"operationId":"listBacklinks","summary":"List tracked backlinks","description":"Returns tracked backlinks overview for a project, including domain metrics and link type breakdown.","tags":["Backlinks"],"parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"List of tracked backlink profiles","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BacklinkOverview"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/backlinks/summary":{"get":{"operationId":"getBacklinksSummary","summary":"Get backlinks summary","description":"Returns aggregated backlink metrics for the entire project across all tracked domains.","tags":["Backlinks"],"parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Aggregated backlink summary","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklinksSummary"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/backlinks/domains":{"get":{"operationId":"listReferringDomains","summary":"List referring domains","description":"Returns referring domains for the project's tracked backlinks, with sorting and status filtering.","tags":["Backlinks"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"name":"status","in":"query","description":"Filter referring domains by status.","schema":{"type":"string","enum":["all","active","lost"],"default":"all"}},{"name":"sort_by","in":"query","description":"Field to sort by.","schema":{"type":"string","enum":["domain_rank","backlinks_count","first_seen","last_seen"],"default":"domain_rank"}},{"name":"sort_order","in":"query","description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Paginated list of referring domains","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReferringDomain"}},"meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/backlinks/history":{"get":{"operationId":"getBacklinksHistory","summary":"Get backlinks history","description":"Returns historical backlink data for the project. Defaults to the last 90 days if no date range is specified.","tags":["Backlinks"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/DateFrom"},{"$ref":"#/components/parameters/DateTo"}],"responses":{"200":{"description":"Backlink history with summary","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BacklinkHistoryResponse"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/backlinks/anchors":{"get":{"operationId":"getAnchorTexts","summary":"Get anchor text distribution","description":"Returns anchor text distribution analysis for the project's backlinks.","tags":["Backlinks"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"limit","in":"query","description":"Maximum number of items to return.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":50}},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Anchor text analysis","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnchorsResponse"},"meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/content":{"get":{"operationId":"listContent","summary":"List content items","description":"Returns content calendar items for a project. Defaults to showing items scheduled up to 7 days in the future if no date range is provided.","tags":["Content"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/DateFrom"},{"$ref":"#/components/parameters/DateTo"},{"name":"status","in":"query","description":"Filter content by status name (e.g. `Draft`, `Published`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of content items","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContentItem"}},"meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/content/{contentId}":{"get":{"operationId":"getContentItem","summary":"Get content item details","description":"Returns details for a specific content item, including body content and metadata.","tags":["Content"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"contentId","in":"path","required":true,"description":"UUID of the content item.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Content item details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentDetail"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/content/preferences":{"get":{"operationId":"getContentPreferences","summary":"Get content preferences","description":"Returns content and publishing preferences for a project.","tags":["Content"],"parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Content preferences","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentPreferences"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"operationId":"updateContentPreferences","summary":"Update content preferences","description":"Updates content and/or publishing preferences for a project. Requires `write:all` scope.","tags":["Content"],"parameters":[{"$ref":"#/components/parameters/ProjectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContentPreferencesRequest"}}}},"responses":{"200":{"description":"Updated content preferences","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentPreferences"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/reports":{"get":{"operationId":"listReports","summary":"List reports","description":"Returns generated report links for a project.","tags":["Reports"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Paginated list of reports","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReportLink"}},"meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createReport","summary":"Create a report","description":"Triggers report generation and returns a shareable link hosted on agencyreport.ai. Requires `write:all` scope.","tags":["Reports"],"parameters":[{"$ref":"#/components/parameters/ProjectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReportRequest"}}}},"responses":{"201":{"description":"Report created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreateReportResponse"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/projects/{projectId}/reports/{reportId}":{"get":{"operationId":"getReport","summary":"Get report details","description":"Returns details for a specific report, including configuration options.","tags":["Reports"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"reportId","in":"path","required":true,"description":"Short ID of the report (nanoid, not UUID).","schema":{"type":"string"}}],"responses":{"200":{"description":"Report details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportDetail"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"operationId":"deleteReport","summary":"Delete a report","description":"Soft-deletes a report link so it is no longer accessible. Requires `write:all` scope.","tags":["Reports"],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"reportId","in":"path","required":true,"description":"Short ID of the report (nanoid, not UUID).","schema":{"type":"string"}}],"responses":{"200":{"description":"Report deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string","example":"Report deleted successfully"},"report_id":{"type":"string"}},"required":["message","report_id"]}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhooks","description":"Returns webhook subscriptions for the authenticated user. Optionally filter by project.","tags":["Webhooks"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"name":"project_id","in":"query","description":"Filter webhooks by project UUID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paginated list of webhooks","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createWebhook","summary":"Create a webhook","description":"Creates a new webhook subscription. The response includes a `secret` field (only returned on creation) for verifying webhook signatures. The URL must use HTTPS and cannot point to private addresses. Requires `write:all` scope.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}}},"responses":{"201":{"description":"Webhook created (includes secret)","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookWithSecret"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/webhooks/{webhookId}":{"get":{"operationId":"getWebhook","summary":"Get webhook details","description":"Returns details for a specific webhook subscription.","tags":["Webhooks"],"parameters":[{"name":"webhookId","in":"path","required":true,"description":"UUID of the webhook.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookDetail"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"operationId":"updateWebhook","summary":"Update a webhook","description":"Updates a webhook subscription. Re-enabling a webhook resets consecutive failure count. Requires `write:all` scope.","tags":["Webhooks"],"parameters":[{"name":"webhookId","in":"path","required":true,"description":"UUID of the webhook.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookRequest"}}}},"responses":{"200":{"description":"Updated webhook","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookDetail"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook","description":"Permanently deletes a webhook subscription and its delivery logs. Requires `write:all` scope.","tags":["Webhooks"],"parameters":[{"name":"webhookId","in":"path","required":true,"description":"UUID of the webhook.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string","example":"Webhook deleted successfully"},"id":{"type":"string","format":"uuid"}},"required":["message","id"]}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/webhooks/{webhookId}/test":{"post":{"operationId":"testWebhook","summary":"Test a webhook","description":"Sends a test payload to the webhook endpoint to verify it is reachable and responding correctly. The webhook must be active. Requires `write:all` scope.","tags":["Webhooks"],"parameters":[{"name":"webhookId","in":"path","required":true,"description":"UUID of the webhook.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Test result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TestWebhookResponse"}}}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Keys use the format `rk_live_...`. Pass as `Authorization: Bearer rk_live_...`."}},"parameters":{"ProjectId":{"name":"projectId","in":"path","required":true,"description":"UUID of the project.","schema":{"type":"string","format":"uuid"}},"Limit":{"name":"limit","in":"query","description":"Maximum number of items to return.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":50}},"Offset":{"name":"offset","in":"query","description":"Number of items to skip for pagination.","schema":{"type":"integer","minimum":0,"default":0}},"DateFrom":{"name":"date_from","in":"query","description":"Start of date range (ISO 8601, e.g. `2025-01-01`).","schema":{"type":"string","format":"date"}},"DateTo":{"name":"date_to","in":"query","description":"End of date range (ISO 8601, e.g. `2025-12-31`).","schema":{"type":"string","format":"date"}}},"responses":{"ValidationError":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"VALIDATION_ERROR","message":"Validation failed","details":{"errors":[{"field":"limit","message":"Limit must be a positive integer"}]}},"meta":{"request_id":"req_abc123"}}}}},"Unauthorized":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid or missing API key"},"meta":{"request_id":"req_abc123"}}}}},"Forbidden":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"FORBIDDEN","message":"You do not have access to this resource"},"meta":{"request_id":"req_abc123"}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NOT_FOUND","message":"Resource not found"},"meta":{"request_id":"req_abc123"}}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"RATE_LIMITED","message":"Rate limit exceeded. Please retry later.","details":{"retry_after_seconds":30,"reset":1700000000}},"meta":{"request_id":"req_abc123"}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please try again later."},"meta":{"request_id":"req_abc123"}}}}}},"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","const":true}},"required":["success","data","meta"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]},"meta":{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}},"required":["success","error","meta"]},"ResponseMeta":{"type":"object","properties":{"request_id":{"type":"string","example":"req_a1b2c3d4e5f6"},"rate_limit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer"},"reset":{"type":"integer","description":"Unix timestamp"}},"required":["limit","remaining","reset"]}},"required":["request_id"]},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}},"required":["total","limit","offset","has_more"]},"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["active","trial","past_due"]},"serviceType":{"type":"string"},"productMode":{"type":"string","enum":["managed","software"],"description":"Who runs the project. \"managed\": Ranked AI's team does the work (content, publishing, optimization, outreach) and the full software suite is included in the service plan. \"software\": self-serve SEO Software the account runs itself, billed as prepaid keyword/prompt blocks; no content pipeline."},"websiteUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","status","serviceType","productMode","websiteUrl","createdAt"]},"CreateProjectRequest":{"type":"object","required":["website_url"],"properties":{"website_url":{"type":"string","description":"The website to track, e.g. \"acme.com\" or \"https://acme.com\".","example":"acme.com"},"name":{"type":"string","description":"Project name. Defaults to the domain.","example":"Acme"},"product_mode":{"type":"string","enum":["software"],"description":"Only \"software\" is accepted. Managed-service projects start from the dashboard's Add Project flow."}}},"SoftwarePlanStatus":{"type":"object","description":"The account's SEO Software plan as it applies to the new project.","properties":{"active":{"type":"boolean","description":"False means keywords, prompts and scans are blocked until a plan is added."},"capacity":{"type":"object","description":"Total tracked keywords / AI prompts the plan allows across all software projects.","properties":{"keywords":{"type":"integer"},"prompts":{"type":"integer"}}},"remaining":{"type":"object","description":"Capacity left after existing software projects' usage.","properties":{"keywords":{"type":"integer"},"prompts":{"type":"integer"}}},"pricing":{"type":"string","description":"Plain-language pricing and billing rules."},"manageUrl":{"type":"string","format":"uri","description":"Where to add or change the plan."}},"required":["active","capacity","remaining","pricing","manageUrl"]},"CreatedProject":{"allOf":[{"$ref":"#/components/schemas/Project"},{"type":"object","properties":{"dashboardUrl":{"type":"string","format":"uri","description":"Deep link to the project's Rankings tab."},"addServiceUrl":{"type":"string","format":"uri","description":"Opens the \"Add our SEO service\" plan picker on the project (upgrade to the managed service)."},"plan":{"$ref":"#/components/schemas/SoftwarePlanStatus"},"ownerUserId":{"type":"string","format":"uuid","description":"The account the project landed under: the key holder, or the team member whose software subscription the account pools into."}},"required":["dashboardUrl","addServiceUrl","plan","ownerUserId"]}]},"KeywordRanking":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"keyword":{"type":"string"},"location":{"type":"string"},"location_code":{"type":"integer"},"target_url":{"type":["string","null"]},"device":{"type":"string"},"language_code":{"type":"string"},"desktop_position":{"type":["integer","null"]},"mobile_position":{"type":["integer","null"]},"ai_mode_position":{"type":["integer","null"]},"maps_position":{"type":["integer","null"]},"desktop_url":{"type":["string","null"]},"mobile_url":{"type":["string","null"]},"ai_mode_url":{"type":["string","null"]},"maps_url":{"type":["string","null"]},"featured_snippet":{"type":"boolean"},"local_pack_position":{"type":["integer","null"]},"monthly_search_volume":{"type":["integer","null"]},"net_change":{"type":"integer","description":"Net position change across all devices. Positive means improvement."},"tags":{"type":"array","items":{"type":"string"}},"last_checked":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"required":["id","keyword","location","location_code","target_url","device","language_code","desktop_position","mobile_position","ai_mode_position","maps_position","desktop_url","mobile_url","ai_mode_url","maps_url","featured_snippet","local_pack_position","monthly_search_volume","net_change","tags","last_checked","created_at"]},"KeywordHistory":{"type":"object","properties":{"keyword_id":{"type":"string","format":"uuid"},"keyword":{"type":"string"},"location":{"type":"string"},"location_code":{"type":"integer"},"history":{"type":"array","items":{"$ref":"#/components/schemas/PositionHistoryEntry"}},"summary":{"type":"object","properties":{"total_data_points":{"type":"integer"},"date_range":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]},"best_position":{"$ref":"#/components/schemas/DevicePositions"},"worst_position":{"$ref":"#/components/schemas/DevicePositions"}},"required":["total_data_points","date_range","best_position","worst_position"]}},"required":["keyword_id","keyword","location","location_code","history","summary"]},"PositionHistoryEntry":{"type":"object","properties":{"date":{"type":"string","format":"date"},"desktop_position":{"type":["integer","null"]},"mobile_position":{"type":["integer","null"]},"ai_mode_position":{"type":["integer","null"]},"maps_position":{"type":["integer","null"]},"featured_snippet":{"type":"boolean"},"local_pack_position":{"type":["integer","null"]}},"required":["date","desktop_position","mobile_position","ai_mode_position","maps_position","featured_snippet","local_pack_position"]},"DevicePositions":{"type":"object","properties":{"desktop":{"type":["integer","null"]},"mobile":{"type":["integer","null"]},"ai_mode":{"type":["integer","null"]},"maps":{"type":["integer","null"]}},"required":["desktop","mobile","ai_mode","maps"]},"Prompt":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"prompt":{"type":"string"},"target_location":{"type":"string"},"ai_models":{"type":"array","items":{"type":"string"}},"brand_name":{"type":["string","null"]},"visibility_percentage":{"type":"number"},"average_position":{"type":"number"},"best_model":{"type":["string","null"]},"ai_search_volume":{"type":["integer","null"]},"total_citations":{"type":"integer"},"latest_responses":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ModelResponse"}},"last_checked":{"type":["string","null"],"format":"date-time"},"last_analyzed":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"required":["id","prompt","target_location","ai_models","brand_name","visibility_percentage","average_position","best_model","ai_search_volume","total_citations","latest_responses","last_checked","last_analyzed","created_at"]},"PromptDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"prompt":{"type":"string"},"target_location":{"type":"string"},"ai_models":{"type":"array","items":{"type":"string"}},"brand_name":{"type":["string","null"]},"visibility_percentage":{"type":"number"},"average_position":{"type":"number"},"best_model":{"type":["string","null"]},"ai_search_volume":{"type":["integer","null"]},"total_citations":{"type":"integer"},"latest_responses":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ModelResponse"}},"last_checked":{"type":["string","null"],"format":"date-time"},"last_analyzed":{"type":["string","null"],"format":"date-time"},"last_volume_update":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"required":["id","prompt","target_location","ai_models","brand_name","visibility_percentage","average_position","best_model","ai_search_volume","total_citations","latest_responses","last_checked","last_analyzed","last_volume_update","created_at"]},"ModelResponse":{"type":"object","properties":{"is_visible":{"type":"boolean"},"position":{"type":["integer","null"]},"citations_count":{"type":"integer"},"response_excerpt":{"type":["string","null"]}},"required":["is_visible","position","citations_count","response_excerpt"]},"PromptHistory":{"type":"object","properties":{"prompt_id":{"type":"string","format":"uuid"},"prompt":{"type":"string"},"responses":{"type":"array","items":{"$ref":"#/components/schemas/PromptHistoryEntry"}}},"required":["prompt_id","prompt","responses"]},"PromptHistoryEntry":{"type":"object","properties":{"model":{"type":"string"},"is_visible":{"type":"boolean"},"position":{"type":["integer","null"]},"citations_count":{"type":"integer"},"citations":{"type":"array","items":{"type":"object"}},"response_excerpt":{"type":["string","null"],"maxLength":500},"checked_at":{"type":"string","format":"date-time"}},"required":["model","is_visible","position","citations_count","citations","response_excerpt","checked_at"]},"AuditSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"target_url":{"type":"string"},"status":{"type":"string","enum":["pending","crawling","processing","completed","failed"]},"crawl_progress":{"type":"number"},"pages_crawled":{"type":"integer"},"total_issues":{"type":"integer"},"critical_issues":{"type":"integer"},"warning_issues":{"type":"integer"},"notice_issues":{"type":"integer"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"required":["id","target_url","status","crawl_progress","pages_crawled","total_issues","critical_issues","warning_issues","notice_issues","started_at","completed_at","created_at"]},"AuditDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"target_url":{"type":"string"},"status":{"type":"string"},"crawl_progress":{"type":"number"},"pages_crawled":{"type":"integer"},"pages_in_queue":{"type":"integer"},"total_issues":{"type":"integer","description":"Active (non-dismissed) issues only."},"critical_issues":{"type":"integer"},"warning_issues":{"type":"integer"},"notice_issues":{"type":"integer"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"issues_summary":{"type":"object","properties":{"passed":{"type":"integer","description":"Dismissed issue count."},"failed":{"type":"integer","description":"Active issue count."},"total":{"type":"integer","description":"Total issues including dismissed."}},"required":["passed","failed","total"]}},"required":["id","target_url","status","crawl_progress","pages_crawled","pages_in_queue","total_issues","critical_issues","warning_issues","notice_issues","started_at","completed_at","created_at","issues_summary"]},"AuditIssue":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"severity":{"type":"string","enum":["critical","warning","notice"]},"title":{"type":"string"},"description":{"type":["string","null"]},"affected_count":{"type":"integer"},"status":{"type":"string","enum":["passed","failed"],"description":"Dismissed issues are marked as `passed`."},"created_at":{"type":"string","format":"date-time"}},"required":["id","type","severity","title","description","affected_count","status","created_at"]},"BacklinkOverview":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"target_domain":{"type":"string"},"target_type":{"type":"string"},"total_backlinks":{"type":"integer"},"total_referring_domains":{"type":"integer"},"domain_rank":{"type":"integer"},"domain_trust":{"type":["number","null"]},"spam_score":{"type":["number","null"]},"dofollow_backlinks":{"type":"integer"},"nofollow_backlinks":{"type":"integer"},"broken_backlinks":{"type":"integer"},"last_checked":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"required":["id","target_domain","target_type","total_backlinks","total_referring_domains","domain_rank","domain_trust","spam_score","dofollow_backlinks","nofollow_backlinks","broken_backlinks","last_checked","created_at"]},"BacklinksSummary":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid"},"total_backlinks":{"type":"integer"},"total_referring_domains":{"type":"integer"},"average_domain_rank":{"type":"integer"},"dofollow_backlinks":{"type":"integer"},"nofollow_backlinks":{"type":"integer"},"broken_backlinks":{"type":"integer"},"tracked_domains_count":{"type":"integer"},"last_updated":{"type":["string","null"],"format":"date-time"}},"required":["project_id","total_backlinks","total_referring_domains","average_domain_rank","dofollow_backlinks","nofollow_backlinks","broken_backlinks","tracked_domains_count","last_updated"]},"ReferringDomain":{"type":"object","properties":{"referring_domain":{"type":"string"},"domain_rank":{"type":"integer"},"backlinks_count":{"type":"integer"},"status":{"type":"string"},"first_seen":{"type":["string","null"],"format":"date-time"},"last_seen":{"type":["string","null"],"format":"date-time"},"lost_date":{"type":["string","null"],"format":"date-time"},"anchor_text":{"type":["string","null"]},"page_title":{"type":["string","null"]},"referring_page_url":{"type":["string","null"]},"is_dofollow":{"type":"boolean"},"is_redirect":{"type":["boolean","null"]},"platform_type":{"type":["string","null"]},"country_iso_code":{"type":["string","null"]},"target_domain":{"type":"string"}},"required":["referring_domain","domain_rank","backlinks_count","status","first_seen","last_seen","lost_date","anchor_text","page_title","referring_page_url","is_dofollow","is_redirect","platform_type","country_iso_code","target_domain"]},"BacklinkHistoryResponse":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid"},"history":{"type":"array","items":{"$ref":"#/components/schemas/BacklinkHistoryEntry"}},"summary":{"type":"object","properties":{"total_data_points":{"type":"integer"},"date_range":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]},"net_backlinks_change":{"type":"integer"},"net_domains_change":{"type":"integer"}},"required":["total_data_points","date_range","net_backlinks_change","net_domains_change"]}},"required":["project_id","history","summary"]},"BacklinkHistoryEntry":{"type":"object","properties":{"date":{"type":"string","format":"date"},"target_domain":{"type":"string"},"new_backlinks":{"type":"integer"},"lost_backlinks":{"type":"integer"},"new_referring_domains":{"type":"integer"},"lost_referring_domains":{"type":"integer"},"net_backlinks_change":{"type":"integer"},"net_domains_change":{"type":"integer"}},"required":["date","target_domain","new_backlinks","lost_backlinks","new_referring_domains","lost_referring_domains","net_backlinks_change","net_domains_change"]},"AnchorsResponse":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid"},"anchors":{"type":"array","items":{"$ref":"#/components/schemas/AnchorTextStats"}},"total_backlinks_analyzed":{"type":"integer"}},"required":["project_id","anchors","total_backlinks_analyzed"]},"AnchorTextStats":{"type":"object","properties":{"anchor_text":{"type":"string"},"count":{"type":"integer"},"percentage":{"type":"number"},"dofollow_count":{"type":"integer"},"nofollow_count":{"type":"integer"},"average_domain_rank":{"type":"integer"}},"required":["anchor_text","count","percentage","dofollow_count","nofollow_count","average_domain_rank"]},"ContentItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["string","null"]},"scheduled_date":{"type":["string","null"],"format":"date"},"due_date":{"type":["string","null"],"format":"date"},"status":{"type":["string","null"]},"status_color":{"type":["string","null"]},"content_type":{"type":["string","null"]},"content_type_color":{"type":["string","null"]},"priority":{"type":"integer"},"document_url":{"type":["string","null"]},"source_url":{"type":["string","null"]},"featured_image_url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}},"required":["id","title","description","scheduled_date","due_date","status","status_color","content_type","content_type_color","priority","document_url","source_url","featured_image_url","created_at","updated_at"]},"ContentDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["string","null"]},"scheduled_date":{"type":["string","null"],"format":"date"},"due_date":{"type":["string","null"],"format":"date"},"status":{"type":["string","null"]},"status_color":{"type":["string","null"]},"content_type":{"type":["string","null"]},"content_type_color":{"type":["string","null"]},"priority":{"type":"integer"},"document_url":{"type":["string","null"]},"source_url":{"type":["string","null"]},"featured_image_url":{"type":["string","null"]},"content_body":{"type":["string","null"]},"meta_data":{"type":["object","null"],"additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}},"required":["id","title","description","scheduled_date","due_date","status","status_color","content_type","content_type_color","priority","document_url","source_url","featured_image_url","content_body","meta_data","created_at","updated_at"]},"ContentPreferences":{"type":"object","properties":{"preferences":{"type":["string","null"]},"publishing_preferences":{"type":["string","null"]},"auto_publish":{"type":"boolean"},"gbp_posting":{"type":"boolean"}},"required":["preferences","publishing_preferences","auto_publish","gbp_posting"]},"UpdateContentPreferencesRequest":{"type":"object","properties":{"preferences":{"type":"string","maxLength":10000,"description":"Content generation preferences."},"publishing_preferences":{"type":"string","maxLength":10000,"description":"Publishing preferences."}},"description":"At least one of `preferences` or `publishing_preferences` must be provided."},"ReportLink":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"report_id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"date_range":{"type":"string"},"start_date":{"type":["string","null"],"format":"date"},"end_date":{"type":["string","null"],"format":"date"},"share_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}},"required":["id","report_id","title","description","date_range","start_date","end_date","share_url","created_at","updated_at"]},"ReportDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"report_id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"date_range":{"type":"string"},"start_date":{"type":["string","null"],"format":"date"},"end_date":{"type":["string","null"],"format":"date"},"share_url":{"type":"string","format":"uri"},"config":{"type":"object","properties":{"include_rankings":{"type":"boolean"},"include_audits":{"type":"boolean"},"include_prompts":{"type":"boolean"},"include_backlinks":{"type":"boolean"},"include_content":{"type":"boolean"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}},"required":["id","report_id","title","description","date_range","start_date","end_date","share_url","config","created_at","updated_at"]},"CreateReportRequest":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"date_range":{"type":"string","enum":["7days","30days","90days","custom"]},"custom_start_date":{"type":"string","format":"date","description":"Required when `date_range` is `custom`."},"custom_end_date":{"type":"string","format":"date","description":"Required when `date_range` is `custom`."},"config":{"type":"object","properties":{"include_rankings":{"type":"boolean","default":true},"include_audits":{"type":"boolean","default":true},"include_prompts":{"type":"boolean","default":true},"include_backlinks":{"type":"boolean","default":true},"include_content":{"type":"boolean","default":true}}}},"required":["title","date_range"]},"CreateReportResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"report_id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"share_url":{"type":"string","format":"uri"},"date_range":{"type":"string"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"created_at":{"type":"string","format":"date-time"}},"required":["id","report_id","title","description","share_url","date_range","start_date","end_date","created_at"]},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"is_active":{"type":"boolean"},"last_triggered_at":{"type":["string","null"],"format":"date-time"},"last_success_at":{"type":["string","null"],"format":"date-time"},"last_failure_at":{"type":["string","null"],"format":"date-time"},"failure_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}},"required":["id","project_id","name","url","events","is_active","last_triggered_at","last_success_at","last_failure_at","failure_count","created_at"]},"WebhookDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"is_active":{"type":"boolean"},"last_triggered_at":{"type":["string","null"],"format":"date-time"},"last_success_at":{"type":["string","null"],"format":"date-time"},"last_failure_at":{"type":["string","null"],"format":"date-time"},"failure_count":{"type":"integer"},"consecutive_failures":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}},"required":["id","project_id","name","url","events","is_active","last_triggered_at","last_success_at","last_failure_at","failure_count","consecutive_failures","created_at","updated_at"]},"WebhookWithSecret":{"type":"object","description":"Webhook with the signing secret. The secret is only returned once at creation time.","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"is_active":{"type":"boolean"},"last_triggered_at":{"type":["string","null"],"format":"date-time"},"last_success_at":{"type":["string","null"],"format":"date-time"},"last_failure_at":{"type":["string","null"],"format":"date-time"},"failure_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"HMAC signing secret. Store securely; it is only returned at creation."}},"required":["id","project_id","name","url","events","is_active","last_triggered_at","last_success_at","last_failure_at","failure_count","created_at","secret"]},"WebhookEvent":{"type":"string","enum":["content.created","content.updated","content.scheduled","content.status_changed","audit.completed","audit.started","keywords.updated","prompts.updated"]},"CreateWebhookRequest":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"url":{"type":"string","format":"uri","description":"Must use HTTPS. Cannot point to private/internal addresses."},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"},"minItems":1}},"required":["project_id","url","events"]},"UpdateWebhookRequest":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri","description":"Must use HTTPS."},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"},"minItems":1},"is_active":{"type":"boolean"}}},"TestWebhookResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"status_code":{"type":"integer","description":"HTTP status code returned by the webhook endpoint."}},"required":["success","message"]}}}}