# Linkio API for account callers

The contract for a script or an agent that calls Linkio with an account API key. Every list, code, field
and number on this page is checked against the code on every build.
The routes a key can call: [HTTP routes](/docs/api/routes). The MCP tools: [MCP tools](/docs/api/tools).
Prices and the receipt in detail: [Billing, limits and receipts](/docs/api/billing). A five-minute walk: [Your first guest post in five minutes](/docs/agents/first-job).

## 1. Authenticate

A key starts with `acc_`. Send it in one of two headers; both are read the same way:

```
X-API-Key: acc_...
Authorization: Bearer acc_...
```

Create a key on the API keys page, or with `POST /api/account/api-keys` from an account sign-in; a key
cannot mint keys (an `acc_` key gets `403` `owner_only`). Body: `name` (required), `scopes` (required, from
the list below), `clientId` (optional: the key sees one brand only), `description`, `expiresAt`. The key is
shown once. At most 10 active keys per account; `DELETE /api/account/api-keys?id=<keyId>` revokes one (a key holding
`api-keys:write` may revoke its account's keys). No account yet? [Sign up as an agent](/docs/agents/signup) creates one from the API.

Base URL: `https://www.linkio.com`. Answers are JSON. A missing or revoked key answers `401`.

The smoke test — the first call to make with a new key, free, no scope beyond `billing:read`:

```
curl -s -H 'X-API-Key: acc_your_key' https://www.linkio.com/api/account/usage/receipt
```

`200` with the receipt (balance, holds, budget left, `canStartPaidWork`) means the key works; `401` means it does not.

## 2. Scopes

A scope is `namespace:action`; the actions are `read`, `write` and `purchase`. A route names the scope it
needs; a key without it answers `403` with `error` `insufficient_scope`, `code` `SCOPE_DENIED` and
`required_scope`. An account sign-in holds every scope; a key holds only the ones it was created with.

Two key types exist. A self-serve account's key may hold any of these 43 scopes:
`orders:read`, `orders:write`, `line-items:read`, `line-items:write`, `websites:read`, `workflows:read`, `workflows:write`, `topic-gen:read`, `topic-gen:write`, `article-gen:read`, `article-gen:write`, `billing:read`, `billing:write`, `search-queries:read`, `search-queries:write`, `bulk-analysis:write`, `client-config:read`, `client-config:write`, `collaborative-placements:read`, `citation:read`, `citation:write`, `change-requests:read`, `change-requests:write`, `opportunities:read`, `opportunities:write`, `account-campaign:read`, `account-campaign:write`, `llm-tracking:read`, `llm-tracking:write`, `asset-bank:read`, `asset-bank:write`, `crm:read`, `crm:write`, `credits:purchase`, `prospect-pipeline:read`, `prospect-pipeline:write`, `campaign:read`, `campaign:write`, `agents:read`, `agents:answer`, `agent-reports:read`, `api-keys:read`, `api-keys:write`.

A managed account's key may hold these 33 scopes: `orders:read`, `orders:write`, `line-items:read`, `line-items:write`, `workflows:read`, `workflows:write`, `topic-gen:read`, `topic-gen:write`, `article-gen:read`, `article-gen:write`, `billing:read`, `citation:read`, `citation:write`, `llm-tracking:read`, `llm-tracking:write`, `search-queries:read`, `search-queries:write`, `client-config:read`, `client-config:write`, `collaborative-placements:read`, `opportunities:read`, `opportunities:write`, `asset-bank:read`, `asset-bank:write`, `crm:read`, `crm:write`, `account-campaign:read`, `account-campaign:write`, `change-requests:read`, `change-requests:write`, `bulk-analysis:write`, `websites:read`, `agents:read`. A managed key does what the account's own dashboard does, order creation included. It never sees Linkio's cost, the publisher behind a placement, or Linkio's internal notes: that is decided by the account's type, not by the scopes on the key. `agents:answer` (self-serve) answers an agent's question as the person signed in through a connector; a key names no person, so it reads but never answers. A managed key on a self-serve-only route (site search, for one) answers `403` `ACCOUNT_TYPE_DENIED`.

`billing:write` changes the account's own spending limits and card, and the subscription: cancel or undo (`subscription_cancel`), auto top-up (`subscription_credit_refill`) and the Stripe portal link (`subscription_customer_portal`); an `orders:write` key without `billing:write` cannot call them. The keys page offers four access levels — Reporting, Read only, Automation and Full access — and
opens on Automation for a self-serve account and on Reporting for a managed one. Full access sends every scope on the list, `billing:write`
included. Automation sends everything except `billing:write`, `api-keys:read` and
`api-keys:write`, so an agent key does the work without touching the account itself. Under the
picker, one line says what an AI agent can do with the chosen level: with Reporting it can only read. A key can
also be scoped to one brand, which is what makes it safe to hand to a client.

An agent that places orders, books sites, messages publishers or passes QA needs a key that can write:
Automation, or at least `orders:write` and `line-items:write`. A Reporting or Read only key can only read,
so every write tool is missing from its MCP tool list. To change what a key may do, create a new key
with the level you need and revoke the old one.

| Namespace | What the scope covers |
|---|---|
| `orders` | View and manage guest post orders |
| `line-items` | View and manage individual line items within orders |
| `websites` | Browse available publisher websites |
| `workflows` | View and manage article workflows |
| `topic-gen` | Generate topics and keywords for articles |
| `article-gen` | Generate and manage AI-written articles |
| `billing` | View credit balance and billing history; write changes your own spending limits, card and subscription (cancel, auto top-up) |
| `search-queries` | Import and manage search query research |
| `bulk-analysis` | Run bulk domain analysis |
| `client-config` | View and update client settings, target pages and provider keys |
| `collaborative-placements` | View collaborative placement opportunities |
| `citation` | View AI citation and ranking data |
| `change-requests` | Reserved, no tool yet |
| `opportunities` | View and manage link exchange opportunities and partner pages |
| `account-campaign` | Your campaigns over HTTP (/api/account/campaigns); no MCP tool yet |
| `llm-tracking` | Track where AI assistants mention and cite your brand (AI Mentions) |
| `asset-bank` | Manage the pages and sites you offer in link exchanges |
| `crm` | View CRM and communication data |
| `credits` | Buy prepaid credit (purchase only) |
| `api-keys` | List your account's API keys; write revokes one (creating a key stays owner-only) |
| `prospect-pipeline` | Create, list and read keyword prospecting campaigns and match their results to the sites you can buy or exchange (pair it with campaign:* to work inside them) |
| `campaign` | Work inside a prospecting campaign: SERP searches, classification, campaign types, page checks, contacts, outreach and exports (pair it with prospect-pipeline:* to create the campaign) |
| `agents` | See what your agents ask you and what they did; reply and answer as yourself |
| `agent-reports` | Read the reports made for your brand (keyword research) |

## 3. Refusals

| Status | `code` | Meaning | What to do |
|---|---|---|---|
| `401` | | No key, or a revoked or expired key | Create a key |
| `403` | `SCOPE_DENIED` | The key lacks `required_scope` | Create a key with that scope |
| `403` | `ACCOUNT_TYPE_DENIED` | A managed key on a self-serve-only route | Nothing: the route is not for managed accounts |
| `429` | `DAILY_READ_CAP` | The key passed 5000 reads per key per UTC day | Wait for `resetsAt`; `Retry-After` is set |
| `429` | `RATE_LIMIT_EXCEEDED` | MCP only: 60 calls per minute with a burst of 20 | Wait `Retry-After` seconds |
| `402` | one of six, below | The account cannot fund this start | Read the body: it names the way out |
| `503` | `TENANT_RESOLUTION_TIMEOUT` | Linkio could not confirm who pays for a write (or a paid read) in time, a cold process; no job was started and nothing was held for one (the per-call write fee of a counted call still applies) | Repeat the same call once after `Retry-After` seconds (2); if it repeats, wait a minute |

## 4. The 402 bodies

A route that spends checks money before it works. A refusal is a `402` with one of three JSON shapes.
The `code` field tells them apart; `error` is a plain sentence for a person; `estimateCents` is what the
start would have held.

### Budget: `budget_exceeded` or `budget_paused`

```
{ error, code, scope, feature, apiKeyId, period, limitCents, spentCents, heldCents, estimateCents,
  remainingCents, affordableCount?, resetsAt, approvalId: null,
  raise: { canSelfRaise, maxSelfServeCents, settingsUrl, api, requestIncreaseApi } }
```

`scope` says which limit stopped the start (the account's month, a feature, this key's day or month).
`raise.api` is `PUT /api/account/usage-limits` (needs `billing:write`); when `canSelfRaise` is false the
budget is at `maxSelfServeCents` and `requestIncreaseApi` asks Linkio for more. `affordableCount` is how
many units the remaining budget would fund, when the start was for several.

### Approval: `needs_approval`

```
{ error, code, scope, feature, apiKeyId, estimateCents, askOverCents, approvalId, expiresAt, refused?,
  approve: { settingsUrl, waitingUrl, api, header, listApi, tool } }
```

The job costs more than the account's "ask me before any job over" amount (`askOverCents`). The
decision is the account owner's. A key that holds `billing:write` may record it: `approve.api` is
`POST /api/account/usage-limits/approvals/<approvalId>` with body `{"decision":"approve"}` or
`{"decision":"deny"}`; the MCP tool is `usage_approvals_decide` (`approve.tool`), marked destructive so a
client asks the person at the keyboard first. Answers: `404` for an unknown or another account's id,
`409` when already decided, `410` when expired. A key without `billing:write` hands the owner
`approve.waitingUrl` (the Waiting view of the activity page) or `approve.settingsUrl`; `listApi`
(`GET /api/account/usage-limits/approvals`) reads the state. Once approved, repeat the same call;
optionally name the approval in the header `X-Linkio-Approval` (`approve.header`), with the
`approvalId` as its value. The approval is matched to the retry by account, feature, key and `jobRef`
(the batch, workflow or order the start names), not by the exact estimate, so a retry that costs a little
more still runs. `refused` is set when a previous decision was a denial.

### Card: `card_required`, `payment_failed` or `credit_line`

```
{ error, code, reason, feature, estimateCents, prepaidCents, cardStatus, unbilledCents, creditLineCents,
  pausedAt, card: { settingsUrl, api, statusApi, setupLinkApi, payNowApi } }
```

Prepaid balance does not cover the start and no card can. `card_required`: no card (or the card was
removed); `payment_failed`: the last charge failed and paid work is paused until the card changes;
`credit_line`: unbilled usage is at `creditLineCents` and is charged shortly. Adding a card is the
owner's click: `card.setupLinkApi` (`billing:write`) returns a Stripe-hosted page to hand to the owner;
`card.statusApi` reads the card; `card.payNowApi` (`billing:write`) charges the unbilled balance now.

### The convert hint

When the account holds placement credit (`link_building`) that the meter cannot spend, the card body
(or a route's older `Insufficient credits` body) adds `convertibleCents` and a `convert` object with
`route` `/api/account/credits/convert`, `tool` `credits_convert`, `rate` `1:1`, `from` `link_building`
and `to` `general`. `POST /api/account/credits/convert` (`billing:write`) moves that amount into
spendable credit at 1:1.

### Confirm first: `CONFIRM_REQUIRED` (a `400`, not a refusal)

A paid prospecting start (the SERP scan, classification, the page checks, contact discovery, email verification,
the outreach polish) answers `400` with `code: "CONFIRM_REQUIRED"` when the body carries no `confirm: true`:
`{ error, code, estimatedCostCents, quote, confirmMessage, … }` — `error` is the API wording ("Send confirm: true
to start …"), `quote` the meter's parts, `confirmMessage` the sentence a person is asked ("… holds about $X … Start?").
Nothing is held. Repeat the same body with `confirm: true` to start; `dryRun: true` answers the same quote with
no confirm step. Through MCP the tools send `dryRun` / `confirm` only when you give them.

## 5. The receipt

`GET /api/account/usage/receipt` (needs `billing:read`) answers where the account stands:
`accountId`, `period`, `asOf`, `spentCents`, `heldCents`, `budgetCents`, `budgetRemainingCents`,
`resetsAt`, `prepaidCents`, `unbilledCents`, `cardStatus`, `cardHeadroomCents`, `canStartPaidWork`,
`feesCents`. `canStartPaidWork` is the one bit to read before a paid call.

The same object (without `accountId` and `asOf`) comes back without a second call:
- API: on every `2xx` answer of a route marked "receipt" in [HTTP routes](/docs/api/routes), in the header
  `X-Linkio-Usage-Receipt` (JSON), with `X-Linkio-Usage-Receipt-Url` naming the route above. Only for
  a key that holds `billing:read`.
- MCP: as `usageReceipt` on every write tool's result.

## 6. Prices and the estimate

Prices are not on this page. `GET /api/pricing/self-serve` (public) returns the per-job fees, the
markup on provider cost when a job runs on Linkio's keys, and the publisher price range; the per-job
rules are in [Billing, limits and receipts](/docs/api/billing). Before a paid start,
`GET /api/account/usage/estimate?feature=<article|topic_generation|target_page_ai|ai_find_sites|website_search|site_metrics|serp_search|prospect_contact_discovery|prospect_email_verify|outreach_polish|prospect_classify|prospect_enhance>&count=N`
(`billing:read`; MCP `usage_estimate`) answers the exact hold the start would take. Every API or MCP
write call carries a per-call fee; reads are free and capped as in section 3.

## 7. Idempotency and retries

There is no idempotency key: no route an account can call reads an `Idempotency-Key` header. A call that starts work
(an article, a topic session, a site search, a batch) answers with a run, batch or job id; the caller
watches that id through its status route or tool and never starts the work again. A step re-run after
a reset is a new job and is charged again. The approval retry (section 4) is the one place a repeated
call is expected, and it is matched by `jobRef`, not by a header you invent.

The HTTP API has no rate limit of its own beyond the daily read cap; the MCP server rate-limits per key
(section 3). A `429` carries `Retry-After` in seconds. A `503` `TENANT_RESOLUTION_TIMEOUT` (section 3) is the
other answer that is safe to repeat as is: the call was refused before any job started, so the same request
again after `Retry-After` seconds is not a second job (each counted call still carries its per-call write
fee). Repeat once; if it answers the same way, wait a minute before the next try.

## 8. Connect an agent

MCP endpoint: `https://mcp.linkio.com/mcp`, header `Authorization: Bearer <your key>`. The server lists
only the tools the key's scopes allow ([MCP tools](/docs/api/tools)), answers `usageReceipt` on every
write, and serves the agent rules as its instructions.

Claude Code, with the key written into the header:

```
claude mcp add --transport http linkio https://mcp.linkio.com/mcp --header "Authorization: Bearer acc_your_key"
```

If the client config reads the key from the environment (`"Authorization": "Bearer ${LINKIO_API_KEY}"`),
export `LINKIO_API_KEY` before you start the client. When the client sends the header without the key,
the server tells you so:

| Answer | Meaning | What to do |
|---|---|---|
| `401` `Missing Authorization header` | No `Authorization` header, or `Bearer` with no key after it | Add the header with the key |
| `403` `Invalid API key`, with a `hint` about a placeholder | The client sent the variable name (for example `${LINKIO_API_KEY}`), not the key | Export the variable before you start the client, or write the key into the header |
| `403` `Invalid API key`, `Unrecognized credential format` | The value is not a Linkio key | Copy the key again from the keys page |

Connectors that sign in instead of pasting a key (Claude.ai, ChatGPT) use OAuth 2.1:
`/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource` publish the
endpoints; `POST /api/oauth/register` registers the client (RFC 7591, no credentials needed);
the authorize step is PKCE (`S256`); `/api/oauth/token` supports `authorization_code` and
`refresh_token`. There is no `client_credentials` grant: OAuth signs an existing account in, it cannot
create an account. The access token is a JWT and travels only as `Authorization: Bearer`.

## 9. Sign up as an agent

Moved to its own page: [Sign up as an agent](/docs/agents/signup).

## 10. Choose the seller

Many sites have more than one seller: the site's owner, and resellers who sell placements on it. Each
search result says who sells the site (`seller.label`: `owner`, `reseller` or `owner_unverified`), whether
that seller is proven (its latest paid order on the site cost no more than its price today), and the
owner's price when an owner offer exists. A reseller is a label, never a name.

A seller policy decides which seller a site is priced and booked with:

| Policy | The seller |
|---|---|
| Linkio default, `linkio_default` | The verified owner, unless a reseller is at least 15% cheaper and its latest paid order on the site proves that price |
| Owner only, `owner_only` | Verified owners only; sites with no owner are left out of a search |
| Proven only, `proven_only` | Only sellers whose latest paid order on the site cost no more than their price today |
| Cheapest, `cheapest` | The lowest price from any seller in good standing |

Set it at three levels; the closest one wins. A search takes `sellerPolicy` for that search. An order
takes `sellerPolicy` when you create it (`order_create`) or later (`PUT /api/orders/<id>/seller-policy`). The account default is read and changed with
`account_seller_policy_get` and `account_seller_policy_set` (`GET` and `PUT /api/account/seller-policy`).
A site added to an order is booked with the seller and price that a search under the same policy shows.
When a policy has no seller on a site, the site is booked with the `linkio_default` seller and the
result says `sellerPolicyFallback`. `ownerAvailable` and `provenSeller` filter a search to sites with an
owner offer or a proven seller. A managed account's policy is set by its account manager.

## 11. Tell Linkio when something breaks

`report_issue` sends a bug, a missing feature, a request or wrong data to the Linkio team: what you
tried (no secrets), what happened and what you expected, with an order or line item id when one applies.
Every key sees it, whatever its scopes. The same problem sent again counts as a repeat, not a new report.
`report_status` lists your own reports, with their status and the team's notes. A failed tool call is
also recorded on Linkio's side, so a silent failure reaches the team even when nobody reports it.
