---
title: "API reference"
description: "Every Agent API endpoint (version 1.24.0), rendered from the public OpenAPI spec, with a console to try requests."
canonical_url: "https://developers.rankability.com/api-reference"
section: "API reference"
last_updated: 2026-11-14
---

# API reference

Every Agent API endpoint (version 1.24.0), rendered from the public OpenAPI spec, with a console to try requests.

OpenAPI 3.0.3 spec for the Rankability Agent API, version 1.24.0. Download it from https://app.rankability.com/api/openapi.json (public, no auth) and import it into Postman, n8n, Make or any OpenAPI client. Requests go to https://app.rankability.com.

## Backlink profile

Saved backlink profile evidence for a client, and explicit refreshes.

- `GET /api/agent/v1/clients/{client_id}/backlinks/profile`: Read one bounded saved backlink profile section with freshness (scopes: `backlinks:read`)
- `POST /api/agent/v1/clients/{client_id}/backlinks/profile/refresh`: Confirm and idempotently create or refresh all four cache-backed profile sections (scopes: `backlinks:run`)

## Campaigns

Client campaign records: context, log entries, snapshots and attached documents.

- `GET /api/agent/v1/clients/{client_id}/campaigns`: List client campaign records (scopes: `clients:read`)
- `POST /api/agent/v1/clients/{client_id}/campaigns`: Create a campaign (scopes: `clients:write`)
- `GET /api/agent/v1/clients/{client_id}/campaigns/{campaign_id}`: Get a campaign summary (scopes: `clients:read`)
- `PATCH /api/agent/v1/clients/{client_id}/campaigns/{campaign_id}`: Update a campaign (scopes: `clients:write`)
- `POST /api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/documents`: Attach an existing Knowledge source as `internal` or `client_facing` (scopes: `clients:write`)
- `GET /api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/log`: Page the campaign log (scopes: `clients:read`)
- `POST /api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/log`: Append a campaign log entry (scopes: `clients:write`)
- `GET /api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/snapshots`: List campaign snapshots (scopes: `clients:read`)
- `POST /api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/snapshots`: Save a campaign snapshot (scopes: `clients:write`, `reporter:read`)
- `GET /api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/snapshots/{snapshot_id}`: Get a full stored campaign snapshot (scopes: `clients:read`, `reporter:read`)
- `GET /api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/snapshots/compare`: Compare two snapshots (scopes: `clients:read`)

## Clients

Client workspaces: identity, settings, integrations and Search Console data.

- `GET /api/agent/v1/clients`: List all clients (any one of: `clients:read`, `copywriter:read`, `reporter:read`)
- `POST /api/agent/v1/clients`: Create a new client (scopes: `clients:write`)
- `GET /api/agent/v1/clients/{client_id}/automations`: GET /clients/:client_id/automations (scopes: `routines:read`)
- `PUT /api/agent/v1/clients/{client_id}/automations`: PUT /clients/:client_id/automations (scopes: `routines:write`)
- `GET /api/agent/v1/clients/{client_id}/automations/{type}`: GET /clients/:client_id/automations/:type (scopes: `routines:read`)
- `POST /api/agent/v1/clients/{client_id}/automations/technical_site_audit/run`: POST /clients/:client_id/automations/technical_site_audit/run (scopes: `routines:write`, `site-auditor:write`)
- `GET /api/agent/v1/clients/{client_id}/automations/technical_site_audit/runs/{run_id}/handoff`: GET /clients/:client_id/automations/technical_site_audit/runs/:run_id/handoff (scopes: `routines:read`, `site-auditor:read`)
- `DELETE /api/agent/v1/clients/{id}`: Delete a client and associated data (scopes: `clients:write`)
- `GET /api/agent/v1/clients/{id}`: Get client details (any one of: `clients:read`, `copywriter:read`, `reporter:read`)
- `PATCH /api/agent/v1/clients/{id}`: Update a client (scopes: `clients:write`)
- `POST /api/agent/v1/clients/{id}/connect-link`: Create an integration connect link for a client (scopes: `clients:write`)
- `GET /api/agent/v1/clients/{id}/gsc/search-performance`: Get bounded GSC query, page, or query-page performance with sync freshness (scopes: `clients:read`)
- `GET /api/agent/v1/clients/{id}/keyword-exclusions`: Read the workspace's ignored keywords (any one of: `clients:read`, `copywriter:read`)
- `PATCH /api/agent/v1/clients/{id}/keyword-exclusions`: Bulk ignore or restore workspace keywords (scopes: `clients:write`)
- `GET /api/agent/v1/clients/{id}/search-performance/catalog`: GET /clients/:id/search-performance/catalog (scopes: `clients:read`)
- `POST /api/agent/v1/clients/{id}/search-performance/query`: POST /clients/:id/search-performance/query (scopes: `clients:read`)
- `GET /api/agent/v1/clients/resolve`: Resolve a client by name or domain (any one of: `clients:read`, `copywriter:read`, `reporter:read`)

