Linkio: a link building agency that plans before it builds

On self-serve you run the work: in the app, with your AI agent, or both. The app and the agent work on the same account and the same placements, so you can mix them at any step. For example, you pick the sites in the app, and your agent sends the articles and watches the activity feed. Or your agent finds the sites, and you approve them in the app.

You pay each publisher directly, at the price the site shows. Linkio charges a fee per job (a search past the free sites, an article, a check). Each step below has its own page.

For an agent that sets a person up: go to If your agent sets you up below. Do part A or part B, then part C. Then the person and you work through the same steps.

The steps

1. Start: account and brand

Make the account, put it on self-serve, and add your brand and the pages you want links to.

In the app: sign up at https://www.linkio.com/signup. Switch the mode in the menu under your name (Your Mode). Add the brand at https://www.linkio.com/clients/new.
With your agent: the agent signs you up without a browser (part A below). account_billing_mode reads and switches the mode. client_create adds the brand, and target_pages_add adds more pages.

Start: account, brand and money

2. Connect your agent (optional)

Skip this step if you work only in the app. You can connect an agent at any later step: it sees the same account, brands, orders and placements.

In the app: make a key at https://www.linkio.com/account/api-keys (the Automation level for an agent that orders, sends and records payments). Or add the Linkio connector in Claude.ai or ChatGPT and sign in.
With your agent: the agent connects to Linkio's MCP server with the key (part C below). An agent that signed you up has its key already.

Connect an agent

3. Money

Linkio's fees are paid from your own provider keys, money on the account or a card. The publisher is paid separately.

In the app: add your own provider keys at https://www.linkio.com/account/ai-keys, money at https://www.linkio.com/shop or a card at https://www.linkio.com/billing. Set spending limits at https://www.linkio.com/billing#limits.
With your agent: usage_receipt says whether paid work can start. usage_estimate gives a job's price before it runs, and usage_limits_get reads the limits. The person adds the keys, the money or the card, not the agent.

Who you pay, and for what

4. Find sites

Search the inventory. Read each site's numbers, its record with Linkio and who sells it (the owner or a reseller).

In the app: open https://www.linkio.com/websites, type a topic and use the filters (Max Cost, Seller policy).
With your agent: website_search searches by topic or domain. ai_find_sites_start runs the automated search.

Find sites

5. Order

Add the sites to an order with your target page and anchor text. An order only groups your placements; it is never paid as a whole.

In the app: on https://www.linkio.com/websites, tick the sites, select New Order, then Create & Review Order.
With your agent: order_create opens the order, and line_items_add_to_order adds the sites. line_items_update changes a placement later.

Order a placement

6. The article

Upload an article you wrote, or let Linkio's article system write it.

In the app: in the order, select Start Article on the row of the site.
With your agent: article_gen_readiness says whether a placement can start, and article_gen_start starts the article. ownContent: true on the placement marks an article you write yourself.

Buy a placement with your own article or Linkio's article system

7. Send

Check the article and send it to the publisher.

In the app: in the order, on the row of the site, select Send in the Publisher column, then Confirm & Send.
With your agent: workflow_verify_doc checks the Google Doc. workflow_send_to_publisher with checkOnly: true shows what the send would do; the agent sends after your yes.

Send the article and track the placement

8. Track

Read the publisher's replies and watch where each placement stands.

In the app: the activity feed is at https://www.linkio.com/account/activity. A reply shows as new on the order row, and all messages are under Messages.
With your agent: account_activity_feed lists what happened on the whole account; check it once an hour, not in a loop. line_item_conversation_read reads a thread, and line_item_message_publisher writes to the publisher.

Statuses and what you do now

9. Check the live link and pay the publisher

When the publisher sends the live URL, check it and pass or fail it. Then pay the publisher's invoice yourself and record the payment in Linkio.

In the app: on the Verification tab of the row, select QA PASS or QA FAIL (Notify Publisher). The invoices are at https://www.linkio.com/account/publisher-payments: pay with Pay Now, then select Mark as Paid.
With your agent: line_item_qa_decision records your pass or fail. account_publisher_invoices_list lists the invoices, and account_publisher_invoice_mark_paid records a payment after you say you paid. The agent moves no money.

Check the live link and pay the publisher

10. Fix problems

A silent or rejecting seller, or a price change: close, reopen or move the placement, or change the price.

In the app: message the seller under Messages. A placement that was rejected or went silent shows Replace Site among its actions.
With your agent: line_item_close, line_item_reopen, line_item_replace_site, line_item_switch_seller and line_item_agreed_price_set, each after your decision.

When a placement goes wrong

A refusal you do not understand: Troubleshooting: refusal codes. Words you do not know: Glossary.

Who you pay

You pay	For	How
The publisher (the seller of the site)	The guest post or the link insertion	Directly, by the payment method on the publisher's invoice. Linkio does not move this money.
Linkio	Each paid job: site searches past the free sites, articles, checks, and each write call of a key	From money you added or your card. With your own provider keys, the provider bills you for its part at cost.

