{"openapi":"3.1.0","info":{"title":"Ranked AI (BYOK) API","version":"0.1.0","description":"Ranked AI (BYOK) lets an AI assistant read your own Ranked AI data through the Ranked AI API with a key you supply (Ranked AI API key (rk_live_..., Read Only permission is enough)). Read-only: 12 tools (list_projects, list_keywords, get_keyword_history, list_prompts, list_audits, get_latest_audit, list_audit_issues, list_backlink_targets, get_backlink_summary, list_referring_domains,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-ranked-ai.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-ranked-ai/docs"},"termsOfService":"https://connectorbay.com/byok-ranked-ai/terms"},"servers":[{"url":"https://byok-ranked-ai.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-ranked-ai/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_projects":{"post":{"operationId":"list_projects","summary":"List your Ranked AI SEO projects with name, status, service type, website and access (owner or team). Use for \"Which SEO","description":"List your Ranked AI SEO projects with name, status, service type, website and access (owner or team). Use for \"Which SEO projects do I have in Ranked AI\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum items to return (default 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip (default 0).","title":"Offset"},"product_mode":{"anyOf":[{"enum":["managed","software"],"type":"string"},{"type":"null"}],"default":null,"description":"managed or software (legacy self-serve).","title":"Product Mode"}},"title":"list_projectsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_keywords":{"post":{"operationId":"list_keywords","summary":"List the tracked keywords of a project with Google positions on desktop, mobile, AI Mode and Maps, target URL, search vo","description":"List the tracked keywords of a project with Google positions on desktop, mobile, AI Mode and Maps, target URL, search volume, net change and tags. Use for \"How do my keywords rank in Ranked AI project 40596405\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Ranked AI project id (UUID) from list_projects.","maxLength":60,"title":"Project Id","type":"string"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum items to return (default 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip (default 0).","title":"Offset"},"date_from":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Start of date range (ISO 8601, for example 2026-09-01).","title":"Date From"},"date_to":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"End of date range (ISO 8601, for example 2026-09-30).","title":"Date To"},"device":{"anyOf":[{"enum":["all","desktop","mobile"],"type":"string"},{"type":"null"}],"default":null,"description":"all (default), desktop or mobile.","title":"Device"}},"required":["project_id"],"title":"list_keywordsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_keyword_history":{"post":{"operationId":"get_keyword_history","summary":"Get the daily position history of one tracked keyword across desktop, mobile, AI Mode and Maps, with best and worst posi","description":"Get the daily position history of one tracked keyword across desktop, mobile, AI Mode and Maps, with best and worst positions. Use for \"How did keyword kw-1 move over the last month in Ranked AI\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Ranked AI project id (UUID) from list_projects.","maxLength":60,"title":"Project Id","type":"string"},"keyword_id":{"description":"Keyword id (UUID) from list_keywords.","maxLength":60,"title":"Keyword Id","type":"string"},"date_from":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Start of date range (ISO 8601, for example 2026-09-01).","title":"Date From"},"date_to":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"End of date range (ISO 8601, for example 2026-09-30).","title":"Date To"}},"required":["project_id","keyword_id"],"title":"get_keyword_historyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_prompts":{"post":{"operationId":"list_prompts","summary":"List the AI search prompts tracked for a project with visibility percentage, average position, best model, search volume","description":"List the AI search prompts tracked for a project with visibility percentage, average position, best model, search volume and citations. Use for \"How visible is my brand in AI answers for Ranked AI project 40596405\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Ranked AI project id (UUID) from list_projects.","maxLength":60,"title":"Project Id","type":"string"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum items to return (default 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip (default 0).","title":"Offset"}},"required":["project_id"],"title":"list_promptsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_audits":{"post":{"operationId":"list_audits","summary":"List the site audits of a project with target URL, status, pages crawled and issue counts by severity. Use for \"What sit","description":"List the site audits of a project with target URL, status, pages crawled and issue counts by severity. Use for \"What site audits ran for Ranked AI project 40596405\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Ranked AI project id (UUID) from list_projects.","maxLength":60,"title":"Project Id","type":"string"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum items to return (default 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip (default 0).","title":"Offset"},"status":{"anyOf":[{"enum":["all","pending","crawling","processing","completed","failed"],"type":"string"},{"type":"null"}],"default":null,"description":"Only audits with this status.","title":"Status"}},"required":["project_id"],"title":"list_auditsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_latest_audit":{"post":{"operationId":"get_latest_audit","summary":"Get the most recent completed site audit of a project with issue counts and passed and failed check totals. Use for \"Wha","description":"Get the most recent completed site audit of a project with issue counts and passed and failed check totals. Use for \"What did the latest site audit of Ranked AI project 40596405 find\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Ranked AI project id (UUID) from list_projects.","maxLength":60,"title":"Project Id","type":"string"}},"required":["project_id"],"title":"get_latest_auditArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_audit_issues":{"post":{"operationId":"list_audit_issues","summary":"List the issues found by a site audit sorted by severity with title, description and number of affected pages. Use for \"","description":"List the issues found by a site audit sorted by severity with title, description and number of affected pages. Use for \"What are the critical issues in Ranked AI audit au-1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Ranked AI project id (UUID) from list_projects.","maxLength":60,"title":"Project Id","type":"string"},"audit_id":{"description":"Audit id (UUID) from list_audits.","maxLength":60,"title":"Audit Id","type":"string"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum items to return (default 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip (default 0).","title":"Offset"},"severity":{"anyOf":[{"enum":["all","critical","warning","notice"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this severity.","title":"Severity"},"status":{"anyOf":[{"enum":["all","passed","failed"],"type":"string"},{"type":"null"}],"default":null,"description":"Only passed or failed checks.","title":"Status"}},"required":["project_id","audit_id"],"title":"list_audit_issuesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_backlink_targets":{"post":{"operationId":"list_backlink_targets","summary":"List the tracked backlink targets (domains) of a project with total backlinks, referring domains, domain rank, trust and","description":"List the tracked backlink targets (domains) of a project with total backlinks, referring domains, domain rank, trust and spam score. Use for \"What is the backlink profile of Ranked AI project 40596405\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Ranked AI project id (UUID) from list_projects.","maxLength":60,"title":"Project Id","type":"string"}},"required":["project_id"],"title":"list_backlink_targetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_backlink_summary":{"post":{"operationId":"get_backlink_summary","summary":"Get aggregated backlink metrics for a project: totals, referring domains, average domain rank and dofollow, nofollow and","description":"Get aggregated backlink metrics for a project: totals, referring domains, average domain rank and dofollow, nofollow and broken counts. Use for \"How many backlinks does Ranked AI project 40596405 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Ranked AI project id (UUID) from list_projects.","maxLength":60,"title":"Project Id","type":"string"}},"required":["project_id"],"title":"get_backlink_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_referring_domains":{"post":{"operationId":"list_referring_domains","summary":"List the domains linking to a project with domain rank, number of backlinks, status, first and last seen, anchor text an","description":"List the domains linking to a project with domain rank, number of backlinks, status, first and last seen, anchor text and whether the link is dofollow. Use for \"Which domains link to Ranked AI project 40596405\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Ranked AI project id (UUID) from list_projects.","maxLength":60,"title":"Project Id","type":"string"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum items to return (default 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip (default 0).","title":"Offset"},"status":{"anyOf":[{"enum":["all","active","lost"],"type":"string"},{"type":"null"}],"default":null,"description":"all, active or lost.","title":"Status"},"sort_by":{"anyOf":[{"enum":["domain_rank","backlinks_count","first_seen","last_seen"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field (default domain_rank).","title":"Sort By"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc (default desc).","title":"Sort Order"}},"required":["project_id"],"title":"list_referring_domainsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_backlink_history":{"post":{"operationId":"get_backlink_history","summary":"Get daily counts of new and lost backlinks and referring domains over a date range. Use for \"How many backlinks did Rank","description":"Get daily counts of new and lost backlinks and referring domains over a date range. Use for \"How many backlinks did Ranked AI project 40596405 gain last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Ranked AI project id (UUID) from list_projects.","maxLength":60,"title":"Project Id","type":"string"},"date_from":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Start of date range (ISO 8601, for example 2026-09-01).","title":"Date From"},"date_to":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"End of date range (ISO 8601, for example 2026-09-30).","title":"Date To"}},"required":["project_id"],"title":"get_backlink_historyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_content":{"post":{"operationId":"list_content","summary":"List the content calendar items of a project with title, status, type, scheduled and due dates and document link. Use fo","description":"List the content calendar items of a project with title, status, type, scheduled and due dates and document link. Use for \"What content is planned in Ranked AI project 40596405\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Ranked AI project id (UUID) from list_projects.","maxLength":60,"title":"Project Id","type":"string"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum items to return (default 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip (default 0).","title":"Offset"},"date_from":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Start of date range (ISO 8601, for example 2026-09-01).","title":"Date From"},"date_to":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"End of date range (ISO 8601, for example 2026-09-30).","title":"Date To"},"status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only this status name, for example Draft or Published.","title":"Status"}},"required":["project_id"],"title":"list_contentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}