---
title: "Endpoint overview"
description: "Every Agent API endpoint on one page, with the scope it needs."
canonical_url: "https://developers.rankability.com/guides/endpoints"
section: "API reference"
last_updated: 2026-11-14
---

# Endpoint overview

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

## 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` | Matching read scope | Retrieve a structured browser-free artifact or paginated result handoff |
| **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 |
