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. The MCP tools: MCP tools. Prices and the receipt in detail: Billing, limits and receipts. A five-minute walk: Your first guest post in five minutes.
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 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
2xxanswer of a route marked "receipt" in HTTP routes, in the headerX-Linkio-Usage-Receipt(JSON), withX-Linkio-Usage-Receipt-Urlnaming the route above. Only for a key that holdsbilling:read. - MCP: as
usageReceipton 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. 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), 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.
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.