CitationBenchTalk to Sales
API reference

API inventory — every CitationBench endpoint, grouped by pillar

Master catalog of every CitationBench REST and MCP endpoint, grouped by pillar (agent, research, production, indexing, link building) with links to full request and response samples.

Conventions

  • Base URL: https://api.citationbench.com/v1
  • Auth: Authorization: Bearer sk_live_***
  • Workspace scoping: X-Workspace-Id: ws_*** header (agency master keys), or workspace-scoped keys
  • Idempotency: Idempotency-Key: <uuid> on every write
  • Agentic endpoints return { invocationId, agentId, skill, skillsUsed, status, result, raw, files } once complete. invocationId and agentId are CUIDs; files is an array of file paths. See Agent · invoke for the universal response shape.
  • Long-running results stream via SSE at /v1/agent/invocations/{id}/events
  • MCP tools are namespaced by pillar (agent.*, research.*, produce.*, indexing.*, link_building.*)

Agent

One generic agent, many skills. Use agent.invoke to run a skill. bootstrap_brand, link_hunter, rank_monitor — these are skill slugs, not separate agents.

EndpointMethodRESTMCP tool
Invoke a skillPOST/v1/agent/invokeagent.invoke
Get invocation statusGET/v1/agent/invocations/{id}agent.invocations.get
Stream invocation eventsGET (SSE)/v1/agent/invocations/{id}/events— (MCP notifications)
Cancel an invocationPOST/v1/agent/invocations/{id}/cancelagent.invocations.cancel
List recent invocationsGET/v1/agent/invocationsagent.invocations.list
Continue (multi-turn)POST/v1/agent/invocations/{id}/continueagent.invocations.continue
Approve a pausePOST/v1/agent/invocations/{id}/approveagent.approval.approve
Reject a pausePOST/v1/agent/invocations/{id}/rejectagent.approval.reject
List pending approvalsGET/v1/agent/approvalsagent.approval.list
Upload a filePOST/v1/agent/filesagent.files.upload
List filesGET/v1/agent/filesagent.files.list
Get a file by pathGET/v1/agent/files/{path}agent.files.get
Delete a fileDELETE/v1/agent/files/{path}agent.files.delete
List available skillsGET/v1/agent/skillsagent.skills.list
Get a skill's schemaGET/v1/agent/skills/{slug}agent.skills.get
Fork a skillPOST/v1/agent/skills/{slug}/forkagent.skills.fork

→ Full sample requests/responses: agent-invoke.md, agent-files.md, agent-approval.md

Research

Discover and analyze. Every research endpoint returns persistent objects that downstream Production and Distribution pillars can reference by ID.

Research · keyword

EndpointMethodRESTMCP tool
Run keyword researchPOST/v1/research/keywordresearch.keyword.research
List keywordsGET/v1/keywordsresearch.keyword.list
Get a keywordGET/v1/keywords/{id}research.keyword.get
Create keyword(s)POST/v1/keywordsresearch.keyword.create
Update a keywordPATCH/v1/keywords/{id}research.keyword.update
Delete (archive)DELETE/v1/keywords/{id}research.keyword.delete
Bulk relabelPOST/v1/keywords/relabelresearch.keyword.relabel
Bulk importPOST/v1/keywords/bulkresearch.keyword.bulk_create
Search by labelsPOST/v1/keywords/searchresearch.keyword.search

Research · serp

EndpointMethodRESTMCP tool
Fetch a SERPPOST/v1/research/serpresearch.serp.fetch
Get a SERPGET/v1/research/serp/{id}research.serp.get
List SERPsGET/v1/research/serpresearch.serp.list

Research · serp gap analysis

Detects whether there's a "serp cliff" — a winnable gap between the top results and the rest. Useful for prioritizing keywords where ranking is realistic.

EndpointMethodRESTMCP tool
Run a SERP gap analysisPOST/v1/research/serp-gapresearch.serp_gap.analyze
List analysesGET/v1/research/serp-gapresearch.serp_gap.list
Get one analysisGET/v1/research/serp-gap/{id}research.serp_gap.get

Research · competitor

