{"openapi":"3.1.0","info":{"title":"SE Ranking (BYOK) API","version":"0.1.0","description":"SE Ranking (BYOK) lets an AI assistant read your own SE Ranking data through the SE Ranking API with a key you supply (SE Ranking API key). Read-only: 12 tools (list_projects, list_project_search_engines, list_keywords, get_project_summary, get_keyword_positions, get_position_checkpoints, list_competitors, get_competitor_positions, get_serp_top10, get_top_ranking_domains, list_keyword_groups,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-seranking.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-seranking/docs"},"termsOfService":"https://connectorbay.com/byok-seranking/terms"},"servers":[{"url":"https://byok-seranking.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-seranking/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 the rank-tracking projects (websites) in the account with their id, title, domain, group, check frequency, depth an","description":"List the rank-tracking projects (websites) in the account with their id, title, domain, group, check frequency, depth and keyword count. Use for \"Which websites am I tracking rankings for in SE Ranking\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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_project_search_engines":{"post":{"operationId":"list_project_search_engines","summary":"List the search engine configurations of one project: engine id, region, language, maps and paid-result tracking, and ke","description":"List the search engine configurations of one project: engine id, region, language, maps and paid-result tracking, and keyword count. Use for \"Which search engines and regions is project 123 tracked in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Numeric id of the rank-tracking project (take it from list_projects).","minimum":1,"title":"Site Id","type":"integer"}},"required":["site_id"],"title":"list_project_search_enginesArguments","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 keywords tracked in a project with keyword id, text, group, target URL and first check date. Pass site_engine_i","description":"List the keywords tracked in a project with keyword id, text, group, target URL and first check date. Pass site_engine_id to get first_check_date. Use for \"Which keywords are tracked in project 123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Numeric id of the rank-tracking project (take it from list_projects).","minimum":1,"title":"Site Id","type":"integer"},"site_engine_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Id of one search engine configuration inside the project (take it from list_project_search_engines). Leave out for all of them.","title":"Site Engine Id"}},"required":["site_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_project_summary":{"post":{"operationId":"get_project_summary","summary":"Get headline rank-tracker numbers for a project: average position today and yesterday, ups and downs, keywords in the to","description":"Get headline rank-tracker numbers for a project: average position today and yesterday, ups and downs, keywords in the top 5, 10 and 30, visibility and Google index count. Use for \"How is project 123 doing in rankings overall\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Numeric id of the rank-tracking project (take it from list_projects).","minimum":1,"title":"Site Id","type":"integer"}},"required":["site_id"],"title":"get_project_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/get_keyword_positions":{"post":{"operationId":"get_keyword_positions","summary":"Get ranking positions per keyword and day for a project over a period, grouped by search engine configuration. Optionall","description":"Get ranking positions per keyword and day for a project over a period, grouped by search engine configuration. Optionally filter to keywords in the top N at the last check and include landing pages or SERP features. Use for \"What were my keyword positions in project 123 last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Numeric id of the rank-tracking project (take it from list_projects).","minimum":1,"title":"Site Id","type":"integer"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as YYYY-MM-DD. The service defaults to one week before today.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as YYYY-MM-DD. The service defaults to today.","title":"Date To"},"site_engine_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Id of one search engine configuration inside the project (take it from list_project_search_engines). Leave out for all of them.","title":"Site Engine Id"},"in_top":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Keep only keywords ranking in the top N at the last check of the period, for example 10.","title":"In Top"},"with_landing_pages":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"1 to include the landing page URLs found in results, 0 or leave out to skip them.","title":"With Landing Pages"},"with_serp_features":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"1 to include detected Google SERP features, 0 or leave out to skip them.","title":"With Serp Features"}},"required":["site_id"],"title":"get_keyword_positionsArguments","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_position_checkpoints":{"post":{"operationId":"get_position_checkpoints","summary":"Get the closest ranking check dates for current, one day, 7, 30, 90 and 180 days ago and the first check, used to compar","description":"Get the closest ranking check dates for current, one day, 7, 30, 90 and 180 days ago and the first check, used to compare positions over time. Use for \"Which dates can I compare rankings between for project 123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Numeric id of the rank-tracking project (take it from list_projects).","minimum":1,"title":"Site Id","type":"integer"},"site_engine_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Id of one search engine configuration inside the project (take it from list_project_search_engines). Leave out for all of them.","title":"Site Engine Id"}},"required":["site_id"],"title":"get_position_checkpointsArguments","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_competitors":{"post":{"operationId":"list_competitors","summary":"List the competitors added to a project with competitor id, name, URL and domain trust. Use for \"Which competitors does ","description":"List the competitors added to a project with competitor id, name, URL and domain trust. Use for \"Which competitors does project 123 track\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Numeric id of the rank-tracking project (take it from list_projects).","minimum":1,"title":"Site Id","type":"integer"}},"required":["site_id"],"title":"list_competitorsArguments","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_competitor_positions":{"post":{"operationId":"get_competitor_positions","summary":"Get a competitor's ranking positions over a period for the keywords of the project, grouped by search engine configurati","description":"Get a competitor's ranking positions over a period for the keywords of the project, grouped by search engine configuration. Use for \"How did competitor 55 rank last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"competitor_id":{"description":"Competitor id from list_competitors.","minimum":1,"title":"Competitor Id","type":"integer"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as YYYY-MM-DD. The service defaults to one week before today.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as YYYY-MM-DD. The service defaults to today.","title":"Date To"},"site_engine_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Id of one search engine configuration inside the project (take it from list_project_search_engines). Leave out for all of them.","title":"Site Engine Id"}},"required":["competitor_id"],"title":"get_competitor_positionsArguments","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_serp_top10":{"post":{"operationId":"get_serp_top10","summary":"Get the top 10 results (URL, position, backlinks, referring domains) for one tracked keyword on a given check date. Use ","description":"Get the top 10 results (URL, position, backlinks, referring domains) for one tracked keyword on a given check date. Use for \"Who ranked in the top 10 for keyword 4843813 on 2026-10-10\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Numeric id of the rank-tracking project (take it from list_projects).","minimum":1,"title":"Site Id","type":"integer"},"date":{"description":"Check date as YYYY-MM-DD.","maxLength":200,"title":"Date","type":"string"},"site_engine_id":{"description":"Search engine configuration id.","minimum":1,"title":"Site Engine Id","type":"integer"},"keyword_id":{"description":"Tracked keyword id from list_keywords.","minimum":1,"title":"Keyword Id","type":"integer"}},"required":["site_id","date","site_engine_id","keyword_id"],"title":"get_serp_top10Arguments","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_top_ranking_domains":{"post":{"operationId":"get_top_ranking_domains","summary":"List the domains that rank in the top 10 for the project's tracked keywords on a date, with visibility, backlinks and re","description":"List the domains that rank in the top 10 for the project's tracked keywords on a date, with visibility, backlinks and referring domains. Only the last 14 days are stored. Use for \"Which domains dominate the top 10 for project 123 today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Numeric id of the rank-tracking project (take it from list_projects).","minimum":1,"title":"Site Id","type":"integer"},"date":{"description":"Check date as YYYY-MM-DD (within the last 14 days).","maxLength":200,"title":"Date","type":"string"},"site_engine_id":{"description":"Search engine configuration id.","minimum":1,"title":"Site Engine Id","type":"integer"},"group_id":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only keywords of this keyword group id.","title":"Group Id"}},"required":["site_id","date","site_engine_id"],"title":"get_top_ranking_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/list_keyword_groups":{"post":{"operationId":"list_keyword_groups","summary":"List the keyword groups of a project with id, name and creation date. Use for \"What keyword groups does project 123 have","description":"List the keyword groups of a project with id, name and creation date. Use for \"What keyword groups does project 123 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Numeric id of the rank-tracking project (take it from list_projects).","minimum":1,"title":"Site Id","type":"integer"}},"required":["site_id"],"title":"list_keyword_groupsArguments","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_search_console_queries":{"post":{"operationId":"get_search_console_queries","summary":"Get the popular Google Search Console queries linked to a project with impressions, clicks, click-through rate and avera","description":"Get the popular Google Search Console queries linked to a project with impressions, clicks, click-through rate and average position. Use for \"Which search queries bring clicks to project 123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Numeric id of the rank-tracking project (take it from list_projects).","minimum":1,"title":"Site Id","type":"integer"}},"required":["site_id"],"title":"get_search_console_queriesArguments","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}}}}