# agents.txt — machine-readable access and capability notes for automated clients
# Canonical human-readable version: https://linkswap.click/for-agents
# Full site summary for language models: https://linkswap.click/llms.txt

User-agent: *
Allow: /
Disallow: /api/
Disallow: /dashboard/

# Agent-facing entry points
Llms-txt: https://linkswap.click/llms.txt
Openapi: https://linkswap.click/openapi.json
Rest-api: https://linkswap.click/api/v1
Docs: https://linkswap.click/for-agents
Sitemap: https://linkswap.click/sitemap.xml
Mcp: https://linkswap.click/api/mcp (planned, step 8; returns 501 today)

# Capabilities — LIVE
Capability: list-categories (GET /categories; full taxonomy with aliases and counts; ?q= previews free-text category resolution)
Capability: submit-site (POST /sites; category field accepts slug, display name, or free text; optional favicon_url / preview_image_url; humans use the identical form at https://linkswap.click/submit)
Capability: verify-domain-ownership (POST /sites/{id}/verify)
Capability: read-public-listing (GET /sites/{domain})
Capability: query-ranked-matches (GET /matches; deterministic rule scoring, no LLM)
Capability: read-site-status (GET /status)
Capability: request-swap (POST /exchanges; requester inferred from token, 7-day expiry)
Capability: list-exchanges (GET /exchanges?domain=; public read)
Capability: accept-swap (POST /exchanges/{id}/accept; target site token only)
Capability: confirm-link-placement (POST /exchanges/{id}/confirm; fetches the page and verifies the anchor)

# Capabilities — PLANNED (HTTP 501 with next_action)
Capability: mcp-tools (POST /api/mcp, step 8)
Capability: daily-link-monitoring (step 7; placement checks currently run only on confirm)
Capability: llm-reranking (step 5)

# Authentication
Auth: none for all GET endpoints and for POST /api/v1/sites
Auth: control-token (X-Control-Token header) required for POST /api/v1/sites/{id}/verify and all exchange writes
Auth: control-token is returned once by POST /api/v1/sites, scoped to one site, and cannot be recovered
Auth: api-key (X-API-Key header, optional; scopes the daily quota to that key instead of the client IP, and does not raise the limit)

# Limits and behavior
Limit: 5 site submissions per key per day
Idempotency: request_key on POST /sites and POST /exchanges
Errors: all error responses include a next_action field
Exchange-states: proposed | accepted | linking | completed | monitoring | broken | expired
Exchange-completion: both parties must report a page on their own domain containing a verified anchor to the partner
Exchange-expiry: 7 days without acceptance; one active exchange per site pair
Content: publish-then-review; clearly illegal content is removed automatically
Compliance: rel="ugc nofollow" recommended for new placements; three-way exchanges and weekly swap caps planned
Notifications: no email is sent; poll GET /exchanges and GET /status for next_action
Dataset: listings in this deployment are seeded sample records, labelled on each page