# How Inciteful works

> Inciteful documentation: getting started, the Agent, citation tracking, white-label reports, deployments, the Shopping app, CLI, REST API and MCP.

Canonical: https://tryinciteful.com/docs
This is the markdown twin of the page above, published by Inciteful for AI agents. It is generated from the same source data as the HTML, so the two never diverge. Reviewed: 2026-07-18.

From the first client workspace to the REST API and the MCP server. Everything on this page is checked against the running product - the test suite fails if a documented endpoint stops existing.

## Getting started

Inciteful does two halves of GEO - Generative Engine Optimization - for agencies and web designers. **Citation tracking** measures whether a client's domain is the answer AI assistants actually give for buyer-intent questions, and who wins the answer instead. The **Agent** turns those measured gaps into a plan your own LLM builds from the client's real records, and Inciteful proves what went live.

**Product boundary:** Product Q&A, Collection guides, and Shopify Product/Collection metafield optimization are the separate
[AI Shopping](https://tryinciteful.com/features/shopping) product.

1. **Create your account.** Start with the [free visibility report](https://tryinciteful.com/report), or begin a 7-day Solo or Pro trial. Agency starts as a paid plan.

2. **Add a client workspace.** One workspace per client: their domain, brand name, and the competitors you want share-of-voice against. Everything - questions, checks, clusters, the report - is scoped to the workspace.

3. **Track the questions that matter.** Add the questions buyers actually ask ("best emergency plumber near me?"). Inciteful refreshes them automatically across ChatGPT, Google AI Overviews and Perplexity.

4. **Ask the Agent what to build.** Open [Agent](https://tryinciteful.com/app#agent) for the client and ask it: it reads the measured runs, says which questions are lost and to whom, and hands you a payload - the measured plan plus the `inciteful-audit` skill - for your own LLM session to build the pages from the client's real records. Inciteful never writes the pages itself.

5. **Publish, then prove it.** Your session publishes the pages and reports each one back. Inciteful independently checks the client domain, public response, redirects, canonical and exact intended artifact, re-measures those questions on the next tracking runs, and shows the movement in the dashboard. A connector response alone never means live.

**Programmatic access:** the CLI, WordPress plugin, REST API and MCP server all authenticate with an API key. Mint one in [Account - API keys](https://tryinciteful.com/account) and copy the `inc_live_…` value - it is shown once.

## Content integrity

Inciteful no longer writes pages for you: the [Agent](https://tryinciteful.com/app#agent) hands your own LLM a measured plan, and every page you publish is held to the same evidence standard before Inciteful calls it live.

### Structure score - what the number means

Every page carries separate measures. **Citability** (0-100) covers answer shape, extractability and source presentation. **Source quality** records whether references were reachable or explicitly supplied as first-party evidence. **Claim verification** records passage-level support. **Output approval** is a server-sealed decision and remains blocked after any edit until evidence is reviewed again. A high citability score is neither a truth claim nor a citation prediction.

### The integrity gate on deployment

A deployment attempt and URL report cannot bypass content approval. Every page needs a current server evidence seal; placeholder sources, dead citations and unsupported high-risk claims return `422 integrity_block` with the offending pages. Any content edit invalidates the seal until source and claim review runs again. Even after approval, automatic tracking begins only when the public verifier finds the intended content on the confirmed client domain.

### Bring your own key

Paid plans let you add your own Anthropic API key in [Account](https://tryinciteful.com/account); Shopping content generation then runs on your key. Plans and monthly cluster quotas are on the [pricing page](https://tryinciteful.com/pricing).

## Citation tracking

You add the questions buyers actually ask; Inciteful refreshes them automatically and records two separate signals: whether the client is named affirmatively in the answer, and whether its domain appears in the cited sources.

- **Included engines.** Every paid plan includes ChatGPT, Google AI Overviews and Perplexity. Claude, Gemini, Google AI Mode and Microsoft Copilot are optional per-client add-ons. Pro and Agency include Microsoft Copilot as a core engine; on Solo it is a $9 per-client add-on.

- **Adaptive sampling, honestly reported.** New, changed or contested questions run 3 samples per engine, aggregated by majority. Stable questions can use a single refresh. Each check row records how many samples produced its verdict.

- **What "Presence" means.** Presence counts an affirmative mention of the brand, domain name or configured alias in answer prose. A negated warning does not count.

- **Alerts on confirmed changes only.** A win or loss on an LLM engine emails you once it has been confirmed at 3 samples, so a single flip cannot page you about a change that is not real. Google AI Overviews is the exception: it is a deterministic SERP scrape read once by design, so one observation is already the confirmed reading and alerts on it directly.

- **Share of voice.** The same checks run for the competitors on the workspace, so the report shows who wins each question, not just whether you did.

- **Source intelligence.** Every check records the domains the assistant leaned on - the map of who currently owns the answers in the niche.

The tracked-question pool is account-wide - spread it across clients however you like. Pool sizes per plan are on the [pricing page](https://tryinciteful.com/pricing); on Agency, adding your own OpenAI, Gemini and Perplexity keys moves tracking onto your keys and opens a larger pool.

## White-label reports

Every client workspace has a shareable report at its own private link - `tryinciteful.com/r/ `, where the slug carries a 128-bit random suffix, so it cannot be guessed or enumerated. Anyone with the link can open it - treat it as a shared secret. It shows Presence over time, the per-assistant grid, share of voice against competitors, and the sources assistants lean on.

- **Your brand, not ours.** Set your agency name and brand colour in the report settings; the page renders in them.

- **Badge removal.** On the Pro and Agency plans the "Powered by Inciteful" badge is removed entirely, so the report reads as your own product. Exports are unbranded on every plan.

- **Honest empty states.** A workspace still running sample checks shows an honest "live tracking is being connected" preview - the report never fabricates numbers it does not have.

- **Publish control.** Disable a report and its URL returns 404 until you re-enable it.

## Deployments

A **deployment** is an append-only evidence trail from approval to outcome. It records the delivery channel, candidate URLs, Inciteful’s independent public-page verification, verified crawler fetches and later AI citations without treating one signal as proof of another.

- The state model begins `deployment_started` -> `urls_recorded`. Verification then yields `transport_verified` when only ancillary/hub URLs pass, `partially_verified_live` when some intended pages match, or `verified_live` only when every unique intended page matches. Only complete `verified_live` coverage can advance the aggregate to `crawler_seen` and `citation_seen`. A failed check remains `verification_failed` with evidence and a retry action.

- WordPress, Shopify, MCP, CLI, API and manual exports all report through the same deployment spine and the same read-only verifier.

- A reported URL is never called live by itself. Per-URL proof is retained during a partial deployment, but every intended cluster page must verify before the cluster is marked implemented and all of its questions enter automatic tracking.

### AI Traffic evidence

AI Traffic accepts bounded request events from Next.js middleware, a Vercel Log Drain, a Cloudflare Worker, an Nginx/Apache forwarder or a custom backend. It does not ingest raw log files, and stored page paths exclude query strings.

- **Retrieval fetch:** a known assistant retrieval user-agent requested a page. The signal is labelled verified only when the source IP also resolves to the vendor’s published network.

- **Indexing crawl:** a training or indexing crawler requested a page. This proves neither an answer nor a human visit.

- **Assistant referral:** a browser arrived from a known assistant origin. It is browser-reported, stored separately and never promoted into crawler proof.

- **Google Search Console:** a separate Google-search dataset. It is never counted as AI Traffic.

### WordPress push

**Discontinued 11 September 2026.** The WordPress connector is no longer offered or supported. Pages are built by your own LLM from the action plan and reported back over MCP, the CLI or a link; Site Health fixes are applied by copy-paste. The endpoints below stay documented for existing installs until they are retired.

The smoothest path. The Inciteful Connector plugin (v1.5.0) connects a WordPress site to your account; you can stage an immutable Content v2 candidate for review and explicitly publish only those exact approved bytes, import legacy clusters from inside wp-admin, or apply an additive retrofit to an existing page (layered as post meta, so the original content is never modified and rollback is instant).

[Download the WordPress plugin](https://tryinciteful.com/inciteful-connector.zip?v=m66)
inciteful-connector.zip - install once per client site

1. **Install it.** In the client's WordPress admin: **Plugins - Add New - Upload Plugin**, choose the `.zip`, then **Activate**.

2. **Connect it.** Open **Inciteful - Connect**, set the API base to `https://tryinciteful.com`, paste your `inc_live_…` key, and click **Save & connect**. Saving registers the site with your account and provisions a per-site receiver token, so the site shows up as a push target.

3. **Publish safely.** Push publishes only that exact unchanged owned candidate under protocol v2. An edited, unrelated or ownership-mismatched post fails closed; an exact replay recognizes the same published post instead of duplicating it. Legacy cluster import and push retain their separately documented slug behavior.

4. **Close the loop.** Verified intended pages start tracking automatically. Deployments then shows vendor-verified crawler fetches and AI citations as separate later evidence.

**No plugin access?** Export the cluster as **WordPress import (.xml)** and use **Tools - Import - WordPress**. The plugin path is better: it keeps schema and re-syncs by slug.

### Exports and copy-as

Legacy saved clusters continue to export in four formats - from the app's Export tab, the API, or the CLI:

| Format | What you get |
| --- | --- |
| markdown | One `.md` per page with frontmatter, plus `llms.txt`, a linking map and an index - built for static-site generators and Git workflows. |
| html | Standalone, styled HTML pages with the JSON-LD embedded - paste-ready for any builder. |
| wordpress | A WXR import file for **Tools - Import**. |
| full | The Implementation Pack zip: every format plus per-page meta and schema files. |

Per page, the app's **Copy as** menu gives an HTML fragment, Gutenberg blocks, or the meta title + description for a builder's SEO fields. Exported files are unbranded on every plan.

### /answers - Inciteful's product-owned library

[tryinciteful.com/answers](https://tryinciteful.com/answers), the matching [/llms.txt](https://tryinciteful.com/llms.txt) and their sitemap entries are maintained as source-controlled Inciteful product identity. Client workspaces can publish only through their own connector and export routes; generated client content can never redefine Inciteful's public answer corpus. The [live public report](https://tryinciteful.com/r/inciteful-455531) remains a separate dated visibility baseline rather than a publishing target.

## Shopify app

**Discontinued 11 September 2026.** The Shopify app is no longer offered or supported. AI Shopping, the module that tracks product-level answers from Google Shopping and Merchant data, continues.

For Shopify stores, Inciteful installs as a native app that optimizes **product and collection pages** for AI shopping assistants - the surface that decides which product gets recommended when a shopper asks an AI what to buy.

This catalog workflow is the separately retained **AI Shopping** product; it uses the
monthly content-generation allowance.

1. **Install the app.** Install **Inciteful** from the Shopify App Store (the button on your [Account](https://tryinciteful.com/account) page's Shopify card takes you there) and approve it in your Shopify admin. An Inciteful workspace is created for the store automatically; agencies can link the store to their own account from inside the app.

2. **Optimize products.** In the embedded app, pick products or collections and click **Optimize**. Inciteful writes Product / Offer / FAQ schema (JSON-LD) through metafields, rendered server-side by the theme extension - non-destructive and fully reversible.

3. **Generate buyer-intent content.** Answer-shaped product Q&A and "best X for Y" collection pages, grounded in the live catalog - the same engine behind the content API.

4. **Track it.** Shopping-query citation tracking shows whether the store's products get recommended by ChatGPT, Google AI Overviews and Perplexity. Optional engine add-ons follow the same evidence model.

**Catalog integrity:** rating and review schema is emitted only from values present in the connected catalog; otherwise those fields are withheld. A write requires an explicit user action and Inciteful records the metafields it owns so they can be removed without deleting unrelated store data.

## Site Health for coding agents

Site Health reports what a crawler actually observed on a client’s website. Most of what it
finds is **infrastructure** – server errors, broken or recursive canonicals, redirect chains,
orphan pages, pages still served over HTTP. Inciteful cannot fix any of that, because it lives in the
client’s own repository. Their coding agent, working in that repository, can.

Every finding already carries a severity, a category, an explanation, a recommendation and the
affected URLs, plus an `action` that says whose job it is:

| action | Meaning | Who fixes it |
| --- | --- | --- |
| `technical_review` | Infrastructure: 5xx, 4xx, redirect chains, canonical loops, HTTP still crawlable, orphan pages, slow responses | The client’s repository – your agent |
| `improve_page` | Page content: missing titles, descriptions, H1s, duplicate metadata, invalid schema | Inciteful’s retrofit flow |

### The skill

Drop the skill into the client repo so the agent knows the workflow, the boundaries and the cost
rules without being told each time:

```
mkdir -p .claude/skills/inciteful-site-health
curl -fsSL https://tryinciteful.com/inciteful-site-health-skill.md \
  -o .claude/skills/inciteful-site-health/SKILL.md
```

Then connect Inciteful as an MCP server with an API key from [Account → API keys](https://tryinciteful.com/account):

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

### Tools and commands

| Surface | What it does | Cost |
| --- | --- | --- |
| `inciteful_site_health` (MCP) | Findings for one workspace, as a work queue | Free, read-only |
| `inciteful_site_health_scan` (MCP) | Starts a new crawl to re-check the site | **Paid** – see below |
| `inciteful health ` (CLI) | The same findings, printed; `--json` for all affected URLs | Free, read-only |
| `GET /api/v1/site-health?workspaceId=…` | The same payload over the REST API | Free, read-only |

### Re-scanning costs money

A re-scan is a real crawl against your monthly Site Health page allowance, so an agent should call
it only once its fixes are committed *and live on the public site* – crawling unchanged
pages spends the allowance to tell you nothing.

**Agent scans are capped per client per day**, on top of the monthly page
allowance, so an agent stuck in a retry loop cannot drain a month of crawl budget in an afternoon.
A refusal carries `site_health_agent_day_cap` and is final – the skill instructs the
agent to report what it fixed rather than retry. Scans you start yourself in the app are never
affected by an agent’s usage.

## CLI

Best for static-site generators (Astro, Hugo, Next, Eleventy), agents and Git-based publishing. The CLI is a zero-dependency single file over the legacy v1 and Content v2 APIs - no install step beyond downloading it:

```
curl -fsSL https://tryinciteful.com/inciteful -o inciteful
chmod +x inciteful

./inciteful login          # paste your inc_live_ key (stored in ~/.inciteful)
./inciteful list           # your saved clusters
./inciteful export   --format markdown --out ./content
./inciteful sync --out ./content   # export every legacy cluster at once
To run it from anywhere, move it onto your PATH: sudo mv inciteful /usr/local/bin/ - then it is just inciteful login.

  CommandDoes
  loginStore an API key in ~/.inciteful/config.json.
  whoamiShow the resolved API base and the masked key.
  list [--workspace  ]List saved clusters - id, niche, pages, updated.
  get   [--out f.json]Raw cluster JSON.
  export   --format   --out ./dirWrite the export file. Formats: markdown, html, wordpress, full.
  sync --out ./dir [--workspace  ] [--format  ]Export every cluster at once.
  logoutForget the stored key.

Auth resolution, first match wins: --key flag, the INCITEFUL_KEY environment variable, then the stored config. The API base follows the same order via --api / INCITEFUL_API - handy for CI.

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

GET `/api/health` No auth

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

GET `/api/plans` No auth

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

GET `/api/demo` No auth

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

### Identity

GET `/api/v1/whoami` Bearer key

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

GET `/api/v1/site-health` Bearer key

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.

| Query | Type | Notes |
| --- | --- | --- |
| workspaceId | string, required | The client workspace. A workspace on another account returns 404. |

**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

GET `/api/v1/clusters` Bearer key

List the account's saved clusters, newest first.

| Query | Type | Notes |
| --- | --- | --- |
| workspaceId | string, optional | Only clusters filed to this workspace. |

**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
```

GET `/api/v1/cluster` Bearer key

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.

| Query | Type | Notes |
| --- | --- | --- |
| id | string, required | Cluster id from `/api/v1/clusters`. |

**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"
```

GET `/api/v1/cluster/pages` Bearer key

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.

| Query | Type | Notes |
| --- | --- | --- |
| id | string, required | Cluster id. |
| workspaceId | string, optional | Brand override when the cluster is not filed to a workspace. |

**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"
```

GET `/api/v1/cluster/export` Bearer key

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

| Query | Type | Notes |
| --- | --- | --- |
| id | string, required | Cluster id. |
| format | string, optional | `markdown`, `html`, `wordpress` or `full`. Default `full`. |

**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.

POST `/api/v1/content/product-questions` Bearer key

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.

| Body field | Type | Notes |
| --- | --- | --- |
| product | object, required | Catalog facts - `title` (required), and any of `description`, `price`, `currency`, `url`, `brand`, etc. |
| shop | object, optional | Shop context (e.g. `{"name":…}`). |
| count | number, optional | 3-10 pairs; default 6. |
| mode | string, optional | `auto` (default), `live` or `mock`. |

**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}'
```

POST `/api/v1/content/collection-page` Bearer key

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`.

| Body field | Type | Notes |
| --- | --- | --- |
| productContext | object, required | `{"collection":{…}, "products":[…], "shop":{…}}` - `products` must be non-empty. |
| niche | string | Topic; defaults to `productContext.collection.title` - one of the two is required. |
| count | number, optional | 3-8 pages; default 4. |
| save | boolean, optional | Default true - the cluster is persisted and its id returned. |
| workspaceId | string, optional | Workspace to file the saved cluster under. |
| mode | string, optional | `auto` (default), `live` or `mock`. |

**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.

POST `/api/v1/schema/product` Bearer key

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"}}'
```

POST `/api/v1/schema/collection` Bearer key

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

POST `/api/v1/prospect/report` Bearer key

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/ ` with a Download-PDF button. Used by `inciteful prospect --publish`.

| Body field | Type | Notes |
| --- | --- | --- |
| agency | object, required | A prospect row with `agencyDomain` and `clientAudits[]`. |
| brand | string, optional | White-label brand name. Defaults to the agency's detected logo alt text. |
| accent | string, optional | Brand accent colour (hex, e.g. `#376EC1`). |

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

### WordPress

**Discontinued 11 September 2026.** The WordPress connector is no longer offered or supported. Pages are built by your own LLM from the action plan and reported back over MCP, the CLI or a link; Site Health fixes are applied by copy-paste. The endpoints below stay documented for existing installs until they are retired.

POST `/api/v1/wp/site/register` Site-scoped `inc_wp_` key

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.

GET `/api/v1/wp/clusters` Paired site-scoped `inc_wp_` key

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

GET `/api/v1/wp/cluster/pages` Paired site-scoped `inc_wp_` key

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

POST `/api/v1/wp/cluster/implemented` Paired site-scoped `inc_wp_` key

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`.

POST `/api/v1/wp/register` Bearer key

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.

| Body field | Type | Notes |
| --- | --- | --- |
| siteUrl | string, required | Public https URL of the site - no credentials, no port, no internal hosts. |
| token | string, required | The site's receiver token, 32-128 visible ASCII characters. Stored encrypted; re-registering the same site rotates it. |
| name | string, optional | Display name. |

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

GET `/api/wp/sites` Bearer key

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

POST `/api/wp/push` Bearer key - owner only

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.

| Body field | Type | Notes |
| --- | --- | --- |
| clusterId | string, required | A saved cluster id. |
| siteId | string, required | From `/api/wp/sites`. An unknown id returns 404 with the registered `sites` so a caller can self-correct. |

**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"}'
```

POST `/api/wp/retrofit` Bearer key - owner only

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.

POST `/api/wp/retrofit/revert` Bearer key - owner only

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

### Deployments

POST `/api/deployments` Bearer key

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.

| Body field | Type | Notes |
| --- | --- | --- |
| clusterId | string, required | A saved cluster id. |
| connector | string, required | One of `self`, `wordpress`, `shopify`, `cli`, `mcp`, `export`, `other`. |
| workspaceId | string, optional | Workspace override. |
| idempotencyKey | string, optional | Stable 8-200 character retry key. Reusing it for the same cluster and connector returns the original attempt instead of creating a duplicate. |

**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`.

POST `/api/deployments/urls` Bearer key

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

| Body field | Type | Notes |
| --- | --- | --- |
| id | string, required | Deployment id. |
| urls | array, required | Candidate public http(s) URLs - plain strings or `{"slug","url"}` pairs (slug = the exported file the URL is expected to serve). Up to 100. |
| replace | boolean, optional | Overwrite the prior set instead of appending. Default false. |
| verify | boolean, optional | Set false only for an asynchronous connector workflow. The state remains `urls_recorded`, never live. |

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.

POST `/api/deployments/verify` Bearer key

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.

POST `/api/deployments/urls/remove` Bearer key

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`.

GET `/api/deployments` Bearer key

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

| Query | Type | Notes |
| --- | --- | --- |
| workspaceId | string, optional | Filter to one workspace. |

**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`:

| Status | Shape | When |
| --- | --- | --- |
| 400 | {"error": "…"} | Validation - the message says which field. A malformed JSON body is `"Invalid JSON body."` |
| 401 | {"error":"Not signed in","code":"unauthenticated"} | Missing or invalid key/session. On `/api/mcp` the 401 body is JSON-RPC instead - see MCP. |
| 402 | {"error","code","usage"} | Plan quota reached (e.g. monthly clusters on `collection-page`). |
| 403 | {"error","code":"owner_only"} | A team member called an owner-only action (API keys, WordPress push, billing). |
| 404 | {"error":"not found"} | Unknown or not-yours id - cross-tenant reads are 404, never 403. `/api/wp/push` adds the registered `sites` to an unknown-site 404. |
| 409 | {"error","code","deploymentId"?} | WordPress receiver failures: `wp_unreachable` / `wp_bad_response`. The deployment stays `deployment_started`. A pre-push failure (stored site token unreadable) returns 409 before any deployment exists, so `deploymentId` is absent. |
| 413 | {"error":"Request body too large."} | Body over 16 MB. |
| 422 | {"error","code":"integrity_block","blocked":[…]} | Starting or recording a deployment while pages carry placeholder, dead-cited or unsupported evidence. |
| 429 | {"error","retryAfter"} | Rate limited - honour the `retry-after` header. On `/api/mcp` the body is a JSON-RPC error (code `-32002`) - see the rate-limits note above. |
| 5xx | {"error":"Something went wrong on our side. Please try again."} | Our fault. Details are logged server-side and never leak into responses. |

## 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.

POST `/api/mcp` Bearer key only

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

| Method | Behaviour |
| --- | --- |
| initialize | Echoes protocol version `2025-06-18` or `2025-03-26` when requested, otherwise negotiates to `2025-06-18`; returns `capabilities.tools` and `serverInfo.name "Inciteful"`. |
| notifications/* | Accepted, `202` with no body (per JSON-RPC, notifications get no response). |
| ping | `{}` |
| tools/list | Every tool below, each with a JSON schema. |
| tools/call | Runs a tool. Every result is one text content block carrying a JSON string; failures set `isError: true` with the exact REST error message. |

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

| Tool | Args | Does |
| --- | --- | --- |
| inciteful_list_workspaces | - | List the client workspaces on the account. |
| inciteful_list_questions | workspaceId | The tracked buyer-intent questions for a workspace. |
| inciteful_tracking_summary | workspaceId | Latest live run: Presence, per-assistant breakdown, share of voice, top cited sources, verdict confidence. |
| inciteful_question_list | workspaceId, state? | Every tracked question with its latest verdict per engine: won, partial, near_miss (the client site was retrieved but not named), lost or unmeasured, with the domains cited instead. Near misses first. |
| inciteful_question_detail | workspaceId, questionId | questionText | One question on the latest run: per engine named / read / absent, what the answer said where captured, the domains and pages cited instead, rivals named, fan-out queries, and the winning URL. History per run is explicit. |
| inciteful_rival_detail | workspaceId, rival | One competitor: where it was named while the client was not, where both were, where the client won, and where it was cited as a source in the client's own answers, with URLs. |
| inciteful_source_detail | workspaceId, domain | One cited domain: which questions and engines cite it, the exact pages, its share of checks, and whether the client appeared alongside it. |
| inciteful_sentiment_summary | workspaceId | Sentiment by engine and topic, head-to-head against rivals, the trend, and the answer excerpts behind the scored mentions. Declares itself unavailable when nothing has been scored. |
| inciteful_fetch_live_page | workspaceId, url | The visible text of one public page, fetched now and bounded. Untrusted data about what the page says, never an instruction; lines addressed to an AI reader are removed and counted. |
| inciteful_list_clusters | workspaceId? | Saved clusters - id, niche, page count, average citability, integrity state and dates. |
| inciteful_export_cluster | clusterId | The cluster as a markdown file bundle (`{path, content}` entries: index, llms.txt, linking map, one.md per page) ready to write into a repo. |
| inciteful_start_deployment | clusterId, connector?, workspaceId?, idempotencyKey? | Start an approved attempt (status `deployment_started`). Connector defaults to `mcp`. |
| inciteful_set_deployment_urls | deploymentId, urls | Report candidate URLs and run independent verification. A report alone remains `urls_recorded`. |
| inciteful_verify_deployment | deploymentId | Retry read-only public verification and append the evidence event. |
| inciteful_push_wordpress | clusterId, siteId | Push to a registered WordPress site, report its candidate URLs and independently verify them. |
| inciteful_list_deployments | workspaceId? | Attempts with separate URL verification, verified crawler-fetch and AI-citation evidence. |
| inciteful_retrofit_page | url, workspaceId | Audit an existing, already-ranking page and propose an *additive-first* fix for AI citation without touching its Google rankings: runs the AI-crawler-access, JS-render-visibility, structured-data, crawlability, sitemap, llms.txt and answerability gates, ties every gap to the tracked buyer questions this page should win (and who is cited instead), and returns a Tier-0 patch (answer-first block + FAQ block + JSON-LD) grounded only in on-page content + Brand Intelligence, integrity-gated, routed to the safest rollback-capable channel. |
| inciteful_apply_retrofit | url, workspaceId, siteId? | Apply the retrofit. On WordPress (with `siteId`) it lands as a reversible post-meta layer; for a headless/repo stack it returns the diff to apply. Records a retrofit deployment so later tracking can show whether the result changes. |
| inciteful_site_health | workspaceId | Read the latest Site Health findings as a technical work queue, including severity, explanation, recommendation and affected public URLs. |
| inciteful_site_health_scan | workspaceId, maxCrawlPages? | Start a paid asynchronous crawl after fixes are live. It consumes the account's Site Health page allowance; read results later with `inciteful_site_health`. |
| inciteful_revert_retrofit | url, siteId | Remove a previously applied WordPress retrofit - deletes the layered post meta, leaving the original post untouched. Instant rollback. |

### Add it to Claude

Create an API key in [Account](https://tryinciteful.com/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"}'
```

[Back to the app](https://tryinciteful.com/app) · [hello@tryinciteful.com](mailto:hello@tryinciteful.com)