Skip to content

Endpoint overview

Every Agent API endpoint on one page, with the scope it needs.

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