## Completion events

Signed webhooks when a Tracker scan, Page Audit or Site Audit finishes. The same subscriptions as the hosted MCP events.

- `GET /api/agent/v1/events`: List the completion events this credential can subscribe to
- `GET /api/agent/v1/events/subscriptions`: List this credential's active event subscriptions
- `POST /api/agent/v1/events/subscriptions`: Subscribe a verified HTTPS callback to a completion event
- `DELETE /api/agent/v1/events/subscriptions/{id}`: Stop an event subscription

## Copywriter

SEO content jobs in auto, stepped or Autopilot mode, plus entity research.

- `POST /api/agent/v1/copywriter/autopilot`: Start an Autopilot run (scopes: `copywriter:run`)
- `GET /api/agent/v1/copywriter/autopilot/{id}`: Get Autopilot run status + review summary (scopes: `copywriter:read`)
- `GET /api/agent/v1/copywriter/jobs`: List all content jobs (scopes: `copywriter:read`)
- `POST /api/agent/v1/copywriter/jobs`: Create a content job (any one of: `copywriter:run`, `seo_research:run`)
- `DELETE /api/agent/v1/copywriter/jobs/{id}`: Delete a content job (scopes: `copywriter:run`)
- `GET /api/agent/v1/copywriter/jobs/{id}`: Get job status (scopes: `copywriter:read`)
- `PATCH /api/agent/v1/copywriter/jobs/{id}`: Mark/unmark the project as Done (scopes: `copywriter:run`)
- `POST /api/agent/v1/copywriter/jobs/{id}/approve`: Approve brief (scopes: `copywriter:run`)
- `GET /api/agent/v1/copywriter/jobs/{id}/artifacts`: Get completed content artifacts (scopes: `copywriter:read`)
- `PATCH /api/agent/v1/copywriter/jobs/{id}/brief`: Edit the brief of a stepped-mode content job before approval (scopes: `copywriter:run`)
- `PUT /api/agent/v1/copywriter/jobs/{id}/draft`: Replace the draft body on an existing project (scopes: `copywriter:run`)
- `GET /api/agent/v1/copywriter/jobs/{id}/export/{format}`: Export content as markdown or HTML (scopes: `copywriter:read`)
- `GET /api/agent/v1/copywriter/jobs/{id}/keyword-exclusions`: Read the project's ignored keywords (scopes: `copywriter:read`)
- `PATCH /api/agent/v1/copywriter/jobs/{id}/keyword-exclusions`: Bulk ignore or restore project keywords (scopes: `copywriter:run`)
- `GET /api/agent/v1/copywriter/queue/status`: Get queue depth, estimated wait, and service alerts (scopes: `copywriter:read`)
- `POST /api/agent/v1/entities/jobs`: Start an entity-only research job (scopes: `copywriter:run`)
- `GET /api/agent/v1/entities/jobs/{job_id}`: Get an entity-only research job (scopes: `copywriter:read`)

## Crawler

Scrape single pages, crawl sites within bounds and extract structured data.

- `POST /api/agent/v1/crawl`: Start a bounded multi-page crawl (scopes: `crawl:run`)
- `GET /api/agent/v1/crawl/{jobId}`: Get a crawl job and its pages (scopes: `crawl:run`)
- `GET /api/agent/v1/crawler/usage`: Get the daily page quota for scrape and crawl (any one of: `scrape:run`, `crawl:run`, `extract:run`)
- `POST /api/agent/v1/extract`: Extract structured data from a page (scopes: `extract:run`)
- `POST /api/agent/v1/scrape`: Scrape one page with SEO and AEO extraction (scopes: `scrape:run`)

## Jobs and exports

One status contract for asynchronous jobs, artifact inventory and exports.

