{"openapi":"3.1.0","info":{"title":"RankControl API","version":"1.0.0","description":"The REST API behind the RankControl dashboard, CLI, and MCP server. Authenticate every request with an API key as a Bearer header; keys are minted in Settings > API and carry scopes (see each operation's x-required-scope). Full docs: https://rctrl.com/docs/api. MCP endpoint for AI agents: https://api.rctrl.com/mcp (OAuth 2.1, see https://rctrl.com/docs/mcp).","contact":{"email":"help@rctrl.com","url":"https://rctrl.com/contact"},"termsOfService":"https://rctrl.com/terms"},"servers":[{"url":"https://api.rctrl.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Settings > API, e.g. `Authorization: Bearer rctrl_pk_...`"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}},"paths":{"/api/v1/analytics/activate":{"post":{"operationId":"activate_analytics_screen","summary":"Turn on the Analytics or Reports screen for this workspace (they ship disabled; activation is one-time per screen).","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"screen":{"type":"string","enum":["analytics","reports"]}},"required":["screen"]}}}}}},"/api/v1/analytics/engagement":{"get":{"operationId":"get_page_engagement","summary":"Per-page engagement for the last 30 days: views, AI citations, and a view sparkline per published page.","description":"Requires the `read:analytics` scope.","x-required-scope":"read:analytics","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/rankings":{"get":{"operationId":"get_rankings_","summary":"Verified Google and Bing positions per keyword (top 30), with Search Console clicks, impressions and average position when connected (gscPosition is an average over the searches you appeared in, never a rank), which page earned each query and whether it is one of your articles (isOurs), and how often Google's AI Overview shows above each keyword and cites one of your pages (a rate over the last 8 weekly checks). Defaults to queries your published articles appear for.","description":"Requires the `read:analytics` scope.","x-required-scope":"read:analytics","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","description":"\"ours\" (default): queries your published articles appear for. \"site\": everything on the domain, including pages RankControl did not write."}}]}},"/api/v1/analytics/sources":{"get":{"operationId":"get_analytics_sources","summary":"Per-workspace analytics source setup: the selected writer for human traffic and AI-crawler data, which sources the setup qualifies for, and install state (Cloudflare zone/sync, WordPress plugin version, embed liveness). Both Analytics and Reports screens ship disabled until activated.","description":"Requires the `read:analytics` scope.","x-required-scope":"read:analytics","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"set_analytics_source","summary":"Select the active writer for a data type. Validated server-side against what the customer's setup supports. Switching aiCrawlers to cloudflare starts a backfill sync.","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dataType":{"type":"string","enum":["humanTraffic","aiCrawlers"]},"source":{"type":"string","description":"embed, wordpress_plugin, cloudflare or none"}},"required":["dataType","source"]}}}}}},"/api/v1/analytics/traffic":{"get":{"operationId":"get_traffic_overview","summary":"Traffic overview from RankControl's own page analytics: total page views, unique visitors, sessions, bounce rate, and average time on page.","description":"Requires the `read:analytics` scope.","x-required-scope":"read:analytics","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"string","enum":["7","30","90"],"description":"Window in days, default 30"}}]}},"/api/v1/articles":{"get":{"operationId":"get_articles","summary":"Read articles","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/auth/device/poll":{"post":{"operationId":"post_auth_device_poll","summary":"auth device poll","description":"Requires the `public` scope.","x-required-scope":"public","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/auth/device/start":{"post":{"operationId":"post_auth_device_start","summary":"auth device start","description":"Requires the `public` scope.","x-required-scope":"public","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/backlinks":{"get":{"operationId":"list_backlinks","summary":"The workspace's backlink table, newest first. Each row carries its source (index, outreach, managed, network).","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"Filter: discovered, verified, lost, placed, identified, contacted, replied, link_placed, rejected"}}]}},"/api/v1/backlinks/stats":{"get":{"operationId":"get_backlink_stats","summary":"Backlink totals (live, lost, avg DA, unique domains) plus outreach pipeline counts.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/brand":{"get":{"operationId":"get_brand","summary":"The workspace's brand data in one read: brand profile (voice, colors, meta), links/CTAs, products, and buyer profiles (ICPs). This is the context RankControl's writers use.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"update_brand_identity","summary":"Update workspace identity: name, industry, productDescription, authors (EEAT bylines used in article JSON-LD), styleReferenceUrls (articles whose writing style the writer imitates), brandAliases (other spellings and short forms of the brand; pages using them count as brand mentions) and brandExclusions (same-name companies or products whose pages are skipped). Every array REPLACES the stored list — call get_brand first and send the full updated list. Saving a name change runs the brand-mention search once a day at most. websiteUrl is immutable and cannot be changed.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":20,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"industry":{"type":"string"},"productDescription":{"type":"string"},"authors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"bio":{"type":"string"},"linkedinUrl":{"type":"string","description":"Person sameAs URL for article JSON-LD"}},"required":["name"]}},"styleReferenceUrls":{"type":"array","items":{"type":"string"}},"brandAliases":{"type":"array","items":{"type":"string"}},"brandExclusions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v1/brand/icp":{"post":{"operationId":"write_brand_icp","summary":"Create, update, or delete a buyer profile / ICP (feeds article targeting + entity triples). Create: title+industry+demographics. Update: profileId + changed fields. Delete: profileId + del=true.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":20,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"profileId":{"type":"string"},"del":{"type":"boolean"},"title":{"type":"string"},"industry":{"type":"string"},"companySize":{"type":"string"},"painPoints":{"type":"array","items":{"type":"string"}},"buyingTriggers":{"type":"array","items":{"type":"string"}},"objections":{"type":"array","items":{"type":"string"}},"preferredChannels":{"type":"array","items":{"type":"string"}},"demographics":{"type":"object","description":"Demographics object; required on create (same shape the dashboard saves)","additionalProperties":true},"isActive":{"type":"boolean"}}}}}}}},"/api/v1/brand/icp/draft":{"post":{"operationId":"draft_brand_icp","summary":"Draft one buyer profile from a one-sentence description or a suggestion from suggest_brand_icps. Returns the fields to review; nothing is saved until write_brand_icp. Fields passed in given are kept as written.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"describe":{"type":"string","description":"Who the audience is, in one sentence"},"title":{"type":"string","description":"Title of a suggestion from suggest_brand_icps"},"who":{"type":"string","description":"The suggestion's one-line description"},"given":{"type":"object","description":"Fields to keep as written (same keys as write_brand_icp, plus ageRange, seniority, department as strings). A key you pass is kept, empty included; a key you leave out is filled.","additionalProperties":true}}}}}}}},"/api/v1/brand/icp/suggest":{"post":{"operationId":"suggest_brand_icps","summary":"Suggest up to 8 audiences for this site from its brand, products, competitors and topics. Saves nothing. Pick one and pass it to draft_brand_icp, or write your own with write_brand_icp.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"exclude":{"type":"array","items":{"type":"string","description":"Audience titles already shown, to get different ones"}}}}}}}}},"/api/v1/brand/product":{"post":{"operationId":"write_brand_product","summary":"Create, update, or delete a product in brand memory (feeds article context + entity triples). Create: name+description+category. Update: productId + changed fields. Delete: productId + del=true.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":20,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"del":{"type":"boolean"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"features":{"type":"array","items":{"type":"string"}},"pricing":{"type":"string"},"category":{"type":"string"},"usps":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}}}}}}}},"/api/v1/brand/profile":{"post":{"operationId":"update_brand_profile","summary":"Patch brand voice/style fields: tone, colors, fontFamily, metaTitle/Description/Keywords, defaultLocale, flexibleScheduling. Only provided fields change; they steer all future article generation.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":20,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tone":{"type":"string"},"primaryColor":{"type":"string"},"secondaryColor":{"type":"string"},"fontFamily":{"type":"string"},"metaTitle":{"type":"string"},"metaDescription":{"type":"string"},"metaKeywords":{"type":"string"},"defaultLocale":{"type":"string","description":"BCP-47 tag from the supported registry"},"flexibleScheduling":{"type":"boolean"}}}}}}}},"/api/v1/citations":{"get":{"operationId":"list_citations","summary":"Recent AI citation checks: which tracked queries were checked on which AI model and whether the brand was cited.","description":"Requires the `read:citations` scope.","x-required-scope":"read:citations","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"model","in":"query","required":false,"schema":{"type":"string","description":"Filter by AI model, e.g. chatgpt, perplexity"}},{"name":"limit","in":"query","required":false,"schema":{"type":"number","maximum":200}}]}},"/api/v1/competitors":{"get":{"operationId":"get_competitors","summary":"Tracked competitors used in share-of-voice and visibility comparisons, with each one's AI visibility score, citations of checks over the last 30 days, domain metrics and positioning analysis.","description":"Requires the `read:citations` scope.","x-required-scope":"read:citations","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"add_competitor","summary":"Track a competitor (max 10). They enter weekly share-of-voice comparisons against the org's own citation rate. Omit websiteUrl to have the site resolved from the name.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Competitor name"},"websiteUrl":{"type":"string","description":"Competitor website URL (optional; resolved from the name when omitted)"}},"required":["name"]}}}}}},"/api/v1/competitors/remove":{"post":{"operationId":"remove_competitor","summary":"Stop tracking a competitor.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"competitorId":{"type":"string","description":"Competitor id from get_competitors"}},"required":["competitorId"]}}}}}},"/api/v1/content":{"get":{"operationId":"list_content","summary":"List content pages in the workspace with their status (planned, draft, published).","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/content/archive":{"post":{"operationId":"archive_content","summary":"Archive an article, removing it from the working set. Reversible in the dashboard.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentId":{"type":"string"}},"required":["contentId"]}}}}}},"/api/v1/content/delete-planned":{"post":{"operationId":"delete_planned_title","summary":"Remove a planned title from the content calendar. The title's keyword returns to Content Ideas as a saved query, so the topic is not lost. Only planned rows qualify; use archive for generated articles.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":20,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentId":{"type":"string","description":"Planned contentPage id"}},"required":["contentId"]}}}}}},"/api/v1/content/generate":{"post":{"operationId":"generate_article","summary":"Write a PLANNED article's body immediately instead of waiting for the scheduled pipeline (generate-only: its publish slot is unchanged). Allowed for past-due slots and up to 3 days ahead, and at most 5 articles in any 24 hours (the dry run reports withinDailyLimit and nextWriteAt). Defaults to a DRY RUN; a human should approve before calling again with confirm=true since generation is costly.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentId":{"type":"string","description":"The planned content page id"},"confirm":{"type":"boolean","description":"Set true to actually start generation (default: dry run)"}},"required":["contentId"]}}}}}},"/api/v1/content/ideas":{"get":{"operationId":"get_content_ideas","summary":"Scored content-idea backlog: uncovered tracked queries ranked by citation gaps, competitor citations, trending topics, and quick-win rankings. Each idea carries a suggested title and winnability metrics.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/content/ideas/hide":{"post":{"operationId":"hide_content_idea","summary":"Hide an idea from Content Ideas. A tracked query keeps its weekly checks and its slot; use remove_tracked_query to delete a query outright.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queryId":{"type":"string","description":"Idea id from get_content_ideas"}},"required":["queryId"]}}}}}},"/api/v1/content/ideas/plan":{"post":{"operationId":"plan_content_idea","summary":"Put a content idea on the calendar as a planned article. Pass the idea's queryText (and its suggested title if you have it — otherwise a title is generated).","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queryText":{"type":"string","description":"The idea's keyword/query text"},"title":{"type":"string","description":"Exact headline to plan"}},"required":["queryText"]}}}}}},"/api/v1/content/internal-links":{"get":{"operationId":"get_internal_links","summary":"How the workspace's articles interlink: how many published articles link TO this page (with the source list) and how many internal links it sends out. Recorded from the real injected links at publish render time.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"contentId","in":"query","required":true,"schema":{"type":"string","description":"The content page id"}}]}},"/api/v1/content/optimizer":{"get":{"operationId":"get_citability_report","summary":"Published pages ranked by citability score (how extractable each page is for AI answers), worst first, each with its top open fixes. Use to decide which articles to improve.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"number","maximum":100,"description":"Max rows, default 25"}}]}},"/api/v1/content/plan":{"post":{"operationId":"plan_content","summary":"Generate candidate article titles (capacity-gated). This DOES NOT put anything on the calendar: review the returned titles, then call commit_planned_titles with the keepers. Costly; capped at 5/min.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"topics":{"type":"array","items":{"type":"string"},"description":"Brand topics to focus on; omit for auto"},"contentTypes":{"type":"array","items":{"type":"string"}},"maxDifficulty":{"type":"number","minimum":0,"maximum":100,"description":"Keyword-difficulty ceiling"},"intents":{"type":"array","items":{"type":"string"},"description":"informational / commercial / transactional"},"useCitationGaps":{"type":"boolean","description":"Target queries where AI cites competitors but not us"},"useRankingGaps":{"type":"boolean","description":"Target keywords ranking page 2-3 or slipping"}}}}}}}},"/api/v1/content/plan/commit":{"post":{"operationId":"commit_planned_titles","summary":"Approve reviewed titles onto the content calendar (the approval half of the plan→commit gate). Pass rejected candidates in `discarded` so their keywords recycle into Content Ideas.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"titles":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"targetKeyword":{"type":"string"},"searchVolume":{"type":"number"},"keywordDifficulty":{"type":"number"},"searchIntent":{"type":"string"}},"required":["title"]},"description":"Titles to schedule"},"discarded":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"targetKeyword":{"type":"string"},"searchVolume":{"type":"number"},"keywordDifficulty":{"type":"number"},"searchIntent":{"type":"string"}},"required":["title"]},"description":"Rejected candidates"}},"required":["titles"]}}}}}},"/api/v1/content/planning-capacity":{"get":{"operationId":"get_planning_capacity","summary":"How many article titles can still be planned onto the content calendar within the scheduling horizon. Check before plan_content.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/content/publish":{"post":{"operationId":"publish_content","summary":"Publish an article to the customer's connected CMS. Defaults to a DRY RUN describing what would happen; a human should approve before calling again with confirm=true. Delivery runs after this call returns. If the article does not go live, list_content shows its lastPublishError. Webhook receivers: https://rctrl.com/docs/webhook","description":"Requires the `write:publish` scope.","x-required-scope":"write:publish","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentId":{"type":"string","description":"The content page id"},"confirm":{"type":"boolean","description":"Set true to actually publish (default: dry run)"}},"required":["contentId"]}}}}}},"/api/v1/content/reschedule":{"post":{"operationId":"reschedule_article","summary":"Move a PLANNED article to another day (requires the flexible schedule; max 5/day; the exact hour is placed automatically). Pass the target day as YYYY-MM-DD in the workspace's timezone.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":20,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentId":{"type":"string"},"date":{"type":"string","description":"Target day as YYYY-MM-DD in the workspace's timezone"}},"required":["contentId","date"]}}}}}},"/api/v1/crawler-access":{"get":{"operationId":"get_crawler_access","summary":"Daily AI-crawler reachability probe result — a DIAGNOSTIC, not a traffic metric: whether the site's edge (e.g. Cloudflare Bot Fight Mode) or robots.txt blocks GPTBot/ClaudeBot. 'shielded' means browsers and bots are both challenged (site-wide shield, ambiguous for real, signed crawlers).","description":"Requires the `read:analytics` scope.","x-required-scope":"read:analytics","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/expedition":{"get":{"operationId":"get_setup_progress","summary":"First-run setup progress for the workspace: five acts from first article live through analytics, each with per-step completion, plus the current act. Use to tell the user what remains to finish setting up.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integrations/cloudflare/connect-url":{"post":{"operationId":"get_cloudflare_connect_url","summary":"OAuth URL to connect read-only Cloudflare analytics (AI-crawler data source). Open it in a browser; the grant is scoped to Analytics:Read.","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integrations/cloudflare/zone":{"post":{"operationId":"select_cloudflare_zone","summary":"Pick the Cloudflare zone to poll. Also selects Cloudflare as the AI-crawler source and starts the first sync (backfills up to 7 days).","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zoneId":{"type":"string"},"zoneName":{"type":"string","description":"Zone name, e.g. example.com"}},"required":["zoneId","zoneName"]}}}}}},"/api/v1/integrations/cloudflare/zones":{"get":{"operationId":"list_cloudflare_zones","summary":"Cloudflare zones visible to the connected grant, for picking which zone to poll.","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integrations/framer/install-embed":{"post":{"operationId":"install_framer_embed","summary":"Install site-wide visit tracking on the connected Framer project via its custom-code API. Dry run unless confirm is true. Confirming ALSO PUBLISHES the customer's Framer site.","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"integrationId":{"type":"string"},"confirm":{"type":"boolean","description":"Actually install (default: dry run)"}}}}}}}},"/api/v1/integrations/webflow/custom-code":{"post":{"operationId":"install_webflow_custom_code","summary":"Register and apply the tracking loader via Webflow's Custom Code API. Dry run unless confirm is true. Needs a site token with CMS + Custom code scopes (pass apiToken to upgrade the stored one). Goes live on the customer's next Webflow site publish.","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"integrationId":{"type":"string"},"apiToken":{"type":"string","description":"New site token with CMS + Custom code scopes"},"confirm":{"type":"boolean","description":"Actually install (default: dry run)"}}}}}}}},"/api/v1/jobs":{"get":{"operationId":"list_jobs","summary":"Recent agent runs (job status feed). Async actions like content planning show up here with their outputs.","description":"Requires the `read:analytics` scope.","x-required-scope":"read:analytics","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"number","maximum":100}}]}},"/api/v1/link-network":{"get":{"operationId":"get_link_network","summary":"Editorial Circle state: credit balance/earn/spend, membership (optedIn), and hosted/received placements with partners and anchors.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/link-network/opt-in":{"post":{"operationId":"set_link_network_opt_in","summary":"Join or leave the Editorial Circle. SIDE EFFECT on partner sites (leaving retires live links): defaults to a DRY RUN; a human should approve before calling again with confirm=true.","description":"Requires the `write:backlinks` scope.","x-required-scope":"write:backlinks","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"optIn":{"type":"boolean"},"confirm":{"type":"boolean"}},"required":["optIn"]}}}}}},"/api/v1/link-network/remove-placement":{"post":{"operationId":"remove_network_placement","summary":"Retire one Editorial Circle placement. VISIBLE on the partner site: defaults to a DRY RUN; call again with confirm=true after human approval.","description":"Requires the `write:backlinks` scope.","x-required-scope":"write:backlinks","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"placementId":{"type":"string"},"confirm":{"type":"boolean"}},"required":["placementId"]}}}}}},"/api/v1/links/detect":{"post":{"operationId":"detect_site_links","summary":"Scan the customer's sitemap (nested indexes handled) or crawl a blog root page and return same-site page URLs, minus the articles RankControl published (those are linked already). The source is remembered and re-read daily. Costly (3/min); review the URLs, then call add_site_pages with the keepers.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":3,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["sitemap","blogroot"]},"url":{"type":"string","description":"Sitemap XML URL or a page URL to crawl"}},"required":["source","url"]}}}}}},"/api/v1/links/pages":{"get":{"operationId":"list_site_pages","summary":"Site pages RankControl links to from inside articles and the Related Reading block (with linkable/alive flags).","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"add_site_pages","summary":"Add site page URLs for internal linking. Duplicates and articles RankControl published are skipped; page titles fill in automatically in the background.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string"}}},"required":["urls"]}}}}}},"/api/v1/outreach/draft-reply":{"post":{"operationId":"draft_outreach_reply","summary":"AI-draft the next reply in an outreach conversation where the prospect has responded (replySnippet present on the prospect). Returns subject/body only — nothing sends; follow with queue_outreach_email to send it.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"backlinkId":{"type":"string","description":"Prospect id from list_outreach_prospects"}},"required":["backlinkId"]}}}}}},"/api/v1/outreach/find-contact":{"post":{"operationId":"find_outreach_contact","summary":"Find an outreach email for one prospect site. Returns the stored contact or found:false. Capped at 5/min.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"backlinkId":{"type":"string","description":"Prospect id from list_outreach_prospects"}},"required":["backlinkId"]}}}}}},"/api/v1/outreach/prospects":{"get":{"operationId":"list_outreach_prospects","summary":"Link outreach pipeline: prospect sites per published article with status (identified → contacted → replied → link placed), Domain Rating (dr, with drSource ahrefs; dataforseo marks an authority estimate for a domain Ahrefs has no number for) and any contact email already found.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/outreach/queue":{"post":{"operationId":"queue_outreach_email","summary":"Queue an outreach email to a prospect. It sends from the workspace's own connected mailbox, paced automatically with a daily cap. Uses the stored draft unless subject/body are given; a \"[Your name]\" sign-off in the draft is replaced with the owner's profile name at send time. Dry-run unless confirm is true — a confirmed queue leads to a REAL email being sent.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"backlinkId":{"type":"string","description":"Prospect id from list_outreach_prospects"},"subject":{"type":"string","description":"Override the drafted subject"},"body":{"type":"string","description":"Override the drafted body"},"confirm":{"type":"boolean","description":"Set true to actually queue the send"}},"required":["backlinkId"]}}}}}},"/api/v1/outreach/stats":{"get":{"operationId":"get_outreach_stats","summary":"Outreach funnel for the last 90 days by how each prospect was found (intersection = competitor linkers, footprint = resource pages, mention = topical mentions, fresh = fresh competitor links, brand_mention = brand mentions, legacy = earlier rows): prospects, sent, replied and placed with reply and placement rates per send, plus the total. The harvest reads the same numbers to weight its methods; nothing to configure.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/outreach/status":{"post":{"operationId":"update_outreach_status","summary":"Move an outreach prospect through the pipeline. A move to link_placed is confirmed by reading their page now and again tomorrow; the row keeps Placed and shows what was seen.","description":"Requires the `write:backlinks` scope.","x-required-scope":"write:backlinks","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"backlinkId":{"type":"string"},"status":{"type":"string","enum":["identified","contacted","replied","link_placed","rejected"]}},"required":["backlinkId","status"]}}}}}},"/api/v1/overview/funnel":{"get":{"operationId":"get_overview_funnel","summary":"AI pipeline overview for the last 30 days: AI crawler hits and visits referred by AI engines.","description":"Requires the `read:analytics` scope.","x-required-scope":"read:analytics","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/queries":{"get":{"operationId":"list_tracked_queries","summary":"The workspace's tracked queries — the questions RankControl checks weekly across the 6 AI engines for brand citations — with their status and metadata.","description":"Requires the `read:citations` scope.","x-required-scope":"read:citations","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"add_tracked_query","summary":"Add a query. Weekly AI citation checks start immediately when a tracking slot is free; otherwise it is saved untracked. Pass coveredByContentId when the query is a question an existing article already answers, so Content Ideas does not offer it again.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queryText":{"type":"string","description":"The search/AI query to track"},"coveredByContentId":{"type":"string","description":"contentPage id of the article that already answers this query"}},"required":["queryText"]}}}}}},"/api/v1/queries/remove":{"post":{"operationId":"remove_tracked_query","summary":"Delete a query. Frees its tracking slot if it was tracked.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":20,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queryId":{"type":"string","description":"Query id from get_tracked_queries"}},"required":["queryId"]}}}}}},"/api/v1/queries/set-tracking":{"post":{"operationId":"set_query_tracking","summary":"Pause or resume weekly AI citation checks on a saved query. Tracking uses one of the plan's tracking slots; pausing frees it. The query is kept either way.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":20,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queryId":{"type":"string","description":"Query id from get_tracked_queries"},"tracked":{"type":"boolean","description":"true to track weekly, false to pause"}},"required":["queryId","tracked"]}}}}}},"/api/v1/queries/update":{"post":{"operationId":"update_tracked_query","summary":"Rewrite a tracked query's text. Future weekly checks use the new text.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":20,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queryId":{"type":"string","description":"Query id from get_tracked_queries"},"queryText":{"type":"string","description":"New query text (min 5 characters)"}},"required":["queryId","queryText"]}}}}}},"/api/v1/reports/agent-activity":{"get":{"operationId":"get_agent_activity","summary":"Recent pipeline runs per agent lane (brand control, radar, forge, recon, deploy, outreach, sentinel, social).","description":"Requires the `read:analytics` scope.","x-required-scope":"read:analytics","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"perAgent","in":"query","required":false,"schema":{"type":"number","maximum":50,"description":"Runs per lane, default 15"}},{"name":"sinceDays","in":"query","required":false,"schema":{"type":"number","description":"Window in days, default 30"}}]}},"/api/v1/reports/summary":{"get":{"operationId":"get_exec_summary","summary":"Executive report: last 30 days vs the 30 before — cite rate, citations, page views, AI-referred views, crawler hits, and articles published.","description":"Requires the `read:analytics` scope.","x-required-scope":"read:analytics","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/reports/wins":{"get":{"operationId":"get_top_wins","summary":"Biggest wins of the last 30 days: most-cited page, best query cite-rate jump, biggest Google ranking climb, best new backlink.","description":"Requires the `read:analytics` scope.","x-required-scope":"read:analytics","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/repurpose":{"get":{"operationId":"list_repurpose_queue","summary":"Published articles with their social repurpose drafts per platform (platform + status chips). Shows which articles still need drafts and which scheduler is connected (Buffer or Postiz).","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/repurpose/channels":{"get":{"operationId":"list_postiz_channels","summary":"Connected social channels across Postiz and Buffer (scheduler, id, name, platform). Channel ids are required by push_repurpose_draft.","description":"Requires the `write:social` scope.","x-required-scope":"write:social","x-rate-limit-per-minute":3,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/repurpose/draft":{"post":{"operationId":"update_repurpose_draft","summary":"Edit a repurpose draft's body and/or title before pushing or posting.","description":"Requires the `write:social` scope.","x-required-scope":"write:social","x-rate-limit-per-minute":20,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"},"body":{"type":"string"},"title":{"type":"string"}},"required":["draftId"]}}}}}},"/api/v1/repurpose/generate":{"post":{"operationId":"generate_repurpose_drafts","summary":"Draft platform-native social posts for a published article. Only for an article with no drafts yet; edit or dismiss existing drafts in the dashboard. Defaults to a DRY RUN; confirm=true generates (costly).","description":"Requires the `write:social` scope.","x-required-scope":"write:social","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentId":{"type":"string"},"platforms":{"type":"array","items":{"type":"string","enum":["linkedin","twitter","pinterest","instagram","facebook","threads","youtube","tiktok"]},"description":"Subset of platforms; omit for the workspace default"},"confirm":{"type":"boolean"}},"required":["contentId"]}}}}}},"/api/v1/repurpose/mark-posted":{"post":{"operationId":"mark_repurpose_posted","summary":"Mark a repurpose draft as posted — use after publishing its text manually (outside Buffer or Postiz).","description":"Requires the `write:social` scope.","x-required-scope":"write:social","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"}},"required":["draftId"]}}}}}},"/api/v1/repurpose/push":{"post":{"operationId":"push_repurpose_draft","summary":"Send a repurpose draft to a connected scheduler's channels: Postiz or Buffer (post now, schedule, save as a draft, or add to Buffer's queue). PUBLICLY VISIBLE side effect: defaults to a DRY RUN; a human should approve before calling again with confirm=true.","description":"Requires the `write:social` scope.","x-required-scope":"write:social","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"},"scheduler":{"type":"string","enum":["postiz","buffer"],"description":"Which scheduler; required when both are connected"},"integrationIds":{"type":"array","items":{"type":"string"},"description":"Channel ids from list_postiz_channels (required with confirm)"},"scheduleType":{"type":"string","enum":["now","schedule","draft","queue"],"description":"Default now; queue is Buffer only"},"date":{"type":"string","description":"ISO time for scheduleType=schedule"},"confirm":{"type":"boolean"}},"required":["draftId"]}}}}}},"/api/v1/settings/articles":{"get":{"operationId":"get_article_settings","summary":"The workspace article policy: per-article defaults (auto-write, auto-publish, images, title-in-hero, section infographics, Related Reading, YouTube, emojis, link counts, global instructions) plus the flexible-scheduling flag. News and trending articles always publish manually, regardless of auto-publish.","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"update_article_settings","summary":"Merge-patch the article policy: only the fields you pass change. Set flexibleScheduling true to allow 1-5 articles/day and manual rescheduling. styleSet picks the image style set applied to all generated images (heroes, infographic panels, social cards).","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"articleSettings":{"type":"object","properties":{"autoPublish":{"type":"boolean"},"autoGenerate":{"type":"boolean","description":"Off = fully manual mode: articles are written only on demand (generate_article) and publish only from the editor. Turning it on needs a publishing destination that has already put at least one article live on the site."},"includeInfographics":{"type":"boolean","description":"AI hero + section images"},"titleInHeroImage":{"type":"boolean","description":"Write the post title into the hero image"},"includeSectionInfographics":{"type":"boolean","description":"Informational panels in 2,000+ word articles"},"includeRelatedReading":{"type":"boolean","description":"Related Reading link block at the end"},"includeYouTube":{"type":"boolean"},"useEmojis":{"type":"boolean"},"internalLinksPerArticle":{"type":"number","minimum":1,"maximum":20},"externalLinksPerArticle":{"type":"number","minimum":0,"maximum":15},"globalInstructions":{"type":"string"}}},"flexibleScheduling":{"type":"boolean"},"styleSet":{"type":"string","enum":["editorial","cinematic","documentary","studio","conceptual-metaphor","editorial-illustration","clay-3d","isometric","line-art-minimal","dark-gradient-glass","travel-poster","watercolor-wash","retro-futurism","ukiyo-e","paper-diorama","gouache-metaphor","minimalist","riso-print","pop-art","corporate-flat","memphis","bauhaus-poster","flat-vector","cartoon-creator","soft-anime"],"description":"The org's image style: one of the 25 styles — every generated hero uses it (each style rotates through its approved title-look pool)"}}}}}}}},"/api/v1/social":{"get":{"operationId":"list_social_threads","summary":"Social thread prospects (Reddit/X) where the brand's articles could earn a mention, with subreddit rules context, sorted by intent.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["reddit","twitter"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"age","in":"query","required":false,"schema":{"type":"string","enum":["ranked","new"]}}]}},"/api/v1/social/draft-reply":{"post":{"operationId":"draft_social_reply","summary":"AI-draft a reply for a social thread. Nothing posts — the draft lands on the thread for human review. Subject to the same warm-up/pacing guards as the dashboard.","description":"Requires the `write:social` scope.","x-required-scope":"write:social","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"threadId":{"type":"string"},"mentionMode":{"type":"string","enum":["none","natural","founderOpen"],"description":"Brand-mention mode; warm-up accounts are clamped to none"}},"required":["threadId"]}}}}}},"/api/v1/social/open":{"post":{"operationId":"open_social_thread","summary":"Open a drafted social thread to post the reply yourself: returns the thread URL (for X, a link that opens X's composer with the reply filled in) and starts four checks over 72 hours that mark the thread Posted once your reply is found there. Pass text to use an edited reply; X replies must be 280 characters or fewer.","description":"Requires the `write:social` scope.","x-required-scope":"write:social","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"threadId":{"type":"string"},"text":{"type":"string"}},"required":["threadId"]}}}}}},"/api/v1/social/reddit-profile":{"post":{"operationId":"set_reddit_profile","summary":"Save the Reddit account the Social tab drafts for: username (optional), comment karma, account age (under1mo, 1to6mo, 6moto2yr or over2yr), goal, founderStory and tone. Karma and age decide whether drafts may mention your product; the reply returns the readiness tier (warmup or ready). Replaces the stored profile — send every field.","description":"Requires the `write:social` scope.","x-required-scope":"write:social","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string"},"karma":{"type":"number"},"accountAge":{"type":"string","description":"under1mo | 1to6mo | 6moto2yr | over2yr"},"goal":{"type":"string"},"founderStory":{"type":"string"},"tone":{"type":"string"}},"required":["karma","accountAge","goal","founderStory","tone"]}}}}}},"/api/v1/social/stats":{"get":{"operationId":"get_social_stats","summary":"Social thread pipeline counts.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/social/status":{"post":{"operationId":"update_social_thread_status","summary":"Skip a social thread so it leaves the queue (the only manual status; Posted is set automatically once your reply is found in the thread).","description":"Requires the `write:social` scope.","x-required-scope":"write:social","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"threadId":{"type":"string"},"status":{"type":"string"}},"required":["threadId","status"]}}}}}},"/api/v1/social/x-handle":{"post":{"operationId":"set_social_x_handle","summary":"Save the X handle used to recognise your posted replies (optional; text matching covers the rest). Pass an empty handle to clear it.","description":"Requires the `write:social` scope.","x-required-scope":"write:social","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string"}},"required":["handle"]}}}}}},"/api/v1/support":{"post":{"operationId":"contact_support","summary":"Send a message or bug report to the RankControl team (emails support with the workspace identified; the org owner is set as reply-to). Use when an API call errors unexpectedly or data looks wrong — include the failing request, ids, and what you expected. Capped at 3/min.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":3,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string"},"message":{"type":"string","description":"Details: what happened, errors, ids, steps to reproduce"},"pageUrl":{"type":"string","description":"Related dashboard or API URL"}},"required":["subject","message"]}}}}}},"/api/v1/team":{"get":{"operationId":"get_team","summary":"Workspace members and pending invites, with each member's per-screen permission matrix and the seat cap.","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/team/invite":{"post":{"operationId":"invite_team_member","summary":"Invite a member to the workspace with per-screen none/read/write access (unspecified screens default to none — grant at least one). Dry-run unless confirm is true; confirming sends the invite email.","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Invitee email address"},"screenPermissions":{"type":"object","properties":{"overview":{"type":"string","enum":["none","read","write"]},"content":{"type":"string","enum":["none","read","write"]},"visibility":{"type":"string","enum":["none","read","write"]},"brandControl":{"type":"string","enum":["none","read","write"]},"linkControl":{"type":"string","enum":["none","read","write"]},"analytics":{"type":"string","enum":["none","read","write"]},"reports":{"type":"string","enum":["none","read","write"]}}},"confirm":{"type":"boolean","description":"Set true to actually send the invite (default dry-run)"}},"required":["email"]}}}}}},"/api/v1/team/remove":{"post":{"operationId":"remove_team_member","summary":"Remove a member from the workspace (access revoked immediately). Dry-run unless confirm is true.","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","description":"Member user id from get_team"},"confirm":{"type":"boolean"}},"required":["userId"]}}}}}},"/api/v1/team/revoke":{"post":{"operationId":"revoke_team_invite","summary":"Revoke a pending team invite by invitation id (from get_team).","description":"Requires the `manage:org` scope.","x-required-scope":"manage:org","x-rate-limit-per-minute":5,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invitationId":{"type":"string"}},"required":["invitationId"]}}}}}},"/api/v1/topics":{"get":{"operationId":"get_topics","summary":"The org's pillar list (topic clusters). Tracked queries, content ideas and planned articles all group under these.","description":"Requires the `read:content` scope.","x-required-scope":"read:content","x-rate-limit-per-minute":60,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"set_topics","summary":"Replace the FULL pillar list. Send every topic that should exist; missing ones are removed, new ones created, duplicates merged. Read get_topics first and modify that list. Up to 20 topics.","description":"Requires the `write:content` scope.","x-required-scope":"write:content","x-rate-limit-per-minute":10,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topics":{"type":"array","items":{"type":"string"},"description":"The complete list of topic names"}},"required":["topics"]}}}}}},"/api/v1/visibility/footprint":{"get":{"operationId":"get_web_footprint","summary":"Web footprint for the workspace and every competitor it tracks: how much of the web links to each domain, scored 0 to 10. A new domain scoring near zero is why AI citations are still absent.","description":"Requires the `read:citations` scope.","x-required-scope":"read:citations","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/visibility/score":{"get":{"operationId":"get_visibility_score","summary":"Composite AI visibility score for the workspace, blending AI citation rate across the tracked models with Google and Bing rank share. Returns the composite and per-pillar subscores (the AI pillar includes a per-model breakdown).","description":"Requires the `read:citations` scope.","x-required-scope":"read:citations","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/visibility/sentiment":{"get":{"operationId":"get_citation_sentiment","summary":"How AI answers frame the brand when it's cited: positive / neutral / negative counts, daily trend, and recent answer snippets as receipts.","description":"Requires the `read:citations` scope.","x-required-scope":"read:citations","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"number","minimum":7,"maximum":90,"description":"Window in days, default 30"}}]}},"/api/v1/visibility/share-of-voice":{"get":{"operationId":"get_share_of_voice","summary":"Share of voice vs competitors: the brand's citation rate, top competitor mention rates, and the brand's share of all brand appearances in AI answers over the window.","description":"Requires the `read:citations` scope.","x-required-scope":"read:citations","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"number","minimum":7,"maximum":90,"description":"Window in days, default 30"}}]}},"/api/v1/visibility/sources":{"get":{"operationId":"get_citation_sources","summary":"Which domains AI engines cite when answering the brand's tracked queries, typed brand / competitive / UGC / editorial with counts and share. Shows where citation presence must be earned.","description":"Requires the `read:citations` scope.","x-required-scope":"read:citations","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"number","minimum":7,"maximum":90,"description":"Window in days, default 30"}}]}},"/api/v1/visibility/trend":{"get":{"operationId":"get_visibility_trend","summary":"Daily AI visibility score series across the 6 tracked AI engines, from RankControl's stored weekly citation checks.","description":"Requires the `read:citations` scope.","x-required-scope":"read:citations","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"string","enum":["30","60","90"],"description":"Window size in days, default 30"}}]}},"/api/v1/visibility/web-total-history":{"get":{"operationId":"get_web_total_history","summary":"Web total history for the workspace and every competitor it tracks: each domain's monthly web total over the last 3 months, oldest month first. The web total counts citations in ChatGPT and Google answers, including queries you do not track.","description":"Requires the `read:citations` scope.","x-required-scope":"read:citations","x-rate-limit-per-minute":30,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success; the payload is wrapped in a data envelope","content":{"application/json":{"schema":{"type":"object","properties":{"data":{}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; the body includes a retryAfterMs hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}