# agents.txt — machine-readable Agent action list for LinkSwap # LinkSwap is a bot-native website directory. A listing is a two-way link between one site owner and the platform. # Canonical human guide: https://linkswap.click/for-agents # Full handbook: https://linkswap.click/agents.md # Structured capability list: https://linkswap.click/agents.json # LLM summary: https://linkswap.click/llms.txt # OpenAPI 3.1 spec: https://linkswap.click/openapi.json User-agent: * Allow: / Disallow: /dashboard/ Base-url: https://linkswap.click/api/v1 # Agent-facing documents Llms-txt: https://linkswap.click/llms.txt Agents-md: https://linkswap.click/agents.md Agents-json: https://linkswap.click/agents.json Openapi: https://linkswap.click/openapi.json Docs: https://linkswap.click/for-agents Badge-rules: https://linkswap.click/badge Pricing: https://linkswap.click/pricing Terms: https://linkswap.click/terms Privacy: https://linkswap.click/privacy Refunds: https://linkswap.click/refunds Contact: https://linkswap.click/contact Cancel-online: https://linkswap.click/manage Support-email: support@linkswap.click Mcp-server: https://linkswap.click/mcp Mcp-server-card: https://linkswap.click/.well-known/mcp/server-card.json Mcp-skill: https://linkswap.click/skills/submit-site/SKILL.md Sitemap: https://linkswap.click/sitemap.xml # Agent action list — run in this order # 1. Discover taxonomy Action: discover-taxonomy Method: GET Path: /api/v1/categories Required: none Optional: q (free text; previews category resolution) Returns: 14 categories with slugs, groups, aliases, counts, and a resolution preview Next: submit-site # 2. Submit a bare domain Action: submit-site Method: POST Path: /api/v1/sites Required: domain (bare domain, no protocol, no www) Optional: title, description, category (slug | display name | free text), content_language, favicon_url, preview_image_url, source, request_key Note: favicon_url and preview_image_url are auto-discovered from the site's homepage if omitted; they refresh on each backlink recheck Idempotency: request_key — reusing a key never creates a duplicate entry Returns: site_id, control_token (shown once), verification_token, badge_html, verification_instructions, category_resolution, link_rel, badge_state, next_action Auth: none Next: place-badge # 3. Place the backlink / badge Action: place-badge Method: PUBLISH (manual; not an API call) Path: https://linkswap.click/badge (code and rules) Required: badge_html from submit-site, published on a page of your own domain Returns: n/a (publish the returned HTML snippet) Next: verify # 4. Verify backlink / ownership Action: verify Method: POST Path: /api/v1/sites/{id}/verify Required: X-Control-Token header (one-time control_token), id = site_id from submit-site Optional: method (meta_tag | file | dns_txt | badge) Auth: control token (X-Control-Token) Returns: link_rel upgraded to follow, status active, next_action Next: poll-status # 5. Poll status Action: poll-status Method: GET Path: /api/v1/status?domain= Required: domain (query parameter) Returns: status, link_rel, badge_state, plan, featured_until, next_action Auth: none Next: follow next_action, or optional-checkout # 6. Optional paid path (skip the backlink) Action: optional-checkout Method: POST Path: /api/v1/checkout Required: domain (or site_id) Required: kind (badge_waiver | featured_home | featured_category); months 1-12 for featured kinds Returns: Waffo Pancake checkout URL (or HTTP 503 payments_not_configured when no provider is configured) Auth: none Note: the signed webhook at POST /api/v1/waffo/webhook writes the entitlement (badge_state=waived, active, followed) and is idempotent by delivery id; POST /api/v1/stripe/webhook is the fallback Next: poll-status # 7. Read public statistics Action: read-stats Method: GET Path: /api/v1/stats Required: none Returns: total listed, added today, backlink survival rate, Featured inventory Auth: none # 8. Self-service cancellation (end a Featured placement or remove the listing) Action: cancel Method: POST Path: /api/v1/cancellations Required: domain, control_token, action (end_placement | remove_listing) Optional: reason (free text, max 300 chars), X-Control-Token header instead of the body field Auth: control token scoped to this listing Returns: ok, confirmation, listing_status, next_action, policy_urls; no recurring charge is stopped because recurring billing does not exist Browser equivalent: https://linkswap.click/manage (no login) Refunds: separate request, see https://linkswap.click/refunds (first purchase refundable within 14 days) Next: none # Other live endpoints Endpoint: POST /mcp (MCP Streamable HTTP JSON-RPC: initialize, tools/list, tools/call; 12 tools; legacy alias /api/mcp) Endpoint: GET /api/v1/sites (public directory list; category / q / lang / sort / plan / featured / limit) Endpoint: GET /api/v1/badge?domain= (public re-issue of badge_html, image_html and meta_tag; grants no editing rights) Endpoint: GET /api/v1/sites/{domain} (public entry detail) Endpoint: GET /api/v1/pricing (prices and Featured slot inventory) Endpoint: POST /api/v1/badge/recheck (one recheck pass; requires CRON_SECRET; for scheduled tasks) Endpoint: POST /api/v1/cancellations (self-service cancellation; requires the per-listing control token) # Authentication Auth: none for all GET endpoints and for POST /api/v1/sites Auth: control-token (X-Control-Token) required for POST /api/v1/sites/{id}/verify Auth: control-token required for POST /api/v1/cancellations (body control_token or X-Control-Token header) Auth: control-token is returned once by POST /api/v1/sites, scoped to one site, cannot be recovered Auth: cron-secret (CRON_SECRET) required for POST /api/v1/badge/recheck Auth: x-waffo-signature (RSA-SHA256) verified on POST /api/v1/waffo/webhook; stripe-signature verified on POST /api/v1/stripe/webhook # Conventions Idempotency: request_key on POST /api/v1/sites Control-token: shown once — store it before leaving the submit response Header: X-Control-Token: on POST /api/v1/sites/{id}/verify Errors: every error response includes a machine-readable next_action field Next-action: follow the next_action string returned by each response as the exact next call Recheck: an hourly Cloudflare Cron Trigger calls POST /api/v1/badge/recheck; a missing backlink has a 7-day grace period before reverting to nofollow and paused Plan: payment waives the backlink (badge_state=waived) but does not exempt content review Directory: one entry per root domain Ranking: Featured slots > paid weight > backlink status > content completeness > time # Planned (not enabled) Planned: Featured slot bidding auctions Planned: x402 / USDC payments Planned: DeepSeek LLM reranking Planned: a public per-listing recheck history view (badge_checks are recorded but not exposed as a page)