Skip to content

What the API can do

The modules the Agent API covers, common automation workflows, and read-only Serena consultation.

This API gives your agent or automation complete control over five core Rankability modules:

Module What you can do Key scopes / auth
Copywriter Create SEO content jobs, poll status, retrieve outlines/drafts/SEO metadata, approve briefs, list/delete/export finished content copywriter:run, copywriter:read
Reporter List rank tracking projects, read SPI scores and AI citation data, create/update/delete tracking projects, trigger scans reporter:read, reporter:run, reporter:write
Clients List/create/update/delete client profiles with brand voice, knowledge base, and domain context clients:read, clients:write
Knowledge Base Retrieve the canonical Help Center in JSON or Markdown for programmatic reference and agent grounding kb:read
Optimize Start a durable asynchronous Agent API score, poll or list saved runs, and retrieve full competitor/entity evidence; the internal admin endpoint remains synchronous optimize:run or X-Admin-Key header
Prospector Read and manage saved outreach lists and pipeline items without invoking discovery, enrichment, or contact providers prospector:read, prospector:write
Backlink profile Read saved summary, history, anchor, and top-page evidence; explicitly create or refresh aggregate snapshots backlinks:read, backlinks:run
Saved audit artifacts Read saved GBP audits and Batch URL Analyzer history without starting provider-backed work gbp-audit:read, batch-url:read
Routines and publishing Read recurring Routine configuration and publishing receipts; preflight and request confirmed draft-only delivery routines:read, publishing:read, publishing:write
Serena consultation Ask one client-scoped strategic question using selected Knowledge, saved evidence, memory, methodology, SOP skills, and Help Center grounding serena:ask
  • Bulk content pipeline: Create a client → create content jobs for 50 keywords → poll until complete → export HTML → push to your CMS
  • Rank tracking setup: Create a client → create Reporter projects for each target keyword → monitor SPI scores and AI citations over time
  • Full SEO automation: Create clients, set up rank tracking, generate content for weak keywords, export and publish — all via API
  • Dashboard integration: Pull Reporter SPI data and Copywriter job statuses into an external dashboard or reporting tool
  • Client onboarding: Automate new client setup — create client profile with brand voice, create tracking projects, start initial content jobs
  • Content scoring at scale: Start retry-safe Optimize runs, poll their durable IDs, and retrieve saved Rankability scores, entity coverage, and competitor benchmarks
  • Serena inside another assistant: Pass a client and question to Serena, then let the host assistant present or continue from Serena’s grounded answer

POST /serena/consult is a synchronous, read-only question-in/answer-out endpoint. It requires serena:ask and a client that belongs to the authenticated organization.

{
"client_id": "11111111-1111-4111-8111-111111111111",
"question": "What should we prioritize over the next 30 days?",
"history": [
{ "role": "user", "content": "Focus on qualified leads." }
]
}

The response contains answer, grounding, limitations, the requested model, and token usage. Grounding state reports whether selected client Knowledge, saved workspace activity, durable client memory, methodology, SOP skill guidance, and relevant public Help Center sources were available. The endpoint never starts scans, runs audits, changes projects, publishes, or performs live web research. Use the separate, scoped Agent API tools for actions and retain their normal approval requirements.

503 feature_unavailable means the deployment has not enabled external Serena consultation. It is not a scope or OAuth failure, and reconnecting or retrying cannot resolve it. 503 serena_unavailable is the separate transient dependency failure that callers may retry with bounded backoff.

19 of 29 app capabilities are available to agents through this API and the MCP server. The rest are listed here.

App only, by design

  • Plans, billing and payment. Plan changes, payment methods and purchases need the account owner in the browser, with the payment provider’s own checkout.
  • Organization settings, team members and API keys. Team access and credentials stay with a signed-in person. An API key cannot create other keys, so a leaked key cannot multiply itself.
  • Client portal. The portal is the read-only view an agency gives its own clients. Agents use the Tracker endpoints for the same data.
  • Academy, certification and rewards. Courses, certificates and referral rewards belong to a person, not to automated work.

Not available to agents yet

  • Google Analytics 4 explorer. GA4 data is not on the public API or the regular MCP tool list yet.
  • Brand audits. Brand audits can only be run and read in the app.
  • Log file audits. Log file uploads and results are app only for now.
  • Serena strategy and the Tasks board. Strategy plans and tasks are not on the API or MCP yet; Serena consultation is.
  • Reviews and reputation. Review monitoring and replies are app only for now.
  • Branded client reports. The report builder and branded reports are app only for now; report data is available through the Tracker and Search Console endpoints.

Source: shared/headless-capability-map.ts. A test fails when a new app page is added without saying whether agents can reach it.