EndpointMethodRESTMCP tool
Add a competitorPOST/v1/research/competitorresearch.competitor.add
List competitorsGET/v1/research/competitorresearch.competitor.list
Pull backlinksPOST/v1/research/competitor/{id}/backlinksresearch.competitor.backlinks
Pull competitor keywordsPOST/v1/research/competitor/{id}/keywordsresearch.competitor.keywords
Get keyword overlap matrixGET/v1/research/competitor/{id}/overlapresearch.competitor.overlap

Research · icp

EndpointMethodRESTMCP tool
Generate ICP from URLPOST/v1/research/icpresearch.icp.generate
Get current ICPsGET/v1/research/icpresearch.icp.get
Update ICP segmentPATCH/v1/research/icp/{segmentId}research.icp.update

Research · discuss

EndpointMethodRESTMCP tool
Run discussion researchPOST/v1/research/discussresearch.discuss.research
List discussionsGET/v1/research/discussresearch.discuss.list
Get a discussion threadGET/v1/research/discuss/{id}research.discuss.get

Research · ai citation

EndpointMethodRESTMCP tool
Run a citation checkPOST/v1/research/ai-citationresearch.ai_citation.check
List citation queriesGET/v1/research/ai-citation/queriesresearch.ai_citation.queries.list
Add a citation queryPOST/v1/research/ai-citation/queriesresearch.ai_citation.queries.create
Get historical resultsGET/v1/research/ai-citation/queries/{id}/historyresearch.ai_citation.history
Get share-of-voiceGET/v1/research/ai-citation/share-of-voiceresearch.ai_citation.share_of_voice

Research · content gap

EndpointMethodRESTMCP tool
Find content gapsPOST/v1/research/content-gapresearch.content_gap.find
List gap reportsGET/v1/research/content-gapresearch.content_gap.list
Get a gap reportGET/v1/research/content-gap/{id}research.content_gap.get

→ Full sample requests/responses: research-keyword.md (others stubbed)

Production

Brief, draft, refine, evaluate, image, publish. Everything that makes a piece of content shippable.

Production · blog post

EndpointMethodRESTMCP tool
Create a blog postPOST/v1/produce/blog-postproduce.blog_post.create
List blog postsGET/v1/produce/blog-postproduce.blog_post.list
Get a blog postGET/v1/produce/blog-post/{id}produce.blog_post.get
Update a blog postPATCH/v1/produce/blog-post/{id}produce.blog_post.update
Delete (archive)DELETE/v1/produce/blog-post/{id}produce.blog_post.delete
Regenerate sectionsPOST/v1/produce/blog-post/{id}/regenerateproduce.blog_post.regenerate
Bulk create from keywordsPOST/v1/produce/blog-post/bulkproduce.blog_post.bulk_create

Production · landing page

EndpointMethodRESTMCP tool
Generate landing pagePOST/v1/produce/landing-pageproduce.landing_page.create
List landing pagesGET/v1/produce/landing-pageproduce.landing_page.list
Get a landing pageGET/v1/produce/landing-page/{id}produce.landing_page.get
Update (manual edits)PATCH/v1/produce/landing-page/{id}produce.landing_page.update
DeleteDELETE/v1/produce/landing-page/{id}produce.landing_page.delete
Regenerate from stepPOST/v1/produce/landing-page/{id}/regenerateproduce.landing_page.regenerate
Manage pillarsCRUD/v1/produce/landing-page/pillar/{...}produce.landing_page.pillar.*

Production · refine

EndpointMethodRESTMCP tool
Apply a refinerPOST/v1/produce/refineproduce.refine.apply
List refinersGET/v1/produce/refine/refinersproduce.refine.list_refiners
Create a refinerPOST/v1/produce/refine/refinersproduce.refine.create_refiner
Update a refinerPATCH/v1/produce/refine/refiners/{id}produce.refine.update_refiner
Delete a refinerDELETE/v1/produce/refine/refiners/{id}produce.refine.delete_refiner
Bulk applyPOST/v1/produce/refine/bulkproduce.refine.bulk

Production · evaluate

EndpointMethodRESTMCP tool
Evaluate a piece of contentPOST/v1/produce/evaluateproduce.evaluate.score
List evaluationsGET/v1/produce/evaluateproduce.evaluate.list
Get an evaluationGET/v1/produce/evaluate/{id}produce.evaluate.get
Compare two evaluationsPOST/v1/produce/evaluate/compareproduce.evaluate.compare
Manage rubricsCRUD/v1/produce/evaluate/rubric/{...}produce.evaluate.rubric.*