The full price list is in Billing, limits and receipts.

If your agent sets you up

Copy the address of this page, https://www.linkio.com/docs/self-serve, into Claude Code, ChatGPT or another AI agent. Tell it: "Set me up on Linkio with this page." The agent does part A or part B below, then part C. It asks you for the code from Linkio's email, and for your yes before it switches the account or starts anything that costs money. After part C, you and the agent work through the same steps as above, on the same account.

For the agent: this page as plain text is https://www.linkio.com/docs/self-serve.md. Every docs page has a plain text copy at the same address with .md added. The list of all pages is https://www.linkio.com/llms.txt. No key and no login is needed to read them.

A. You do not have a Linkio account yet

Sign up. The agent sends your email address, a password (8 characters or more), your name and your website:

curl -s -X POST https://www.linkio.com/api/signup -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"<8+ characters>","name":"Your Name","website":"https://example.com"}'

The answer is 202 {"status":"verification_sent"}.

Ask the person for the code. Linkio sends the email "Verify Your Email Address - Linkio" to the person's mailbox. The agent cannot read that mail: it stops and asks the person for the code that follows the line "Did an AI agent create this account for you? Give it this verification code:". The code is good for 24 hours.
Get the key. The agent sends the code:
```
curl -s -X POST https://www.linkio.com/api/signup/verify -H 'content-type: application/json' \
  -d '{"token":"<the code>"}'
```
The answer is 201 with these fields:
- apiKey: the account's first key. It starts with acc_ and is shown only this once: keep it secret.
- keyPrefix: the first characters of the key. The keys page shows the key by this prefix.
- accountId: the account id.
- scopes: what the key may do. That is everything except the spending limits, the card and making keys (the Automation level).
- expiresAt: null. The key does not expire. The owner can revoke it on the keys page.
- next: the calls that come after. receipt reads where the account's money stands (the MCP tool usage_receipt gives the same), providerKeys adds your own OpenAI and DataForSEO keys (the tool provider_key_save), pricing lists the price of each paid job (no key needed), and addMoney is the page where the person adds money. receipt and providerKeys are HTTP paths on https://www.linkio.com: send the key in Authorization: Bearer <the key> or in X-API-Key.
Keep the key safe: hold it in an environment variable, or in a file only the person's user can read (chmod 600). Never print it, and never paste it into the chat or a log. Send it only in the Authorization header (or X-API-Key).

The account is on self-serve already. Refusals and limits: Sign up as an agent.
Go to part C.

B. You already made an account in the browser

Let the agent in. Use one of these:
- Make a key at https://www.linkio.com/account/api-keys. Select the Automation level. Give the key to the agent.
- In Claude.ai or ChatGPT, add the Linkio connector and sign in with your Linkio login. No key is needed. The steps: Connect an agent.
The agent connects as in part C, step 1.
The agent checks the account first.
- account_me (no input) returns account with email, contactName and companyName. The agent compares email and contactName with the person's. companyName counts only when it is set and differs; an empty companyName is normal. If something differs, the agent asks the person if this is the right account before it does anything more.
- A placeholder name on the right account: the person corrects it at https://www.linkio.com/account/settings, or, on the person's yes, the agent sends PUT https://www.linkio.com/api/account/profile with the key in X-API-Key and {"contactName": "...", "companyName": "..."}. Only the fields sent change. No MCP tool changes them.
- account_billing_mode (no input) returns mode, canSwitchToSelfServe and managedCustomer.
Self-serve. If mode is self_serve, go to part C, step 2.
Managed. If mode is managed: an account made in the browser starts on the managed plan. The agent does not switch it by itself.
- canSwitchToSelfServe is false (managedCustomer is true): the account has a managed plan with Linkio (a subscription, or an order paid in the last 60 days). The agent stops and tells the person to contact their account manager at Linkio. A switch attempt is refused with 403 managed_customer.
- canSwitchToSelfServe is true: the agent asks the person. The switch is one way: only Linkio's team moves an account back to the managed plan. On the person's yes, the agent calls account_billing_mode with {"mode": "self_serve"}. The person can also switch in the browser: the menu under their name, Your Mode, Self-Serve, then Switch. A key made before the switch works on self-serve after it. Details: Start: account, brand and money.

C. Connect and start (both)

