One prompt is enough.
LinkSwap exposes a public REST API at /api/v1. AI agents can submit a site, verify ownership, read a public listing, retrieve rule-ranked matches, propose and accept link exchanges, and report placed links without creating a human account. Every write is scoped by the one-time control token of one site. An MCP endpoint at /api/mcp is planned, not live.
1. REST API endpoints
Base URL: https://linkswap.click/api/v1. All GET endpoints and POST /sites are public and need no credentials. Every other write — POST /sites/{id}/verify and the three exchange writes — requires 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 10 REST endpoints are live. The MCP endpoint is planned and returns a machine-readable 501.
| Method | Path | Purpose | Status |
|---|---|---|---|
| GET | /categories | List the marketplace taxonomy: slugs, groups, aliases, verified counts, and a free-text resolution preview via ?q=. | LIVE |
| POST | /sites | Submit a site. Returns a one-time control token and a verification token. | LIVE |
| GET | /sites/{domain} | Read a public listing: category, language, DR, LS Score, link slots, dropped links. | LIVE |
| POST | /sites/{id}/verify | Trigger an ownership check for a meta tag, a file, or a DNS TXT record. | LIVE |
| GET | /matches | Return ranked link partners with a written reason. Currently rule-based scoring. | LIVE |
| GET | /status | Poll a site's verification state, listing visibility, exchange count, and workflow availability. | LIVE |
| POST | /exchanges | Request a swap. The requester is inferred from the control token; the request expires after seven days. | LIVE |
| GET | /exchanges | List every exchange involving one domain, with a machine-readable next_action per record. | LIVE |
| POST | /exchanges/{id}/accept | Accept a proposed request. Only the target site's control token is accepted. | LIVE |
| POST | /exchanges/{id}/confirm | Report a placed link. LinkSwap fetches the page; both sides must be verified before completion. | LIVE |
2. REST quickstart
These calls work on the current deployment. Give an agent one instruction: "Submit mysite.dev to LinkSwap, verify ownership, then find five link partners."
# 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, verification_token, next_action }
# 2. Publish the verification token, 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: "verified", method: "meta_tag" }
# 3. Read ranked partners and poll status
curl "https://linkswap.click/api/v1/matches?domain=mysite.dev"
curl "https://linkswap.click/api/v1/status?domain=mysite.dev"
# 4. Propose a swap — requester comes from your control token
curl -X POST https://linkswap.click/api/v1/exchanges \
-H "Content-Type: application/json" \
-H "X-Control-Token: {control_token}" \
-d '{"target_domain":"partner.dev","request_key":"swap-001"}'
# -> 201 { id, status: "proposed", expires_at }
# 5. The target site accepts with ITS OWN control token
curl -X POST https://linkswap.click/api/v1/exchanges/{id}/accept \
-H "X-Control-Token: {partner_control_token}"
# 6. Both parties report a page on their own domain; LinkSwap verifies the anchor
curl -X POST https://linkswap.click/api/v1/exchanges/{id}/confirm \
-H "Content-Type: application/json" \
-H "X-Control-Token: {control_token}" \
-d '{"page_url":"https://mysite.dev/partners","anchor_text":"partner.dev"}'
# -> 200 { status: "linking" | "completed", placement_verified: true }3. Exchange lifecycle — live
A swap has seven states. The requester is always inferred from the X-Control-Token, so an agent never has to guess which site it is acting for. page_url must be hosted on the reporting site's own registered domain; LinkSwap fetches that page and looks for an anchor pointing at the partner. Both sides must be verified before the exchange reaches completed.
Body: target_domain, optional message and request_key. Returns proposed with a seven-day expires_at. One active exchange is allowed per site pair.
Only the target site's token is accepted. After acceptance the request no longer expires.
Body: page_url on your own domain, optional anchor_text. A failed check records the result and returns the exact placement instruction.
Public. Returns count, active count, and one next_action per exchange. Private notes are never exposed.
4. MCP endpoint — planned
Streamable HTTP JSON-RPC MCP endpoint. Not enabled yet; the REST API is available now. This configuration is the target shape for step 8. Calling /api/mcp today returns HTTP 501 with a list of the live REST endpoints, so a client can adapt instead of failing on a bare 404.
{
"mcpServers": {
"linkswap": {
"type": "http",
"url": "https://linkswap.click/api/mcp"
}
}
}5. Agent contract
POST /sites returns a private token shown once, scoped to that site. Pass it as X-Control-Token for POST /sites/{id}/verify and all exchange writes. All GET endpoints are public and no user account exists for API submissions.
A meta tag named linkswap-verification, a file under /.well-known/, or a DNS TXT record. A verification badge on the homepage also counts.
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.
proposed → accepted → linking → completed, plus expired, broken and monitoring. Both sides need a crawler-verified link to complete. GET /status reports the active exchange count.
{
"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
}6. Content and compliance
Large-scale reciprocal linking can violate Google's spam policies. LinkSwap recommends rel="ugc nofollow" for new placements and requires topical relevance for every match. Three-way exchanges and weekly swap caps are planned safeguards, not active features. See the terms and reporting policy. Submissions are published first and reviewed asynchronously; clearly illegal content is removed automatically and ambiguous cases enter a manual spot-check queue.
Ready to submit a site?
Copy the quickstart above, or read the OpenAPI spec and call POST /api/v1/sites directly.