Production · image

EndpointMethodRESTMCP tool
Generate an imagePOST/v1/produce/imageproduce.image.create
List imagesGET/v1/produce/imageproduce.image.list
Get an imageGET/v1/produce/image/{id}produce.image.get
Delete an imageDELETE/v1/produce/image/{id}produce.image.delete
List templatesGET/v1/produce/image/templatesproduce.image.templates.list
Bulk regeneratePOST/v1/produce/image/bulkproduce.image.bulk

Production · publish

EndpointMethodRESTMCP tool
Publish contentPOST/v1/produce/publishproduce.publish.send
List publishing historyGET/v1/produce/publish/historyproduce.publish.history
Unpublish (depublish)POST/v1/produce/publish/{id}/unpublishproduce.publish.unpublish
Manage platform configsCRUD/v1/produce/publish/platforms/{...}produce.publish.platforms.*
Test a connectionPOST/v1/produce/publish/platforms/{id}/testproduce.publish.platforms.test

→ Full sample requests/responses: production-blog-post.md (others stubbed)

Indexing

Get URLs visible. Auto-fires on publish or callable standalone.

Indexing · gsc index

EndpointMethodRESTMCP tool
Submit URL(s) for indexingPOST/v1/indexing/gsc-indexindexing.gsc.submit
Get URL statusGET/v1/indexing/gsc-index?url=...indexing.gsc.status
List recent submissionsGET/v1/indexing/gsc-indexindexing.gsc.list
Connect GSCCRUD/v1/indexing/gsc-index/configindexing.gsc.config.*

Indexing · indexnow

EndpointMethodRESTMCP tool
Submit URL(s)POST/v1/indexing/indexnowindexing.indexnow.submit
List submissionsGET/v1/indexing/indexnowindexing.indexnow.list
IndexNow configCRUD/v1/indexing/indexnow/configindexing.indexnow.config.*

→ Full sample requests/responses: indexing-gsc-index.md

The CRM + outreach engine, plus an autonomous inbound responder.

Link Building · serp outreach

EndpointMethodRESTMCP tool
Start a SERP campaignPOST/v1/link-building/serp-outreachlink_building.serp_outreach.create
List SERP campaignsGET/v1/link-building/serp-outreachlink_building.serp_outreach.list
Get a campaignGET/v1/link-building/serp-outreach/{id}link_building.serp_outreach.get
Get campaign draftsGET/v1/link-building/serp-outreach/{id}/draftslink_building.serp_outreach.drafts
Bulk approve draftsPOST/v1/link-building/serp-outreach/{id}/approvelink_building.serp_outreach.bulk_approve
Update filtersPATCH/v1/link-building/serp-outreach/{id}link_building.serp_outreach.update
Cancel a campaignDELETE/v1/link-building/serp-outreach/{id}link_building.serp_outreach.cancel

Link Building · competitor link outreach

EndpointMethodRESTMCP tool
Start competitor outreachPOST/v1/link-building/competitor-outreachlink_building.competitor_outreach.create
List competitor campaignsGET/v1/link-building/competitor-outreachlink_building.competitor_outreach.list
Get a campaignGET/v1/link-building/competitor-outreach/{id}link_building.competitor_outreach.get
Bulk approve draftsPOST/v1/link-building/competitor-outreach/{id}/approvelink_building.competitor_outreach.bulk_approve

Link Building · inbound

Autonomous negotiation for inbound link-building requests. CitationBench watches your inbox, drafts (and optionally sends) responses to negotiate link swaps, paid placements, guest posts, and link insertions. You set eval gates — conditions that escalate to a human (e.g. partner requests payment, DR below threshold, suspicious sender).

