Documentation

API reference

Authentication, scopes, refusals, the 402 bodies, the receipt, idempotency, the seller policy and report_issue.

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.

NamespaceWhat the scope covers
ordersView and manage guest post orders
line-itemsView and manage individual line items within orders
websitesBrowse available publisher websites
workflowsView and manage article workflows
topic-genGenerate topics and keywords for articles
article-genGenerate and manage AI-written articles
billingView credit balance and billing history; write changes your own spending limits, card and subscription (cancel, auto top-up)
search-queriesImport and manage search query research
bulk-analysisRun bulk domain analysis
client-configView and update client settings, target pages and provider keys
collaborative-placementsView collaborative placement opportunities
citationView AI citation and ranking data
change-requestsReserved, no tool yet
opportunitiesView and manage link exchange opportunities and partner pages
account-campaignYour campaigns over HTTP (/api/account/campaigns); no MCP tool yet
llm-trackingTrack where AI assistants mention and cite your brand (AI Mentions)
asset-bankManage the pages and sites you offer in link exchanges
crmView CRM and communication data
creditsBuy prepaid credit (purchase only)
api-keysList your account's API keys; write revokes one (creating a key stays owner-only)
prospect-pipelineCreate, 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)
campaignWork inside a prospecting campaign: SERP searches, classification, campaign types, page checks, contacts, outreach and exports (pair it with prospect-pipeline:* to create the campaign)
agentsSee what your agents ask you and what they did; reply and answer as yourself
agent-reportsRead the reports made for your brand (keyword research)

3. Refusals

StatuscodeMeaningWhat to do
401No key, or a revoked or expired keyCreate a key
403SCOPE_DENIEDThe key lacks required_scopeCreate a key with that scope
403ACCOUNT_TYPE_DENIEDA managed key on a self-serve-only routeNothing: the route is not for managed accounts
429DAILY_READ_CAPThe key passed 5000 reads per key per UTC dayWait for resetsAt; Retry-After is set
429RATE_LIMIT_EXCEEDEDMCP only: 60 calls per minute with a burst of 20Wait Retry-After seconds
402one of six, belowThe account cannot fund this startRead the body: it names the way out
503TENANT_RESOLUTION_TIMEOUTLinkio 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, 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. 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:

AnswerMeaningWhat to do
401 Missing Authorization headerNo Authorization header, or Bearer with no key after itAdd the header with the key
403 Invalid API key, with a hint about a placeholderThe client sent the variable name (for example ${LINKIO_API_KEY}), not the keyExport the variable before you start the client, or write the key into the header
403 Invalid API key, Unrecognized credential formatThe value is not a Linkio keyCopy 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:

PolicyThe seller
Linkio default, linkio_defaultThe verified owner, unless a reseller is at least 15% cheaper and its latest paid order on the site proves that price
Owner only, owner_onlyVerified owners only; sites with no owner are left out of a search
Proven only, proven_onlyOnly sellers whose latest paid order on the site cost no more than their price today
Cheapest, cheapestThe 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.

This page as markdown: /docs/api.md. All pages for agents: /llms.txt.