docs
Contents
Docs

API reference

93 endpoints under /api/v1. The OpenAPI document is served by the API at /api/v1/openapi.json.

MethodPathSummaryAuth
post/public/auditsStart a URL-only auditpublic
get/public/audits/{id}Read the safe public result of an auditresult_token
get/meCurrent user and workspacessession
post/projectsCreate a project from a public auditsession
get/projectsList projects in the active workspacesession
get/projects/{id}Read one projectsession
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 itsession
post/projects/{id}/verification-challengesCreate or return the open DNS TXT challenge of the caller (owner only)session
post/projects/{id}/verify-domainCheck the DNS TXT record of a challenge (owner only)session
get/projects/{id}/contextRead the business context, its pending proposals and version listsession
patch/projects/{id}/contextEdit, confirm or remove claims. Each request creates one new versionsession
get/projects/{id}/competitorsList the competitor setsession
post/projects/{id}/competitorsAdd a competitor, or approve, exclude or reclassify onesession
get/projects/{id}/integrationsList connections with state, selected property and last sync (ADR 0008)session
post/projects/{id}/integrationsStart a generic connection (owner). Not implemented: use the Google routessession
get/projects/{id}/auditsAudit history with scores and comparison to the previous auditsession
post/projects/{id}/auditsStart a new audit of the project domainsession
get/projects/{id}/audits/{auditId}One audit with its check resultssession
get/projects/{id}/tracking-targetsTracking targets, their newest observation, limits and cost estimatesession
post/projects/{id}/tracking-targetsAdd, suggest, pin, exclude or remove tracking targetssession
get/projects/{id}/activityActivity history of a project, newest firstsession
get/projects/{id}/opportunitiesRanked opportunity queue with evidence and counts for each status groupsession
post/projects/{id}/opportunities/evaluateEvaluate the stored audit and tracking evidence again. Calls no providersession
get/projects/{id}/opportunities/{opportunityId}One opportunity with all its evidence and its decision historysession
post/projects/{id}/opportunities/{opportunityId}/decisionsDefer, ignore, accept as an exception, suppress or reopen, with a reasonsession
post/projects/{id}/integrations/google/authorizeOwner. Start Google OAuth for Search Console and GA4 (read-only). No verified domain neededsession
get/integrations/google/callbackOAuth redirect target. Exchanges the code, stores tokens encrypted, redirects to /projectsession
get/projects/{id}/integrations/google/propertiesOwner. Search Console sites and GA4 properties of the connected accountsession
post/projects/{id}/integrations/google/propertiesOwner. Select a Search Console site and/or GA4 property. A matching property verifies the domainsession
delete/projects/{id}/integrations/googleOwner. Revoke the Google grant and delete the stored tokens. Synced data stayssession
post/projects/{id}/integrations/{integrationId}/refreshQueue a sync of one connected source. Rate-limitedsession
post/projects/{id}/integrations/github/installOwner. Link to install the GitHub App, with a signed single-use state. No verified domain neededsession
get/integrations/github/callbackGitHub App setup URL. Checks the state and the installation, records it, redirects to /projectsession
get/projects/{id}/integrations/github/repositoriesOwner. Repositories the project's installation can see, with the linked onesession
post/projects/{id}/integrations/github/repositoryOwner. Link the one Next.js repository and its path allowlist. Not archived, in the installationsession
delete/projects/{id}/integrations/githubOwner. Unlink the installation and repository from the project. The App stays installed on GitHubsession
post/integrations/github/webhookGitHub webhook. Raw JSON body signed with X-Hub-Signature-256, deduplicated by X-GitHub-Deliverypublic
get/projects/{id}/pagesPages with audit, opportunity, Search Console and GA4 datasession
get/projects/{id}/pages/{pageKey}One page: metrics, top queries, daily series, opportunities and audit checkssession
get/projects/{id}/queriesSearch Console queries with comparison and branded tag. The default view reads the daily sync; other filters fetch live and cache for 24 hourssession
get/projects/{id}/brand-termsBrand terms that split branded and non-branded queries (defaults until an owner saves)session
put/projects/{id}/brand-termsSave the brand terms (owner only). An empty list returns to the defaultssession
get/projects/{id}/tracking/search-console-suggestionsQueries the site already gets clicks or impressions for, not tracked yet, by clicks then impressionssession
get/projects/{id}/integrations/github/fileOwner 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 refusedsession
post/projects/{id}/proposalsOwner 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_approvalsession
get/projects/{id}/proposalsChange proposals of the project, newest firstsession
get/projects/{id}/proposals/{proposalId}One proposal: revisions, the current revision's before/after content, decisions, executions and what the signed-in user can dosession
post/projects/{id}/proposals/{proposalId}/revisionsOwner or member. Create a new revision with a new hash. Earlier revisions become superseded and their approvals authorize nothingsession
post/projects/{id}/proposals/{proposalId}/decisionsSigned-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 ownersession
post/projects/{id}/proposals/{proposalId}/executeSigned-in person only. Start the approved current revision: github_pr queues one pull request (never merged). Payload routes answer 501 until the Payload contract existssession
get/projects/{id}/work-summaryCounts for Today: awaiting approval, ready to execute, in progress, monitoringsession
get/workspace/planPlan, project limit and credit balance of the active workspacesession
get/workspace/credits/ledgerCredit ledger of the active workspace, newest first (owners only)session
get/projects/{id}/autonomyAutonomy level of the project (review_all, auto_low_risk, auto_all), its last change and what each level lets the policy approvesession
patch/projects/{id}/autonomyOwner 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 409session
get/projects/{id}/integrations/cmsCMS 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 managesession
put/projects/{id}/integrations/cmsOwner. 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 toolssession
post/projects/{id}/integrations/cms/testOwner. 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 codesession
put/projects/{id}/integrations/cms/toolsOwner. 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 onlysession
delete/projects/{id}/integrations/cmsOwner. Delete the sealed API key, the endpoint, the tool list and the enabled toolssession
get/projects/{id}/integrations/keysBing Webmaster Tools, PostHog and Microsoft Clarity connections: state, property and a hint of the key (last four characters, never the key). Members read; owners managesession
put/projects/{id}/integrations/keys/{provider}Owner. Save the property and, when given, a new key (sealed). The connection becomes untestedsession
post/projects/{id}/integrations/keys/{provider}/testOwner. One read-only request to the service with the stored key. A failed test is a 200 result with ok falsesession
delete/projects/{id}/integrations/keys/{provider}Owner. Delete the sealed key and the propertysession
get/projects/{id}/context/generationWhether AI context generation is configured, its credit estimate, the balance and the latest runsession
post/projects/{id}/context/generationOwner 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 claimsession
get/projects/{id}/researchResearch 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 readsession
post/projects/{id}/research/requestsRun 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/requestsHistory of research requests, newest first, without result bodies. Members readsession
get/projects/{id}/research/requests/{requestId}One stored research request with its result. Reopening it does not call the providersession
get/projects/{id}/research/competitorsLatest stored intelligence for each approved competitor: organic keywords, estimated traffic, shared keywords with the project and domain ranksession
post/projects/{id}/research/competitors/{competitorId}/refreshFetch competitor intelligence for one approved competitor now. Reserves and settles credits like a manual toolsession
get/projects/{id}/research/backlinksLatest stored backlinks of the project domain, or of one page with ?url= (a URL on the project domain)session
post/projects/{id}/research/backlinks/refreshFetch the backlinks summary of the domain, or the linking domains of one page, now. Reserves and settles credits like a manual toolsession
patch/meChange the display name of the signed-in user (1 to 80 characters after trimming)session
get/me/avatarThe 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 itsession
put/me/avatarUpload 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 refusedsession
delete/me/avatarRemove the avatar; the initial is shown againsession
patch/workspaceOwner only. Rename the active workspace (1 to 80 characters); recorded in Activitysession
get/me/deletionWhat deleting the account would do now: workspaces deleted with all their data, memberships removed, and workspaces that block deletionsession
delete/meDelete 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 memberssession
get/projects/{id}/tracking/overviewTracking 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 callsession
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 onlysession
get/projects/{id}/page-intelPage intelligence build of the project: provider, estimate of a whole build, the active and the latest build, and recent runs. Members readsession
post/projects/{id}/page-intel/buildsOwner 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}/intelStored ranking keywords, backlinks and SERP preview of one page, each with its fetched time. Never calls the providersession
post/projects/{id}/pages/{pageKey}/intel/refreshOwner 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/startCreate 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 nothingsession
get/projects/{id}/pages/{pageKey}/sourcesOne 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 hourssession
get/projects/{id}/pages/{pageKey}/cmsWhether 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 CMSsession
post/projects/{id}/pages/{pageKey}/cms/checkLook the page up in the CMS again now (Check again). Read only. At most 20 checks per project in 10 minutessession
get/projects/{id}/integrations/cms/url-rulesURL rules that map page paths to CMS collections and fields, the enabled collections, and suggestions from the site's page pathssession
put/projects/{id}/integrations/cms/url-rulesOwner. 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