Endpoint catalog

RankWatch API surface — platform, SEO, and AEO.

All paths are relative to /api/v1/public. Full schemas live in the API reference.

Platform

Account & usage

Method	Path	Scope
`GET`	`/account`	(any valid key)
`GET`	`/account/usage/credits`	`usage:read`
`GET`	`/account/limits`	`usage:read`

Workspaces

Method	Path	Scope
`GET`	`/workspaces`	`workspaces:read`
`GET`	`/workspaces/{workspace_id}`	`workspaces:read`

workspace_id is a UUID returned by the API.

Projects

Method	Path	Scope	Notes
`GET`	`/workspaces/{workspace_id}/projects`	`projects:read`	List (query: `page`, `page_size`, `tracking_status`)
`POST`	`/workspaces/{workspace_id}/projects`	`projects:write`	Create tracking-ready project (`setups`); requires `Idempotency-Key`
`POST`	`/workspaces/{workspace_id}/projects/list`	`projects:read`	Preferred — body: `page`, `page_size`, `include_contexts`, `tracking_status` (`all` default, `active`, `paused`)
`POST`	`/workspaces/{workspace_id}/projects/get`	`projects:read`	Body: `project_id`, `include_contexts` (default true)
`GET`	`/workspaces/{workspace_id}/projects/{project_id}`	`projects:read`	Single project
`GET`	`/workspaces/{workspace_id}/projects/{project_id}/status`	`projects:read`	Processing progress; poll until `ready`
`GET`	`/workspaces/{workspace_id}/projects/{project_id}/data-range`	`rankings:read`	Available rank dates (`context_id` is a UUID)
`POST`	`/workspaces/{workspace_id}/projects/{project_id}/keywords`	`keywords:write`	Add keywords/prompts to a context
`POST`	`/workspaces/{workspace_id}/projects/{project_id}/keywords/batch`	`keywords:write`	Batch add
`DELETE`	`/workspaces/{workspace_id}/projects/{project_id}/keywords`	`keywords:write`	Remove from tracking by `tracking_ids`
`PATCH`	`/workspaces/{workspace_id}/projects/{project_id}/keywords/frequency`	`keywords:write`	Change frequency
`POST`	`/workspaces/{workspace_id}/projects/{project_id}/tracking/pause`	`projects:write`	Pause all active jobs
`POST`	`/workspaces/{workspace_id}/projects/{project_id}/tracking/resume`	`projects:write`	Resume paused jobs

GET /config/engines returns the public engine/device/frequency catalog for create-project and deep-dive.

Project and context ids are UUIDs. Prefer POST endpoints with JSON bodies where documented.

tracking_status on project list: all (default), active (every rank job active), or paused (includes mixed partial projects). Each project still returns tracking_status of active, paused, partial, or none.

Tools

Tool jobs use hyphenated slugs under /workspaces/{workspace_id}/tools/{tool_slug}/jobs. See Tools jobs.

SEO

SEO endpoints require an SEO search context_id (from projects/get → contexts[].kind === "seo").

Keywords

keywords/list returns tracked items for a project (SEO and AI contexts).
keywords/table and keywords/get are for SEO contexts. For AI contexts, use the AEO prompts endpoints.

keywords/get is a compact snapshot + history. keywords/detail is the integration contract for a single keyword: rank snapshot, SERP features, daily history, economics, and organic competitor landscape.

Method	Path	Scope	Body highlights
`POST`	`/workspaces/{workspace_id}/keywords/list`	`keywords:read`	`project_id`, optional `context_id`, `page`, `lifecycle`, `q`
`POST`	`/workspaces/{workspace_id}/keywords/table`	`rankings:read`	SEO context + `latest` or `start_date`/`end_date`
`POST`	`/workspaces/{workspace_id}/keywords/get`	`rankings:read`	`project_id`, `context_id`, `tracking_id`, `latest` or dates
`POST`	`/workspaces/{workspace_id}/keywords/detail`	`rankings:read`	Full SEO keyword view (snapshot, SERP, history, competitors)

Competitors (overview + keyword gap)

List competitor domains with metrics (scope=selected or scope=all), or compare ranks to up to 5 domains in keyword gap. Always paginated (page_size max 100).

Method	Path	Scope	Body highlights
`POST`	`/workspaces/{workspace_id}/competitors/selections`	`competitors:read`	SEO `context_id` — selected domains
`POST`	`/workspaces/{workspace_id}/competitors/overview`	`competitors:read`	dates, `scope` (`selected` default / `all`), `page` / `page_size`
`POST`	`/workspaces/{workspace_id}/competitors/keyword-gap`	`competitors:read`	`domains` (1–5), dates, `page` / `page_size`, optional `kpi_filter`
`POST`	`/workspaces/{workspace_id}/competitors/keyword-gap/kpi-counts`	`competitors:read`	Same domains/dates — `gap_weak`, `you_lead`, `contested`, `total`

AI contexts must use the AEO prompt-gap endpoints (PUBLIC_API_USE_PROMPT_GAP).

AEO

AEO (AI Engine Optimization) endpoints require an AI context_id (contexts[].kind === "ai").

Prompts

prompts/get is a compact AI snapshot + history. prompts/detail is the full latest-run payload: answer markdown, citations, mentioned brands and products (including retailer listings and prices).

Method	Path	Scope	Body highlights
`POST`	`/workspaces/{workspace_id}/prompts/table`	`rankings:read`	AI context + `latest` or dates
`POST`	`/workspaces/{workspace_id}/prompts/get`	`rankings:read`	AI context + `tracking_id` + dates/`latest`
`POST`	`/workspaces/{workspace_id}/prompts/detail`	`rankings:read`	Full AI prompt view (answer, citations, brands, products, prices)

Competitors (overview + prompt gap)

List rival brands with mention/citation metrics (scope=selected or scope=all), or compare prompt-by-prompt to up to 5 brands. Always paginated (page_size max 100).

Method	Path	Scope	Body highlights
`POST`	`/workspaces/{workspace_id}/competitors/prompt-selections`	`competitors:read`	`project_id` — selected brands (project-scoped)
`POST`	`/workspaces/{workspace_id}/competitors/prompt-overview`	`competitors:read`	AI `context_id`, dates, `scope` (`selected` default / `all`), `page` / `page_size`
`POST`	`/workspaces/{workspace_id}/competitors/prompt-gap`	`competitors:read`	`brands` (1–5), AI `context_id`, dates, `page` / `page_size`
`POST`	`/workspaces/{workspace_id}/competitors/prompt-gap/kpi-counts`	`competitors:read`	Same brands/dates — `you_lag`, `you_lead`, `contested`, `sentiment_behind`, `total`

SEO contexts must use the SEO keyword-gap endpoints (PUBLIC_API_USE_KEYWORD_GAP).

Conventions

Success responses include request_id, api_version, and platform_version
Errors: { "error", "code", "details"? }
Collections use named arrays (projects, workspaces, …) plus pagination fields
Gap pagination: { page, page_size, total, total_pages, has_more }