- `GET /api/agent/v1/audit-manifest`: Inventory client Tracker, audit, research, and content artifacts with lifecycle metadata (any one of: `page_audit:read`, `site-auditor:read`, `reporter:read`, `researcher:read`, `copywriter:read`)
- `GET /api/agent/v1/exports`: Retrieve a structured browser-free artifact or paginated result handoff (any one of: `page_audit:read`, `site-auditor:read`, `reporter:read`, `researcher:read`, `copywriter:read`)
- `GET /api/agent/v1/jobs/{job_id}`: Reconcile supported asynchronous job families through one status contract
- `POST /api/agent/v1/jobs/status`: Reconcile one to 50 job IDs in one read-only batch

## Knowledge Base

Rankability Help Center content for grounding agents.

- `GET /api/agent/v1/kb/articles`: Get all published KB articles and FAQ content (scopes: `kb:read`)

## Knowledge sources

A client's Knowledge sources used for content and Serena grounding.

- `GET /api/agent/v1/clients/{id}/sources`: List compact Knowledge source metadata (any one of: `clients:read`, `copywriter:read`)
- `POST /api/agent/v1/clients/{id}/sources`: Create a pasted source up to 250,000 characters (scopes: `clients:write`)
- `DELETE /api/agent/v1/clients/{id}/sources/{source_id}`: Delete one Knowledge source (scopes: `clients:write`)
- `GET /api/agent/v1/clients/{id}/sources/{source_id}`: Get one Knowledge source in compact or full view (any one of: `clients:read`, `copywriter:read`)
- `PATCH /api/agent/v1/clients/{id}/sources/{source_id}`: Update source name, body, role, generation usage, selection, or priority (scopes: `clients:write`)
- `GET /api/agent/v1/clients/{id}/sources/{source_id}/contradictions`: Read durable contradiction-check receipts and completed findings (any one of: `clients:read`, `copywriter:read`)
- `GET /api/agent/v1/clients/{id}/sources/{source_id}/sections`: Read sections of one Knowledge source (scopes: `clients:read`)

## Optimize

Durable page optimization runs scored against SERP competitors.

- `GET /api/agent/v1/optimizations`: List compact saved optimization history (scopes: `optimize:run`)
- `GET /api/agent/v1/optimizations/{id}`: Poll a run or read its saved summary/full result (scopes: `optimize:run`)
- `POST /api/agent/v1/optimize`: Start one durable, retry-safe page optimization run (scopes: `optimize:run`)

## Page Auditor

Single-page and batch AEO/SEO page audits.

- `GET /api/agent/v1/page-auditor/audits`: List audits (scopes: `page_audit:read`)
- `POST /api/agent/v1/page-auditor/audits`: Start one durable retry-safe page audit (scopes: `page_audit:write`)
- `DELETE /api/agent/v1/page-auditor/audits/{audit_id}`: Permanently delete a finished audit (scopes: `page_audit:write`)
- `GET /api/agent/v1/page-auditor/audits/{audit_id}`: Get an audit by ID (scopes: `page_audit:read`)
- `PUT /api/agent/v1/page-auditor/audits/batch`: Dry-run or start/resume a durable batch of up to 25 audits (scopes: `page_audit:write`)

## Prospect scans

AI visibility reports for prospects.

- `GET /api/agent/v1/prospect-scans`: List prospect AI visibility reports (scopes: `prospect_scan:read`)
- `POST /api/agent/v1/prospect-scans`: Start a prospect AI visibility report (scopes: `prospect_scan:run`)
- `GET /api/agent/v1/prospect-scans/{publicId}`: Get one prospect AI visibility report (scopes: `prospect_scan:read`)

## Prospector

Saved outreach lists and pipeline items.

- `GET /api/agent/v1/clients/{client_id}/prospect-lists`: List bounded saved outreach lists and status counts (scopes: `prospector:read`)
- `POST /api/agent/v1/clients/{client_id}/prospect-lists`: Create one retry-safe saved list (scopes: `prospector:write`)
- `DELETE /api/agent/v1/clients/{client_id}/prospect-lists/{list_id}`: Delete one exact-name-confirmed list (scopes: `prospector:write`)
- `GET /api/agent/v1/clients/{client_id}/prospect-lists/{list_id}/items`: List bounded pipeline items with optional status filtering (scopes: `prospector:read`)
- `POST /api/agent/v1/clients/{client_id}/prospect-lists/{list_id}/items`: Save and canonical-URL-deduplicate one known prospect (scopes: `prospector:write`)
- `DELETE /api/agent/v1/clients/{client_id}/prospect-lists/{list_id}/items/{item_id}`: Remove one exact-URL-confirmed list item (scopes: `prospector:write`)
- `PATCH /api/agent/v1/clients/{client_id}/prospect-lists/{list_id}/items/{item_id}`: Update saved status or notes (scopes: `prospector:write`)