Connect. The agent uses Linkio's MCP server, https://mcp.linkio.com/mcp, with the header Authorization: Bearer <the key>. Claude Code:
```
claude mcp add --transport http linkio https://mcp.linkio.com/mcp --header "Authorization: Bearer acc_your_key"
```
A new tool server shows in the next session. An agent that cannot add one now calls the same tools over HTTP, one JSON-RPC request per call:
```
curl -s https://mcp.linkio.com/mcp -H 'Authorization: Bearer acc_your_key' \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"account_me","arguments":{}}}'
```
The answer is an event stream. The result is the JSON on the data: line, and the tool's answer is the text in result.content[0].text. "method":"tools/list" lists every tool (a few hundred; the number depends on the key) with its inputSchema. For the first job read the inputSchema of these five: client_create, website_search, order_create, line_items_add_to_order and order_get. It gives the field names and which fields are required. Every tool: MCP tools. More ways to connect: Connect an agent.
Read the account. account_me gives the account id (account.id). After a signup by the agent, companyName is empty: the signup takes no business name. account_billing_mode must say self_serve (part B). usage_receipt says whether paid work can start (canStartPaidWork) and gives the month's spending limit (budgetCents, the most Linkio may bill this month) and what is left of it (budgetRemainingCents). A new account's limit is $50 (budgetCents: 5000). The person changes it at https://www.linkio.com/billing#limits.
Money. canStartPaidWork: false is normal for a new account. The free steps still work: add a brand, search sites (the first 100 sites a day are free), make an order and add sites to it. Paid steps stop with a 402 refusal until there is money: a search past the free sites, AI site finding, keyword and topic research, articles, and site checks and metrics. To start paid work, the person (not the agent) does one of these: adds their own OpenAI and DataForSEO keys at https://www.linkio.com/account/ai-keys (with both keys live, a new account also gets a free start), adds money at https://www.linkio.com/shop, or adds a card at https://www.linkio.com/billing. Each write call of a key also costs 1c. A daily job charges the writes of each finished UTC day, so usage_receipt shows them (in spentCents) only from the next day. Until then no field shows the amount to come. Details: Who you pay, and for what.
The first job.
- Add the brand: client_create with name (the business or brand name, not the person's name), website, targetPages (a list of the page URLs that get links, for example ["https://example.com/services"]) and description (what the business does and sells). It returns the brand id. The brand can show clientType: prospect; that is normal, leave it.
- Search sites: website_search with clientId (the brand id), topicQuery (the business topic, for example "home improvement") or domain, and limit. Always pass clientId: the search then leaves out sites the brand already has a link from or has on an order. Use a limit of 20 or less: the first 100 sites a day are free, and every search call counts the sites it returns, a repeated search too. Keep the answer instead of searching again. Each site shows its guest post price (guestPostCost, in dollars) and a seller object: label (owner, reseller or owner_unverified), policy (the seller policy that picked it), proven (its latest paid placement here cost no more than today's price) and ownerOfferAvailable (an offer from the owner exists). The seller has no name and no id. Search filters such as maxPrice are in dollars too. A site with guestPostCost: null or seller.label: null has no listed price or seller yet: skip it. history.attempts and history.lastAttemptAt count the earlier tries on the site, also the ones that did not go live; they are not failures. Failures are in history.failed.
- The agent checks the results before it shows them to the person. It drops the sites that are off the business topic, for example news, city or review sites in a search for a niche shop. If few sites fit, it searches again with a narrower topicQuery, for example "dog beds" instead of "pet supplies".
- Pick a site, in this order:
  1. The site's topic fits the business. Only sites that fit go on.
  2. Among those, an owner seller comes before a reseller.
  3. Then a proven seller and a high deliveredCount (placements that went live on the site) with few history.failed come before an unproven site.
  4. The guestPostCost is within the person's budget: the agent asks the person for the budget when it does not know it.
  If every site that fits is an unproven reseller, the agent shows the best 2 or 3 with that caveat and the person chooses.
- Make an order: order_create with the brand id (clientId). On self-serve an order is only the group your placements sit in; it is never paid as a whole. Do not pass billingType: the account's mode sets it, so the order is self-serve. It returns the order id.
- Add a site: line_items_add_to_order. orderId is at the top level, and each site is one entry in items:
```
{"orderId": "<order id>", "items": [{"clientId": "<brand id>", "assignedDomain": "example.org", "targetPageUrl": "https://example.com/services"}]}
```
  Prices on placements are in cents. Each placement's price is the seller's price, which you pay to that publisher directly. Leave out qualify: it starts a paid analysis of the site (keyword data and a grade) and is not needed to add a site.
  
  The answer gives each added placement's site as assignedDomain, and its estimatedPrice and wholesalePrice (in cents). On self-serve both are the seller's price (guestPostCost × 100). profitMargin is only in the order-level orderTotals, never on a placement, and it is 0 on self-serve.
- Read it back: order_get with orderId. Each placement is in lineItems[], with its site as domain (not assignedDomain) and its price at pricing.estimated, pricing.wholesale and pricing.serviceFee (in cents; on self-serve serviceFee is 0).
That makes an order with one placement on it. Nothing is sent to a publisher yet. You pay the publisher for the placement later, directly, on the publisher's invoice; Linkio charges only its metered fees. Anchor text is not needed yet. Set it before the article: article_gen_anchor_suggestions gives suggested texts, the person picks one, and article_gen_anchor_apply applies it by its suggestionId. The whole walk, with the article, the send and what to watch after: Your first guest post in five minutes. The rules the server gives every agent: The rules your agent gets.

Buy links yourself