EndpointMethodRESTMCP tool
List inbound messagesGET/v1/link-building/inboundlink_building.inbound.list
Get an inbound messageGET/v1/link-building/inbound/{id}link_building.inbound.get
Ingest a message (webhook)POST/v1/link-building/inbound/ingestlink_building.inbound.ingest
Draft a responsePOST/v1/link-building/inbound/{id}/draftlink_building.inbound.draft
Approve and send responsePOST/v1/link-building/inbound/{id}/approvelink_building.inbound.approve
Reject (mark spam / decline)POST/v1/link-building/inbound/{id}/rejectlink_building.inbound.reject
List pending manual actionsGET/v1/link-building/inbound/pendinglink_building.inbound.pending
Get/update inbound settingsCRUD/v1/link-building/inbound/settingslink_building.inbound.settings.*
Manage eval gatesCRUD/v1/link-building/inbound/eval-gate/{...}link_building.inbound.eval_gate.*
Get/update per-account behaviorCRUD/v1/link-building/inbound/account-settings/{accountId}link_building.inbound.account_settings.*
Get message history with a partnerGET/v1/link-building/inbound/history?accountId=...link_building.inbound.history

Link Building · campaign management

EndpointMethodRESTMCP tool
List all campaignsGET/v1/link-building/campaignlink_building.campaign.list
Get a campaignGET/v1/link-building/campaign/{id}link_building.campaign.get
Get campaign metricsGET/v1/link-building/campaign/{id}/metricslink_building.campaign.metrics
Pause / resume campaignPOST/v1/link-building/campaign/{id}/{pause|resume}link_building.campaign.toggle
Send an outreach emailPOST/v1/link-building/campaign/{id}/send-emaillink_building.campaign.send_email

Link Building · CRM

EndpointMethodRESTMCP tool
List accountsGET/v1/link-building/crm/accountlink_building.crm.account.list
Get an accountGET/v1/link-building/crm/account/{id}link_building.crm.account.get
Update an accountPATCH/v1/link-building/crm/account/{id}link_building.crm.account.update
List relationshipsGET/v1/link-building/crm/relationshiplink_building.crm.relationship.list
Get a relationshipGET/v1/link-building/crm/relationship/{id}link_building.crm.relationship.get
Update relationship statusPATCH/v1/link-building/crm/relationship/{id}link_building.crm.relationship.update
List contactsGET/v1/link-building/crm/contactlink_building.crm.contact.list
Get a contactGET/v1/link-building/crm/contact/{id}link_building.crm.contact.get
Discover contacts (Apollo)POST/v1/link-building/crm/contact/discoverlink_building.crm.contact.discover
List eventsGET/v1/link-building/crm/eventlink_building.crm.event.list
Add a note (event)POST/v1/link-building/crm/eventlink_building.crm.event.create

→ Full sample requests/responses: link-building-serp-outreach.md (others stubbed)

Cross-cutting

Workspaces (agency-only)

EndpointMethodRESTMCP tool
List workspacesGET/v1/workspacesworkspaces.list
Get a workspaceGET/v1/workspaces/{id}workspaces.get
Create a workspacePOST/v1/workspacesworkspaces.create
Archive a workspaceDELETE/v1/workspaces/{id}workspaces.delete
Bulk-action across manyPOST/v1/workspaces/bulk-actionworkspaces.bulk_action

Webhooks

EndpointMethodREST
Register a webhookPOST/v1/webhooks
List webhooksGET/v1/webhooks
Delete a webhookDELETE/v1/webhooks/{id}
Test a webhookPOST/v1/webhooks/{id}/test

Outbound event types (selected): agent.invocation.completed, agent.invocation.failed, agent.invocation.awaiting_approval, link_building.inbound.received, link_building.inbound.requires_review, link_building.email.opened, link_building.email.replied, indexing.url.indexed, produce.publish.completed.

Eval Gates

Eval gates combine deterministic and LLM-evaluated conditions to let an agent run autonomously on 95% of cases and escalate only the 5% that need a human.

Errors

CitationBench uses standard HTTP status codes plus a single error envelope with stable `code`, `message`, `details`, and `requestId` across REST and MCP. Branch on `code` in your client.

On this page

ConventionsAgentResearchResearch · keywordResearch · serpResearch · serp gap analysisResearch · competitorResearch · icpResearch · discussResearch · ai citationResearch · content gapProductionProduction · blog postProduction · landing pageProduction · refineProduction · evaluateProduction · imageProduction · publishIndexingIndexing · gsc indexIndexing · indexnowLink BuildingLink Building · serp outreachLink Building · competitor link outreachLink Building · inboundLink Building · campaign managementLink Building · CRMCross-cuttingWorkspaces (agency-only)Webhooks