How Inciteful works

API reference

The REST surface behind the CLI, the WordPress plugin and any custom build. Base URL https://tryinciteful.com. Requests and responses are JSON unless a download is noted; request bodies are capped at 16 MB.

Authentication

Create an API key in Account - API keys (owner-only; the raw inc_live_… value is shown once, and keys can be revoked at any time). Send it as a Bearer token:

curl -H "Authorization: Bearer inc_live_YOUR_KEY" https://tryinciteful.com/api/v1/clusters

Endpoints marked Bearer key below also accept the app's session cookie, so they work from the browser too. The one exception is the MCP endpoint, which accepts only a Bearer key by design. A missing or invalid key returns 401 {"error":"Not signed in","code":"unauthenticated"}.

Rate limits: the API surface - every /api/v1/* endpoint plus the MCP endpoint - allows 300 requests per minute per account. Exceeding it returns 429 with a retry-after header; on /api/mcp the 429 body is a JSON-RPC error (code -32002) carrying the same retryAfter. Generation endpoints (content, scan, strategy) stay limited to 40 calls per hour per account, with the same 429 + retry-after contract.

Public endpoints - no auth

Service status: {"ok":true, "platformLive":…, "model":…, "billingEnabled":…, "seedNiche":…}.

The live plan catalog: {"plans":[…], "billingEnabled":…, "purchasable":[…]} - the same data the pricing page renders.

A full demo cluster ({"cluster":…}) - useful for exploring the cluster shape without generating one.

Identity

Who this key belongs to - the first call an integration should make to confirm it is wired up.

Response 200 - {"ok":true, "email", "plan"}. A team member's key resolves to the account owner, the same way every other route scopes.

curl -H "Authorization: Bearer inc_live_YOUR_KEY" https://tryinciteful.com/api/v1/whoami

Site Health

The latest Site Health findings for one client, shaped as a work queue for a coding agent (see Site Health for coding agents). Read-only and free.

Response 200 - {"workspaceId","clientDomain","status","score","scope","pagesChecked","findings":[{"id","severity","category","title","explanation","recommendation","action","affectedCount","affectedUrls","providerField"}],"counts":{"total","technicalReview","improvePage"},"definitions"}. action is technical_review (the client’s own repository) or improve_page (Inciteful’s retrofit flow). A client with no completed audit returns status:"no_audit" with an empty findings array and a note - never a silent empty list.

curl -H "Authorization: Bearer inc_live_YOUR_KEY" \
  "https://tryinciteful.com/api/v1/site-health?workspaceId=WORKSPACE_ID"

Clusters

List the account's saved clusters, newest first.

Response 200 - {"clusters":[{"id","workspaceId","niche","brand","pages","avgScore","citabilityScore","integrity","createdAt","updatedAt","publishedAt"}]}. avgScore is the compatibility/readiness score; use citabilityScore and integrity for the separated customer-facing measures.

curl -H "Authorization: Bearer inc_live_YOUR_KEY" \
  https://tryinciteful.com/api/v1/clusters

One saved cluster in full - pieces, scores, linking map - plus its loop state (publish date, first citation, days-to-citation, refresh-due). Deployment records and per-URL citation proof live on GET /api/deployments.

Response 200 - {"cluster":…}. Unknown id: 404 {"error":"not found"}.

curl -H "Authorization: Bearer inc_live_YOUR_KEY" \
  "https://tryinciteful.com/api/v1/cluster?id=CLUSTER_ID"

Per-page, ready-to-insert payloads for headless importers - each page is pre-rendered and branded, so your CMS never re-implements rendering. This is the endpoint the WordPress plugin consumes.

Response 200 - a cluster summary plus pages, one entry per page:

{
  "cluster": { "id", "niche", "siteName", "workspaceId" },
  "pages": [{
    "slug", "title", "metaTitle", "metaDescription",
    "intent", "cluster", "schemaTypes",
    "gutenberg",   // WordPress block markup
    "html",        // body fragment (no doctype)
    "jsonld",      // schema, as a JSON string
    "related": [{ "question", "slug" }]
  }]
}

curl -H "Authorization: Bearer inc_live_YOUR_KEY" \
  "https://tryinciteful.com/api/v1/cluster/pages?id=CLUSTER_ID"

Download a cluster export as a file (zip, or xml for wordpress).

Response 200 - the file, with a content-disposition filename.

curl -OJ -H "Authorization: Bearer inc_live_YOUR_KEY" \
  "https://tryinciteful.com/api/v1/cluster/export?id=CLUSTER_ID&format=markdown"

Shopping catalog content generation

The channel-agnostic engine surface the Shopify app is built on - usable from any commerce stack. Generation endpoints are rate-limited (40/hour) and honour your BYOK key when one is set.

Product boundary: these Product Q&A and Collection endpoints belong to the separately retained Shopping product and target exact commerce resources.

Buyer-facing Q&A for one product, grounded in the catalog facts you supply. The server verifies returned claims against that catalog evidence and withholds unsafe items before any metafield write.

Response 200 - {"faqs":[{"question","answer"}], "mode"}.

curl -X POST https://tryinciteful.com/api/v1/content/product-questions \
  -H "Authorization: Bearer inc_live_YOUR_KEY" -H "content-type: application/json" \
  -d '{"product":{"title":"Trail running shoe","price":"129","currency":"GBP"},"count":5}'

A "best X" / comparison content cluster for a product collection, grounded in the real products you pass. Counts toward the plan's monthly cluster quota; saved automatically unless save:false.

Response 200 - {"clusterId", "cluster"} (clusterId is null with save:false). Over quota: 402 with {"error","code","usage"}.

Product schema

Deterministic JSON-LD builders with the integrity gate built in: offers are omitted unless a real price and currency exist, ratings and reviews are withheld unless they carry real values and provenance - fabricated trust signals are structurally impossible. issues lists everything that was withheld or dropped, and why.

Body: {"product":{…}} - title, url, description, price/currency, images, brand, sku, faqs, breadcrumbs, and optionally real aggregateRating/reviews data.

Response 200 - {"jsonld":{"@context","@graph":[Product, FAQPage?, BreadcrumbList?]}, "issues":[…]}.

curl -X POST https://tryinciteful.com/api/v1/schema/product \
  -H "Authorization: Bearer inc_live_YOUR_KEY" -H "content-type: application/json" \
  -d '{"product":{"title":"Trail running shoe","url":"https://shop.example/products/trail",
       "price":"129","currency":"GBP"}}'

Body: {"collection":{"title","url","description","products":[…],"faqs","breadcrumbs"}}. Products need a title and an http(s) URL to be listed.

Response 200 - {"jsonld":{"@graph":[CollectionPage, ItemList, FAQPage?, BreadcrumbList?]}, "issues":[…]}.

Prospecting

Publish an agency prospect report to a shareable public link. Send a prospect row (the shape from inciteful prospect --json); the server renders a branded, self-contained report and hosts it at /p/<slug> with a Download-PDF button. Used by inciteful prospect --publish.

Response 200 - {"slug","url"}. The report is public at url until unpublished.

WordPress

Pairs a newly issued WordPress credential to its one expected site and workspace. The plugin supplies siteUrl, its 32–128 character receiver token, and an optional display name. This is the only call an unpaired key can make; a site or workspace mismatch fails closed.

Lists only saved clusters belonging to the credential’s bound workspace. An inc_wp_ credential cannot access account-wide API or MCP methods.

Returns the reviewed WordPress page payload for ?id=CLUSTER_ID. Cross-workspace clusters return 404; content with unresolved integrity blockers returns 422 integrity_block.

Finalizes a plugin import with the complete {slug,url} mapping. Every intended page must be reported and independently pass HTTP, canonical and content verification before the cluster is marked implemented or tracking begins; incomplete or unverified sets return 409.

Legacy account-key registration. When scoped WordPress credentials are enabled this returns 410 scoped_wordpress_credential_required; new Connector installations use the four site-scoped endpoints above.

Response 200 - {"ok":true, "site":{"id","siteUrl","name"}}. Validation failures are 400 with a readable error.

Response 200 - {"sites":[{"id","siteUrl","name","lastPushAt"}]}. Receiver tokens are never returned.

Push a saved cluster to a registered site: creates a wordpress deployment, nudges the site's Connector plugin to pull and publish the cluster (re-push updates the same posts by slug), records the candidate URLs it reports, then independently verifies the public pages.

Response 200 - {"ok":true, "deploymentId", "urls":[…], "verification", "deploymentStatus"}. If the receiver cannot be reached or reports no URLs, the response is 409 with code wp_unreachable or wp_bad_response; the deployment stays deployment_started. Receiver success with failed public verification remains verification_failed, not live. Team members get 403 owner_only.

curl -X POST https://tryinciteful.com/api/wp/push \
  -H "Authorization: Bearer inc_live_YOUR_KEY" -H "content-type: application/json" \
  -d '{"clusterId":"CLUSTER_ID","siteId":"SITE_ID"}'

Apply a retrofit patch to an EXISTING page on a registered site: the Connector (v1.2.0+) appends the additive answer-first + FAQ blocks and injects the JSON-LD, keeping the prior version as a WordPress revision. A retrofit deployment is recorded so later tracking can show whether the page's result changes. Body: {"url","siteId","workspaceId","patch"} where patch is the reviewed patch object from a retrofit audit - what you reviewed is exactly what lands.

Revert a previously applied retrofit on that page: {"url","siteId"}. The Connector restores the pre-retrofit revision and removes the injected JSON-LD.

Deployments

Start an approved deployment attempt. The workspace is inherited from the cluster unless overridden. This records intent and an audit event; it is not evidence that a page is live.

Response 200 - {"deployment":{"id","clusterId","workspaceId","connector","status":"deployment_started","urls":[],"createdAt","approvedAt","updatedAt"}}. A cluster not filed to a client with a website returns 422 with code no_client_domain.

Report candidate public page URLs. By default Inciteful immediately performs read-only independent verification against the confirmed client domain.

Calls append and dedupe by host+path (www and trailing slashes normalized). The verifier checks host ownership, HTTP status, redirects, canonical and expected generated content. Duplicate URLs for one page count once. An ancillary URL can produce only transport_verified; some uniquely matched intended pages produce partially_verified_live; every unique expected page must match before the aggregate becomes verified_live and automatic cluster tracking starts.

Response 200 - {"deployment":…, "verification":{"status","deploymentStatus","verified","failed","contentVerified","contentExpected","contentMissing","contentCoverage","ancillaryVerified","missingSlugs"}}. verified is the raw per-URL transport count; use the content coverage fields for aggregate success. autoPublished: {"publishedAt","linked"} appears only after complete intended-page coverage passes the integrity gate.

Retry independent verification after a DNS, page, redirect, canonical or content fix. Body: {"id":"DEPLOYMENT_ID"}. Verification is read-only and appends a new audit event; the prior evidence remains visible.

Remove one recorded URL from a deployment (a mistyped paste should not sit as "not cited yet" forever). Body: {"id","url"} - the URL is matched by normalized host+path. Unknown deployment or URL: 404.

List deployment attempts with their append-only audit events and per-URL verification, crawler and citation evidence.

Response 200 - {"deployments":[…]}. Each URL can carry verification, crawler and cited/citedAt/citedBy/question independently. Deployment summaries expose intended verifiedUrls, separate transportVerifiedUrls, crawlerSeenUrls, citedUrls, the derived stage, and events. Ancillary and partial per-URL observations remain visible but cannot promote the aggregate stage beyond transport_verified or partially_verified_live.

curl -H "Authorization: Bearer inc_live_YOUR_KEY" \
  "https://tryinciteful.com/api/deployments?workspaceId=WORKSPACE_ID"

Errors

Errors are JSON with a readable error message and, where a caller can act on it, a stable code:

MCP server

Inciteful is an MCP (Model Context Protocol) server: AI agents - Claude Code, Claude Desktop, claude.ai custom connectors, any MCP client - can read the same measured evidence the dashboard shows - workspaces, tracked questions, per-engine verdicts, rivals, sources and sentiment - and use the saved-cluster export and deployment tools.

A single stateless Streamable-HTTP endpoint speaking JSON-RPC 2.0 - no SSE stream, no session id. Auth is the same inc_live_… key as the REST API, but key-only: a browser session cookie is deliberately not accepted, so a logged-in browser can never be driven into this endpoint cross-site. A missing or invalid key returns HTTP 401 with a JSON-RPC error body (code -32001), not the REST error shape - agents parse it:

{"jsonrpc":"2.0","id":null,"error":{"code":-32001,
  "message":"unauthorized - send Authorization: Bearer inc_live_... (create an API key in Account)."}}

The 401 also carries a standard WWW-Authenticate: Bearer challenge (RFC 6750), so a connector client gets a machine-readable reason rather than an opaque internal error id.

Adding Inciteful as a Claude connector

Inciteful does not run an OAuth authorization server. It does not implement dynamic client registration (RFC 7591) or a PKCE authorize/token pair, so Claude's “Add custom connector” Sign in button has nothing to talk to and will fail. That is a deliberate current limitation, not a misconfiguration — we would rather refuse honestly than publish discovery metadata that starts a login flow which cannot finish.

Use the API key instead. It is the supported path and gives the same access:

1. In Inciteful, open Account → API keys and create a key (inc_live_…). Copy it — it is shown once.
2. In your MCP client, add https://tryinciteful.com/api/mcp as a Streamable-HTTP server.
3. Set the header Authorization: Bearer inc_live_….

For Claude Code:

claude mcp add --transport http Inciteful https://tryinciteful.com/api/mcp \
  --header "Authorization: Bearer inc_live_YOUR_KEY"

The key is account-scoped and owner-only: a team member's key cannot reach another account's clusters, and a browser session cookie is never accepted here.

Protocol

Malformed JSON is -32700, a structurally invalid request (wrong jsonrpc, missing method, batch arrays) is -32600, an unknown method is -32601, an unknown tool name is -32602. Internal tool faults return an isError result with a generic message - stack traces never leave the box.

Tools

Add it to Claude

Create an API key in Account, then:

claude mcp add --transport http Inciteful https://tryinciteful.com/api/mcp \
  --header "Authorization: Bearer inc_live_YOUR_KEY"

Any MCP client that can send an Authorization header works the same way: URL https://tryinciteful.com/api/mcp, header Authorization: Bearer inc_live_YOUR_KEY. Claude Desktop and claude.ai custom connectors currently accept only OAuth-based remote servers (no custom headers), and Inciteful does not expose OAuth yet - use Claude Code or a header-capable client for now.

Smoke test:

curl -s https://tryinciteful.com/api/mcp \
  -H "authorization: Bearer inc_live_YOUR_KEY" -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'