Endpoint overview
Every Agent API endpoint on one page, with the scope it needs.
Endpoint overview
Section titled “Endpoint overview”All endpoints use the base URL /api/agent/v1/. Bearer token authentication is required for all endpoints except key management (which uses Clerk session auth).
| Method | Endpoint | Scope | Description |
|---|---|---|---|
| Key Management | |||
| POST | /keys |
Clerk session | Create a new API key |
| GET | /keys |
Clerk session | List all API keys |
| DELETE | /keys/:id |
Clerk session | Revoke an API key |
| Copywriter | |||
| POST | /copywriter/jobs |
copywriter:run |
Create a content job |
| GET | /copywriter/jobs/:id |
copywriter:read |
Get job status |
| PATCH | /copywriter/jobs/:id |
copywriter:run |
Mark/unmark the project as Done |
| GET | /copywriter/jobs/:id/keyword-exclusions |
copywriter:read |
Read the project’s ignored keywords |
| PATCH | /copywriter/jobs/:id/keyword-exclusions |
copywriter:run |
Bulk ignore or restore project keywords |
| GET | /clients/:id/keyword-exclusions |
clients:read or copywriter:read |
Read the workspace’s ignored keywords |
| PATCH | /clients/:id/keyword-exclusions |
clients:write |
Bulk ignore or restore workspace keywords |
| GET | /copywriter/jobs/:id/artifacts |
copywriter:read |
Get completed content artifacts |
| POST | /copywriter/jobs/:id/approve |
copywriter:run |
Approve brief (stepped mode) |
| PUT | /copywriter/jobs/:id/draft |
copywriter:run |
Replace the draft body on an existing project |
| GET | /copywriter/jobs |
copywriter:read |
List all content jobs |
| DELETE | /copywriter/jobs/:id |
copywriter:run |
Delete a content job |
| GET | /copywriter/jobs/:id/export/:format |
copywriter:read |
Export content as markdown or HTML |
| POST | /copywriter/autopilot |
copywriter:run |
Start an Autopilot run (one-shot orchestrated pipeline) |
| GET | /copywriter/autopilot/:id |
copywriter:read |
Get Autopilot run status + review summary |
| GET | /copywriter/queue/status |
copywriter:read |
Get queue depth, estimated wait, and service alerts |
| Reporter | |||
| GET | /reporter/projects |
reporter:read |
List rank tracking projects |
| GET | /reporter/capabilities |
reporter:read |
Preflight platform entitlements, report capacity, and client identity/location dependencies |
| GET | /reporter/projects/:id |
reporter:read |
Get project detail with latest results |
| GET | /reporter/projects/:id/results |
reporter:read |
Get full latest-per-platform results, or select one run |
| GET | /reporter/projects/:id/trends |
reporter:read |
Get SPI trend data |
| GET | /reporter/brand-summary?client_id=:clientId |
reporter:read |
Get a client-scoped latest-per-platform brand summary |
| GET | /reporter/visibility-summary?client_id=:clientId |
reporter:read |
Get an alias-aware client visibility summary (AI rates, organic and local pack positions, competitors, cited domains). Default scope: scheduled reports only (the rule Serena uses), or every active report when the client has none; scope.mode and scope.excluded_unscheduled report it. Optional project_ids (any report), subset_project_ids, as_of, view=compact|full |
| GET | /reporter/visibility-gaps?client_id=:clientId |
reporter:read |
Where the client is missing: deduplicated, classified, geo-matched, prioritized pages without the client, AI answers without the client, and organic or Local Pack gaps. ready and source_check_progress distinguish finished evidence from pages still being checked; repeat the same request after retry_after_seconds while false. Same default scope as the summary; cached up to 5 minutes per client, scope, and latest scan (X-Rankability-Result-Cache: hit|miss). Optional project_ids or campaign_id (include exactly those reports), page_types, client_status, include_excluded, limit, offset, view |
| GET | /reporter/visibility-comparison?client_id=:clientId&before_as_of=:date |
reporter:read |
Compare client visibility between two dates like for like; optional after_as_of, or stored campaign snapshots via before_snapshot_id / after_snapshot_id, project_ids, view=compact|full |
| GET | /clients/:id/campaigns |
clients:read |
List client campaign records (archived hidden unless include_archived=true) |
| POST | /clients/:id/campaigns |
clients:write |
Create a campaign; Idempotency-Key required. Prompt set is {tracker_cluster_id} or {tracker_project_ids}; nothing is created or scanned |
| GET | /clients/:id/campaigns/:campaign_id |
clients:read |
Compact summary; log_limit (0 to 50), include_log_detail. Report status needs reporter:read |
| PATCH | /clients/:id/campaigns/:campaign_id |
clients:write |
Patch fields; context lists replace only the lists provided; Idempotency-Key required |
| GET, POST | /clients/:id/campaigns/:campaign_id/log |
clients:read / clients:write |
Page the log (limit, before, kind) or append an entry; resolve with resolves_entry_id |
| GET, POST | /clients/:id/campaigns/:campaign_id/snapshots |
clients:read / clients:write + reporter:read |
List snapshots with headline numbers, or save one (no scan, no sync, no usage). First-party totals match the SEO performance dashboard for first_party_range; each item reports payload_version and first_party (basis, range, partial, caveats). Version 1 snapshots used stored-row totals (basis: "stored_rows") and are always partial |
| GET | /clients/:id/campaigns/:campaign_id/snapshots/compare |
clients:read |
Compare two snapshots (before_id, after_id; default baseline vs latest) |
| GET | /clients/:id/campaigns/:campaign_id/snapshots/:snapshot_id |
clients:read + reporter:read |
Full stored snapshot payload |
| POST | /clients/:id/campaigns/:campaign_id/documents |
clients:write |
Attach an existing Knowledge source as internal or client_facing |
| GET | /reporter/summary |
reporter:read |
Get org-wide Reporter summary |
| GET | /reporter/seo-performance?client_id=:clientId&days=28 |
reporter:read |
Get GSC and GA4 organic performance from the client’s connected Google integrations |
| GET | /clients/:id/gsc/search-performance |
clients:read |
Get bounded GSC query, page, or query-page performance with sync freshness |
| POST | /reporter/projects |
reporter:write |
Create a rank tracking project |
| PUT | /reporter/projects/upsert |
reporter:write |
Declaratively create or update one client/topic report in place; supports dry_run |
| PATCH | /reporter/projects/:id |
reporter:write |
Update a rank tracking project |
| DELETE | /reporter/projects/:id |
reporter:write |
Delete a rank tracking project |
| Researcher | |||
| POST | /researcher/jobs |
researcher:run |
Start a keyword research job |
| GET | /researcher/jobs/:job_id |
researcher:read |
Poll job status / fetch results |
| GET | /researcher/jobs |
researcher:read |
List recent research jobs |
| GET | /researcher/projects |
researcher:read |
List saved Researcher projects |
| GET | /researcher/projects/:id |
researcher:read |
Get a project with its saved keywords |
| Usage | |||
| GET | /usage |
Any supported Agent API scope | Read the active metering contract and limits |
| GET | /usage/events |
Any Agent API scope | List completed usage outcomes with bounded pagination |
| Optimize | |||
| POST | /optimize |
optimize:run |
Start one durable, retry-safe page optimization run |
| GET | /optimizations/:id |
optimize:run |
Poll a run or read its saved summary/full result |
| GET | /optimizations |
optimize:run |
List compact saved optimization history |
| Prospector | |||
| GET | /clients/:client_id/prospect-lists |
prospector:read |
List bounded saved outreach lists and status counts |
| POST | /clients/:client_id/prospect-lists |
prospector:write |
Create one retry-safe saved list |
| GET | /clients/:client_id/prospect-lists/:list_id/items |
prospector:read |
List bounded pipeline items with optional status filtering |
| POST | /clients/:client_id/prospect-lists/:list_id/items |
prospector:write |
Save and canonical-URL-deduplicate one known prospect |
| PATCH | /clients/:client_id/prospect-lists/:list_id/items/:item_id |
prospector:write |
Update saved status or notes |
| DELETE | /clients/:client_id/prospect-lists/:list_id/items/:item_id |
prospector:write |
Remove one exact-URL-confirmed list item |
| DELETE | /clients/:client_id/prospect-lists/:list_id |
prospector:write |
Delete one exact-name-confirmed list |
| Backlink profile | |||
| GET | /clients/:client_id/backlinks/profile |
backlinks:read |
Read one bounded saved backlink profile section with freshness |
| POST | /clients/:client_id/backlinks/profile/refresh |
backlinks:run |
Confirm and idempotently create or refresh all four cache-backed profile sections |
| Saved audit artifacts | |||
| GET | /clients/:client_id/gbp-audits |
gbp-audit:read |
List bounded saved GBP audits |
| GET | /clients/:client_id/gbp-audits/:audit_id |
gbp-audit:read |
Read one saved summary or bounded full GBP audit |
| GET | /clients/:client_id/batch-url-runs |
batch-url:read |
List saved Batch URL Analyzer runs |
| GET | /clients/:client_id/batch-url-runs/:run_id |
batch-url:read |
Read one paginated saved Batch URL result |
| Routines and publishing | |||
| GET | /clients/:client_id/routines |
routines:read |
List bounded recurring content and Knowledge-monitor Routines |
| GET | /clients/:client_id/routines/:routine_id |
routines:read |
Read one Routine with bounded topics or source IDs |
| GET | /clients/:client_id/publishing/connections |
publishing:read |
List credential-free destination state and safe target metadata |
| POST | /clients/:client_id/publishing/artifacts |
publishing:write |
Create or reuse an immutable destination-specific snapshot without destination mutation |
| GET | /clients/:client_id/publishing/preflight |
publishing:read |
Validate one immutable article snapshot without mutation |
| POST | /clients/:client_id/publishing/deliveries |
publishing:write |
Request one confirmed, idempotent draft delivery |
| GET | /clients/:client_id/publishing/deliveries |
publishing:read |
List bounded privacy-safe delivery receipts |
| GET | /clients/:client_id/publishing/deliveries/:delivery_id |
publishing:read |
Read one delivery’s preflight, remote, currency, and validation state |
| Page Auditor | |||
| POST | /page-auditor/audits |
page_audit:write |
Start one durable retry-safe page audit (150 credits on legacy Full accounts) |
| PUT | /page-auditor/audits/batch |
page_audit:write |
Dry-run or start/resume a durable batch of up to 25 audits |
| GET | /page-auditor/audits/:audit_id |
page_audit:read |
Get an audit by ID |
| GET | /page-auditor/audits |
page_audit:read |
List audits |
| DELETE | /page-auditor/audits/:audit_id |
page_audit:write |
Permanently delete a finished audit (409 if it is still in progress — wait for it to finish) |
| GET | /jobs/:job_id |
Any Agent API scope | Reconcile supported asynchronous job families through one status contract |
| POST | /jobs/status |
Any Agent API scope | Reconcile one to 50 job IDs in one read-only batch |
| GET | /audit-manifest?client_id=:id |
Matching read scope | Inventory client Tracker, audit, research, and content artifacts with lifecycle metadata |
| GET | `/exports?client_id=:id&type=audit_manifest | audit_results&format=json | csv` |
| Site Auditor | |||
| POST | /site-auditor/projects |
site-auditor:write |
Create a project and start a full-site crawl (1 credit / 5 pages, charged on success) |
| POST | /site-auditor/projects/:project_id/crawl |
site-auditor:write |
Re-crawl an existing project |
| POST | /site-auditor/projects/:project_id/cancel |
site-auditor:write |
Cancel an in-progress crawl |
| DELETE | /site-auditor/projects/:project_id |
site-auditor:write |
Permanently delete a finished/cancelled/errored project and its pages + issues (409 if a crawl is in progress — cancel first) |
| GET | /site-auditor/projects |
site-auditor:read |
List projects |
| GET | /site-auditor/projects/:project_id |
site-auditor:read |
Get a project with pages + issues |
| GET | /site-auditor/credit-estimate |
site-auditor:read |
Estimate crawl cost for N pages |
| Clients | |||
| GET | /clients |
clients:read |
List all clients |
| POST | /clients |
clients:write |
Create a new client |
| GET | /clients/:id |
clients:read |
Get client details |
| PATCH | /clients/:id |
clients:write |
Update a client |
| DELETE | /clients/:id |
clients:write |
Delete a client and associated data |
| GET | /clients/:id/sources |
clients:read or copywriter:read |
List compact Knowledge source metadata; use view=full only when source bodies are required |
| GET | /clients/:id/sources/:source_id |
clients:read or copywriter:read |
Get one Knowledge source in compact or full view |
| GET | /clients/:id/sources/:source_id/contradictions |
clients:read or copywriter:read |
Read durable contradiction-check receipts and completed findings |
| POST | /clients/:id/sources |
clients:write |
Create a pasted source up to 250,000 characters; optional role and usage; upsert_by_name=true safely syncs one exact-name match |
| PATCH | /clients/:id/sources/:source_id |
clients:write |
Update source name, body, role, generation usage, selection, or priority |
| DELETE | /clients/:id/sources/:source_id |
clients:write |
Delete one Knowledge source |
| Knowledge Base | |||
| GET | /kb/articles |
kb:read |
Get all published KB articles and FAQ content |
