One prompt is enough.
LinkSwap exposes a public REST API at /api/v1. AI agents can submit a site, verify a reciprocal link, read a public listing, browse the directory, poll status, read pricing and public stats, and create a checkout session without creating a human account. Every write is scoped by the one-time control token of one site. A live MCP Streamable HTTP server at /mcp exposes 12 tools for the same workflow; /api/mcp is the legacy alias.
1. REST API endpoints
Base URL: https://linkswap.click/api/v1, or connect the MCP server at /mcp. All GET endpoints are public and need no credentials. Write endpoints require the one-time per-site control token in the X-Control-Token header; store it when it is returned, because it is shown only once. All 14 documented REST endpoints and the MCP server are live.
| Method | Path | Purpose | Status |
|---|---|---|---|
| GET | /categories | List the directory taxonomy: slugs, groups, aliases, live counts, and a free-text resolution preview via ?q=. | LIVE |
| GET | /sites | Browse the public directory with category, language, plan, featured and free-text filters. | LIVE |
| POST | /sites | Submit a bare domain. Returns a one-time control token, badge_html, and machine-readable next steps. | LIVE |
| GET | /sites/{domain} | Read one public listing, including link_rel, badge_state and plan. | LIVE |
| GET | /badge | Public re-issue of badge_html and the alternative verification snippets for a submitted domain. No editing rights granted. | LIVE |
| POST | /sites/{id}/verify | Verify the reciprocal link. A match upgrades the directory link to followed. | LIVE |
| GET | /status | Poll a listing's status, link attribute, badge state, plan and latest check. | LIVE |
| GET | /stats | Public directory metrics computed from the live database. | LIVE |
| GET | /pricing | Machine-readable price list, rules and featured slot inventory. | LIVE |
| POST | /checkout | Create a hosted checkout session (Waffo Pancake, Stripe fallback) for a badge waiver or a featured slot. | LIVE |
| POST | /stripe/webhook | Apply paid entitlements after a signed Stripe event. Idempotent by session id. | LIVE |
| POST | /waffo/webhook | Waffo Pancake delivery endpoint. RSA-SHA256 signature verified on the raw body; idempotent by delivery id. | LIVE |
| POST | /badge/recheck | Batch reciprocal-link recheck for a scheduler, authenticated with CRON_SECRET. | LIVE |
| POST | /cancellations | Self-service cancellation: end a Featured placement or remove a listing. Requires the per-listing control token. | LIVE |
2. REST quickstart
These calls work on the current deployment. Give an agent one instruction: "Submit mysite.dev to LinkSwap, place the badge, and confirm the listing is active with a followed link."
# 1. Submit a site — no user account required
curl -X POST https://linkswap.click/api/v1/sites \
-H "Content-Type: application/json" \
-d '{"domain":"mysite.dev","request_key":"unique-key"}'
# -> 201 { site_id, control_token, badge_html, next_action }
# 2. Place the LinkSwap link or badge on your site, then verify
# (write endpoints need the control token)
curl -X POST https://linkswap.click/api/v1/sites/{site_id}/verify \
-H "X-Control-Token: {control_token}"
# -> 200 { status: "active", link_rel: "follow", badge_state: "verified" }
# 3. Read a listing, poll status, and read public stats
curl "https://linkswap.click/api/v1/sites/mysite.dev"
curl "https://linkswap.click/api/v1/status?domain=mysite.dev"
curl "https://linkswap.click/api/v1/stats"
# 4. Or skip the backlink with a one-time checkout session
curl -X POST https://linkswap.click/api/v1/checkout \
-H "Content-Type: application/json" \
-d '{"domain":"mysite.dev","kind":"badge_waiver"}'
# -> 200 { checkout_url, amount_cents: 499, currency: "usd" }
# Hand checkout_url to the human owner; never collect card details in chat.3. Badge verification & link attributes
A submitted site appears in the directory immediately with status: pending_link and a directory link carrying rel="ugc nofollow" (link_rel: nofollow). Place the badge_html reciprocal link on your own site; LinkSwap fetches your pages once an hour to verify it. Once found, the listing becomes active and the directory link is upgraded to followed (link_rel: follow). A missing link has a seven-day grace period, after which the listing returns to nofollow and is paused, and recovers automatically when the link is restored.
Add an anchor pointing at https://linkswap.click anywhere on your site. This is the simplest reciprocal link.
Wrap the LinkSwap badge image in the same anchor. The badge is optional but counts as the reciprocal link.
Publish a small text file under /.well-known/ containing your verification token. Read /badge for all three snippets.
GET /api/v1/status?domain= and GET /api/v1/sites/{domain} report status, link_rel, badge_state, plan, and featured_until for the listing.
rel="ugc nofollow"; a verified reciprocal link or a paid placement upgrades the directory link to followed.4. Checkout, pricing & stats
An agent that does not want to place a backlink can create a hosted checkout session with Waffo Pancake instead. A one-time $4.99 payment sets badge_state: waived: no reciprocal link is required and the listing becomes active with a followed link immediately. Featured homepage and category placements are sold at a fixed monthly price for limited slots and expire automatically at featured_until; bidding is planned and not enabled. A payment never skips content review and never guarantees a ranking.
Read the current price list: free listing, one-time badge waiver, and monthly featured placements.
Create a Waffo Pancake hosted checkout session for a badge waiver or a featured placement. Returns a checkout_url to complete payment.
Read public, machine-readable platform stats. No credentials are required for read endpoints.
Poll one listing for status, link_rel, badge_state, plan, and featured_until after verification or checkout.
5. MCP server — live
MCP Streamable HTTP endpoint. initialize / tools/list / tools/call call the same service layer as the REST API; no signup, writes need the per-listing control token. Point your MCP client at https://linkswap.click/mcp (protocol 2025-06-18); /api/mcp also works. The server is stateless: one JSON-RPC message per POST, no session id to keep alive, and a GET returns 405 because no server-initiated SSE stream is needed. Every tool calls the same service layer as the REST API.
{
"mcpServers": {
"linkswap": {
"type": "http",
"url": "https://linkswap.click/mcp"
}
}
}# initialize (POST /mcp, Accept: application/json, text/event-stream)
curl -X POST https://linkswap.click/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'
# list the tools
curl -X POST https://linkswap.click/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# submit a site through a tool
curl -X POST https://linkswap.click/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"submit_site","arguments":{"domain":"mysite.dev","category":"saas","request_key":"a-fresh-32-character-random-key"}}}'| Tool | What it does | Credential |
|---|---|---|
| get_guide | Workflow, live endpoints, rules and policy URLs. Call first if unsure. | none |
| list_categories | Taxonomy, aliases, live counts, and a free-text resolution preview. | none |
| submit_site | Submit a domain; returns site_id, one-time control_token and badge_html. | none |
| get_badge | Public re-issue of badge_html and the alternative verification snippets. | none |
| verify_site | Check the reciprocal link and upgrade the directory link to followed. | control_token |
| get_status | Full listing state, last badge check, latest order and next_action. | none |
| get_listing | Read one public directory entry. | none |
| list_sites | Browse the directory with category, text, plan and sort filters. | none |
| get_pricing | Prices, billing model, Featured inventory and policy URLs. | none |
| get_stats | Live verifiable directory metrics. | none |
| create_checkout | Create a hosted checkout session and return checkout_url for the owner. | none |
| cancel_placement | End a Featured placement or remove a listing; refunds are separate. | control_token |
submit_site returns a one-time control_token — keep it in your conversation state, because verify_site and cancel_placement require it and it cannot be recovered. get_badge is public and can re-issue the badge snippet later. create_checkout returns a URL for the human owner; never ask for card details in chat. Read the agent skill for the full workflow.6. Agent contract
POST /sites returns a private token shown once, scoped to that site. Pass it as X-Control-Token for write endpoints. All GET endpoints are public and no user account exists for API submissions.
Place the reciprocal link as a text link, an image badge, or a verification file under /.well-known/. LinkSwap rechecks it every hour.
Every write accepts an idempotency key. Retrying with the same key never creates a duplicate listing.
Every error response includes the exact next call or fix, plus a retryable flag, so an agent never needs a human to interpret it.
Five site submissions per day. Usage is counted against the X-API-Key when supplied, otherwise against the client IP address. An API key scopes the counter; it does not raise the limit.
pending_link → active on a verified backlink or a paid waiver; paused after the seven-day grace period; recovered automatically when the link returns. GET /status reports the current state.
{
"error": "missing_control_token",
"message": "This write endpoint requires the per-site control token.",
"next_action": "Retry with the header X-Control-Token: <control_token from POST /api/v1/sites>. The GET endpoints are public and need no credentials.",
"retryable": true
}7. Content review
Free listings start with rel="ugc nofollow" (status pending_link). After a verified reciprocal link, or after a paid placement with badge_state=waived, the directory link is upgraded to followed (link_rel=follow). A payment buys the link attribute and an optional featured placement; it does not buy content approval and does not guarantee any ranking. See the terms of service. Submissions are published first and reviewed asynchronously; clearly illegal content is removed automatically and ambiguous cases enter a manual spot-check queue. A payment does not skip this review.
8. Legal, billing and support
Every purchase is a one-time prepaid charge — no subscription, no free trial and no automatic renewal. Waffo Pancake is the merchant of record, PCI-DSS compliant payment processor and the hosted checkout. A Featured placement can be ended online at /manage or with POST /api/v1/cancellations. Your first paid purchase is fully refundable within 14 days.
Support: support@linkswap.click · Legal pages are linked from the footer of every page and open without a login.
Ready to submit a site?
Copy the quickstart above, or read the OpenAPI spec and call POST /api/v1/sites directly.