## Reporter

AI and organic rank tracking: projects, scans, results, trends and visibility.

- `GET /api/agent/v1/notifications`: List recent notifications for the organization (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/brand-summary`: Get a client-scoped latest-per-platform brand summary (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/capabilities`: Preflight platform entitlements, report capacity, and client identity/location dependencies (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/matrix`: Get the prompt by platform visibility matrix for a client (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/projects`: List rank tracking projects (scopes: `reporter:read`)
- `POST /api/agent/v1/reporter/projects`: Create a rank tracking project (scopes: `reporter:write`)
- `DELETE /api/agent/v1/reporter/projects/{id}`: Delete a rank tracking project (scopes: `reporter:write`)
- `GET /api/agent/v1/reporter/projects/{id}`: Get project detail with latest results (scopes: `reporter:read`)
- `PATCH /api/agent/v1/reporter/projects/{id}`: Update a rank tracking project (scopes: `reporter:write`)
- `GET /api/agent/v1/reporter/projects/{id}/citation-analysis`: Get citation analysis for a rank tracking project (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/projects/{id}/competitors`: Get competitors seen in a rank tracking project (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/projects/{id}/results`: Get full latest-per-platform results, or select one run (scopes: `reporter:read`)
- `POST /api/agent/v1/reporter/projects/{id}/scan`: Trigger a scan of a rank tracking project (scopes: `reporter:run`)
- `GET /api/agent/v1/reporter/projects/{id}/scan-estimate`: Estimate the usage of scanning a rank tracking project (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/projects/{id}/sources`: Get the sources cited in a project's AI answers (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/projects/{id}/trends`: Get SPI trend data (scopes: `reporter:read`)
- `PUT /api/agent/v1/reporter/projects/upsert`: Declaratively create or update one client/topic report in place (scopes: `reporter:write`)
- `GET /api/agent/v1/reporter/scan-status`: Get the scan state of every rank tracking project for a client (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/seo-performance`: Get GSC and GA4 organic performance from the client's connected Google integrations (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/summary`: Get org-wide Reporter summary (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/visibility-comparison`: Compare client visibility between two dates like for like (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/visibility-gaps`: Find where a client is missing from search and AI answers (scopes: `reporter:read`)
- `GET /api/agent/v1/reporter/visibility-summary`: Get an alias-aware client visibility summary (scopes: `reporter:read`)

## Researcher

Keyword research jobs and saved Researcher projects.

- `GET /api/agent/v1/researcher/jobs`: List recent research jobs (scopes: `researcher:read`)
- `POST /api/agent/v1/researcher/jobs`: Start a keyword research job (scopes: `researcher:run`)
- `GET /api/agent/v1/researcher/jobs/{job_id}`: Poll job status / fetch results (scopes: `researcher:read`)
- `GET /api/agent/v1/researcher/projects`: List saved Researcher projects (scopes: `researcher:read`)
- `GET /api/agent/v1/researcher/projects/{id}`: Get a project with its saved keywords (scopes: `researcher:read`)

## Routines and publishing

Recurring Routine state and confirmed, draft-only CMS delivery.

- `POST /api/agent/v1/clients/{client_id}/publishing/artifacts`: Create or reuse an immutable destination-specific snapshot without destination mutation (scopes: `publishing:write`)
- `GET /api/agent/v1/clients/{client_id}/publishing/connections`: List credential-free destination state and safe target metadata (scopes: `publishing:read`)
- `GET /api/agent/v1/clients/{client_id}/publishing/deliveries`: List bounded privacy-safe delivery receipts (scopes: `publishing:read`)
- `POST /api/agent/v1/clients/{client_id}/publishing/deliveries`: Request one confirmed, idempotent draft delivery (scopes: `publishing:write`)
- `GET /api/agent/v1/clients/{client_id}/publishing/deliveries/{delivery_id}`: Read one delivery's preflight, remote, currency, and validation state (scopes: `publishing:read`)
- `GET /api/agent/v1/clients/{client_id}/publishing/preflight`: Validate one immutable article snapshot without mutation (scopes: `publishing:read`)
- `GET /api/agent/v1/clients/{client_id}/routines`: List bounded recurring content and Knowledge-monitor Routines (scopes: `routines:read`)
- `GET /api/agent/v1/clients/{client_id}/routines/{routine_id}`: Read one Routine with bounded topics or source IDs (scopes: `routines:read`)

## SEO Research

SEO Research jobs and usage.

- `GET /api/agent/v1/seo-research/connection`: Check the SEO Research connection (any one of: `seo_research:read`, `seo_research:run`)
- `GET /api/agent/v1/seo-research/jobs`: List SEO Research jobs (scopes: `seo_research:read`)
- `POST /api/agent/v1/seo-research/jobs`: Start an SEO Research job (scopes: `seo_research:run`)
- `GET /api/agent/v1/seo-research/jobs/{id}`: Get an SEO Research job (scopes: `seo_research:read`)
- `GET /api/agent/v1/seo-research/jobs/{id}/result`: Get the result of an SEO Research job (scopes: `seo_research:read`)
- `GET /api/agent/v1/seo-research/usage`: Get SEO Research usage (any one of: `seo_research:read`, `seo_research:run`)

## Saved audit artifacts

Saved GBP audits and Batch URL Analyzer runs.

- `GET /api/agent/v1/clients/{client_id}/batch-url-runs`: List saved Batch URL Analyzer runs (scopes: `batch-url:read`)
- `GET /api/agent/v1/clients/{client_id}/batch-url-runs/{run_id}`: Read one paginated saved Batch URL result (scopes: `batch-url:read`)
- `GET /api/agent/v1/clients/{client_id}/gbp-audits`: List bounded saved GBP audits (scopes: `gbp-audit:read`)
- `GET /api/agent/v1/clients/{client_id}/gbp-audits/{audit_id}`: Read one saved summary or bounded full GBP audit (scopes: `gbp-audit:read`)

## Search Intelligence

Live queries across Google and AI platforms.

- `POST /api/agent/v1/search-intelligence/query`: Run a search intelligence query across Google and AI platforms (scopes: `search_intelligence:query`)
- `GET /api/agent/v1/search-intelligence/query/{runId}`: Get a search intelligence query run (scopes: `search_intelligence:query`)

## Serena

Read-only consultation with Serena, Rankability's AI SEO director.

- `POST /api/agent/v1/serena/consult`: Ask Serena one client-scoped question (scopes: `serena:ask`)
- `POST /api/agent/v1/serena/document-reviews`: Ask Serena to review a Knowledge document (scopes: `serena:ask`)
- `GET /api/agent/v1/serena/document-reviews/{review_id}`: Get a Serena document review (scopes: `serena:ask`)

## Site Auditor

Full-site crawls with page-level issues.

- `GET /api/agent/v1/site-auditor/credit-estimate`: Estimate crawl cost for N pages (scopes: `site-auditor:read`)
- `GET /api/agent/v1/site-auditor/projects`: List projects (scopes: `site-auditor:read`)
- `POST /api/agent/v1/site-auditor/projects`: Create a project and start a full-site crawl (scopes: `site-auditor:write`)
- `DELETE /api/agent/v1/site-auditor/projects/{project_id}`: Permanently delete a finished/cancelled/errored project and its pages + issues (scopes: `site-auditor:write`)
- `GET /api/agent/v1/site-auditor/projects/{project_id}`: Get a project with pages + issues (scopes: `site-auditor:read`)
- `POST /api/agent/v1/site-auditor/projects/{project_id}/cancel`: Cancel an in-progress crawl (scopes: `site-auditor:write`)
- `POST /api/agent/v1/site-auditor/projects/{project_id}/crawl`: Re-crawl an existing project (scopes: `site-auditor:write`)
- `GET /api/agent/v1/site-auditor/projects/{project_id}/pages/{page_id}`: Get one crawled page with its issues (scopes: `site-auditor:read`)

## Usage

The active metering contract, limits, usage events and estimates.

- `GET /api/agent/v1/credits/balance`: Get the credit balance (any one of: `copywriter:read`, `reporter:read`)
- `GET /api/agent/v1/usage`: Read the active metering contract and limits
- `GET /api/agent/v1/usage/estimate`: Estimate the usage impact of an operation before running it (any one of: `copywriter:read`, `copywriter:run`, `optimize:run`, `page_audit:read`, `page_audit:write`, `researcher:read`, `researcher:run`, `scrape:run`, `crawl:run`, `extract:run`, `search_intelligence:query`, `site-auditor:read`, `site-auditor:write`, `reporter:read`, `reporter:run`, `prospect_scan:run`, `prospect_scan:read`)
- `GET /api/agent/v1/usage/events`: List completed usage outcomes with bounded pagination

## mcp

- `GET /api/agent/v1/mcp/capabilities`: GET /mcp/capabilities
