Docs
API reference
93 endpoints under /api/v1. The OpenAPI document is served by the API at /api/v1/openapi.json.
| Method | Path | Summary | Auth |
|---|---|---|---|
| post | /public/audits | Start a URL-only audit | public |
| get | /public/audits/{id} | Read the safe public result of an audit | result_token |
| get | /me | Current user and workspaces | session |
| post | /projects | Create a project from a public audit | session |
| get | /projects | List projects in the active workspace | session |
| get | /projects/{id} | Read one project | session |
| delete | /projects/{id} | Owner. Remove the project from the workspace: it is archived, its history is kept and it no longer counts toward the plan. Adding the same domain again restores it | session |
| post | /projects/{id}/verification-challenges | Create or return the open DNS TXT challenge of the caller (owner only) | session |
| post | /projects/{id}/verify-domain | Check the DNS TXT record of a challenge (owner only) | session |
| get | /projects/{id}/context | Read the business context, its pending proposals and version list | session |
| patch | /projects/{id}/context | Edit, confirm or remove claims. Each request creates one new version | session |
| get | /projects/{id}/competitors | List the competitor set | session |
| post | /projects/{id}/competitors | Add a competitor, or approve, exclude or reclassify one | session |
| get | /projects/{id}/integrations | List connections with state, selected property and last sync (ADR 0008) | session |
| post | /projects/{id}/integrations | Start a generic connection (owner). Not implemented: use the Google routes | session |
| get | /projects/{id}/audits | Audit history with scores and comparison to the previous audit | session |
| post | /projects/{id}/audits | Start a new audit of the project domain | session |
| get | /projects/{id}/audits/{auditId} | One audit with its check results | session |
| get | /projects/{id}/tracking-targets | Tracking targets, their newest observation, limits and cost estimate | session |
| post | /projects/{id}/tracking-targets | Add, suggest, pin, exclude or remove tracking targets | session |
| get | /projects/{id}/activity | Activity history of a project, newest first | session |
| get | /projects/{id}/opportunities | Ranked opportunity queue with evidence and counts for each status group | session |
| post | /projects/{id}/opportunities/evaluate | Evaluate the stored audit and tracking evidence again. Calls no provider | session |
| get | /projects/{id}/opportunities/{opportunityId} | One opportunity with all its evidence and its decision history | session |
| post | /projects/{id}/opportunities/{opportunityId}/decisions | Defer, ignore, accept as an exception, suppress or reopen, with a reason | session |
| post | /projects/{id}/integrations/google/authorize | Owner. Start Google OAuth for Search Console and GA4 (read-only). No verified domain needed | session |
| get | /integrations/google/callback | OAuth redirect target. Exchanges the code, stores tokens encrypted, redirects to /project | session |
| get | /projects/{id}/integrations/google/properties | Owner. Search Console sites and GA4 properties of the connected account | session |
| post | /projects/{id}/integrations/google/properties | Owner. Select a Search Console site and/or GA4 property. A matching property verifies the domain | session |
| delete | /projects/{id}/integrations/google | Owner. Revoke the Google grant and delete the stored tokens. Synced data stays | session |
| post | /projects/{id}/integrations/{integrationId}/refresh | Queue a sync of one connected source. Rate-limited | session |
| post | /projects/{id}/integrations/github/install | Owner. Link to install the GitHub App, with a signed single-use state. No verified domain needed | session |
| get | /integrations/github/callback | GitHub App setup URL. Checks the state and the installation, records it, redirects to /project | session |
| get | /projects/{id}/integrations/github/repositories | Owner. Repositories the project's installation can see, with the linked one | session |
| post | /projects/{id}/integrations/github/repository | Owner. Link the one Next.js repository and its path allowlist. Not archived, in the installation | session |
| delete | /projects/{id}/integrations/github | Owner. Unlink the installation and repository from the project. The App stays installed on GitHub | session |
| post | /integrations/github/webhook | GitHub webhook. Raw JSON body signed with X-Hub-Signature-256, deduplicated by X-GitHub-Delivery | public |
| get | /projects/{id}/pages | Pages with audit, opportunity, Search Console and GA4 data | session |
| get | /projects/{id}/pages/{pageKey} | One page: metrics, top queries, daily series, opportunities and audit checks | session |
| get | /projects/{id}/queries | Search Console queries with comparison and branded tag. The default view reads the daily sync; other filters fetch live and cache for 24 hours | session |
| get | /projects/{id}/brand-terms | Brand terms that split branded and non-branded queries (defaults until an owner saves) | session |
| put | /projects/{id}/brand-terms | Save the brand terms (owner only). An empty list returns to the defaults | session |
| get | /projects/{id}/tracking/search-console-suggestions | Queries the site already gets clicks or impressions for, not tracked yet, by clicks then impressions | session |
| get | /projects/{id}/integrations/github/file | Owner or member. Read one text file of the linked repository at the default-branch head, for a proposal's before/after view. Allowlisted paths only; binary and files over 200 KB are refused | session |
| post | /projects/{id}/proposals | Owner or member. Draft a change proposal for a proposed opportunity. The route follows from action_class (nextjs_code_change -> github_pr, cms_content_write -> payload_cms, cms_schema_change -> payload_schema). Moves the opportunity to awaiting_approval | session |
| get | /projects/{id}/proposals | Change proposals of the project, newest first | session |
| get | /projects/{id}/proposals/{proposalId} | One proposal: revisions, the current revision's before/after content, decisions, executions and what the signed-in user can do | session |
| post | /projects/{id}/proposals/{proposalId}/revisions | Owner or member. Create a new revision with a new hash. Earlier revisions become superseded and their approvals authorize nothing | session |
| post | /projects/{id}/proposals/{proposalId}/decisions | Signed-in person only. Approve or reject the exact current revision hash with a reason. A stale hash is 409. The author cannot approve their own revision when the workspace has another member; high risk needs an owner | session |
| post | /projects/{id}/proposals/{proposalId}/execute | Signed-in person only. Start the approved current revision: github_pr queues one pull request (never merged). Payload routes answer 501 until the Payload contract exists | session |
| get | /projects/{id}/work-summary | Counts for Today: awaiting approval, ready to execute, in progress, monitoring | session |
| get | /workspace/plan | Plan, project limit and credit balance of the active workspace | session |
| get | /workspace/credits/ledger | Credit ledger of the active workspace, newest first (owners only) | session |
| get | /projects/{id}/autonomy | Autonomy level of the project (review_all, auto_low_risk, auto_all), its last change and what each level lets the policy approve | session |
| patch | /projects/{id}/autonomy | Owner only. Change the autonomy level with a reason; recorded in Activity. Applies to proposals created or revised afterwards: it neither undoes nor adds a decision. The same level again is 409 | session |
| get | /projects/{id}/integrations/cms | CMS connection: endpoint, a hint of the API key (last four characters, never the key), last test, tools with their draft-guard result, enabled tools. Members read; owners manage | session |
| put | /projects/{id}/integrations/cms | Owner. Save the https MCP endpoint and the API key (sealed; required the first time, optional later to keep the stored one). A new endpoint or key clears the tool list and enabled tools | session |
| post | /projects/{id}/integrations/cms/test | Owner. Connect to the saved endpoint with the stored key, list the tools and store the list. A failed test is a 200 result with an error code | session |
| put | /projects/{id}/integrations/cms/tools | Owner. Replace the enabled collection bindings: for each collection, one tool to read a document and one to save a draft, bound to the schema hash of the last test. An empty list switches every collection off. A tool that publishes, deletes or is destructive is refused (400); a stale hash is 409; a collection bound twice or a tool used by two collections is 400. Webtick saves drafts only | session |
| delete | /projects/{id}/integrations/cms | Owner. Delete the sealed API key, the endpoint, the tool list and the enabled tools | session |
| get | /projects/{id}/integrations/keys | Bing Webmaster Tools, PostHog and Microsoft Clarity connections: state, property and a hint of the key (last four characters, never the key). Members read; owners manage | session |
| put | /projects/{id}/integrations/keys/{provider} | Owner. Save the property and, when given, a new key (sealed). The connection becomes untested | session |
| post | /projects/{id}/integrations/keys/{provider}/test | Owner. One read-only request to the service with the stored key. A failed test is a 200 result with ok false | session |
| delete | /projects/{id}/integrations/keys/{provider} | Owner. Delete the sealed key and the property | session |
| get | /projects/{id}/context/generation | Whether AI context generation is configured, its credit estimate, the balance and the latest run | session |
| post | /projects/{id}/context/generation | Owner only. Crawl the website and draft claims with the context model. Credits are reserved before the call; every claim cites a quote found on its page. Never confirms a claim | session |
| get | /projects/{id}/research | Research tools of the project: provider, locales, each tool with its cost estimate in USD and credits, the rate limit and whether the caller may run them. Members read | session |
| post | /projects/{id}/research/requests | Run one research tool. Reserves the estimated credits first (402 INSUFFICIENT_CREDITS), calls the provider, settles the reported cost or releases on failure, and stores the result once. A provider failure or a missing provider plan is a stored result with status failed or not_in_plan, not an error. Rate limited per project (429) | session |
| get | /projects/{id}/research/requests | History of research requests, newest first, without result bodies. Members read | session |
| get | /projects/{id}/research/requests/{requestId} | One stored research request with its result. Reopening it does not call the provider | session |
| get | /projects/{id}/research/competitors | Latest stored intelligence for each approved competitor: organic keywords, estimated traffic, shared keywords with the project and domain rank | session |
| post | /projects/{id}/research/competitors/{competitorId}/refresh | Fetch competitor intelligence for one approved competitor now. Reserves and settles credits like a manual tool | session |
| get | /projects/{id}/research/backlinks | Latest stored backlinks of the project domain, or of one page with ?url= (a URL on the project domain) | session |
| post | /projects/{id}/research/backlinks/refresh | Fetch the backlinks summary of the domain, or the linking domains of one page, now. Reserves and settles credits like a manual tool | session |
| patch | /me | Change the display name of the signed-in user (1 to 80 characters after trimming) | session |
| get | /me/avatar | The signed-in user's avatar: PNG, JPEG or WebP bytes with the stored type, `Cache-Control: private` and `nosniff`. `v` is a version for cache busting. Only the user can read it | session |
| put | /me/avatar | Upload or replace the avatar: a 256 × 256 PNG, JPEG or WebP of at most 200 KB, base64 encoded. The magic bytes must match the declared type; SVG and other types are refused | session |
| delete | /me/avatar | Remove the avatar; the initial is shown again | session |
| patch | /workspace | Owner only. Rename the active workspace (1 to 80 characters); recorded in Activity | session |
| get | /me/deletion | What deleting the account would do now: workspaces deleted with all their data, memberships removed, and workspaces that block deletion | session |
| delete | /me | Delete the signed-in account. The body repeats the account email, and the session must have started within the last 15 minutes. Deletes each workspace where the user is the only active member with all its data (Google access revoked first, best effort), removes other memberships, then the user, sessions and accounts. Refused (409) while the user is the only owner of a workspace with other members | session |
| get | /projects/{id}/tracking/overview | Tracking overview (B-047): summary figures, one row per keyword that joins positions, trend, Search Console (newest daily sync), volume, difficulty, intent and the ranking page, and the AI prompts. Stored data only; no provider or Google call | session |
| get | /projects/{id}/tracking/targets/{targetId} | One tracking target (B-047): position or answer history, the newest sampled results, and the Search Console trend and pages for the same query. Stored data only | session |
| get | /projects/{id}/page-intel | Page intelligence build of the project: provider, estimate of a whole build, the active and the latest build, and recent runs. Members read | session |
| post | /projects/{id}/page-intel/builds | Owner only. Queue a rebuild of the stored keyword, backlink and SERP data of every page. The worker estimates the build, reserves credits, builds the cheap parts and skips SERP previews when credits or the cost cap do not cover them, and settles the reported cost. 402 when the workspace cannot pay even the cheap parts; 409 while a build is queued or running; rate limited per project (429) | session |
| get | /projects/{id}/pages/{pageKey}/intel | Stored ranking keywords, backlinks and SERP preview of one page, each with its fetched time. Never calls the provider | session |
| post | /projects/{id}/pages/{pageKey}/intel/refresh | Owner or member. Refresh the keywords, backlinks and SERP preview of one page now: reserves the estimated credits (402), calls the provider, settles the reported cost or releases on failure, and stores the result. Rate limited per project (429) | session |
| post | /projects/start | Create a project from a domain and start its first audit at once (in-product New project, B-045). A domain that already is a project answers 200 with that project and starts nothing | session |
| get | /projects/{id}/pages/{pageKey}/sources | One page's GA4 traffic by default channel group (with the compared period), top sources / mediums and top referrers, and Search Console clicks as a separate line. The default view reads the daily sync; other filters fetch live and cache for 24 hours | session |
| get | /projects/{id}/pages/{pageKey}/cms | Whether the page maps to a CMS document through the owner's URL rules. Serves the stored lookup for 24 hours; an older or missing one is looked up through the read tool of the matching collection (rate-limited). Read only: nothing is saved in the CMS | session |
| post | /projects/{id}/pages/{pageKey}/cms/check | Look the page up in the CMS again now (Check again). Read only. At most 20 checks per project in 10 minutes | session |
| get | /projects/{id}/integrations/cms/url-rules | URL rules that map page paths to CMS collections and fields, the enabled collections, and suggestions from the site's page paths | session |
| put | /projects/{id}/integrations/cms/url-rules | Owner. Replace the URL rules. Each pattern has literal segments and one {name} segment; the collection must be enabled with a read tool that can find by field; the field is letters, digits and _ | session |