{
  "openapi": "3.1.0",
  "info": {
    "title": "LinkSwap API",
    "version": "2.0.0",
    "summary": "Bot-native website directory with a two-way link between a site owner and the platform",
    "description": "LinkSwap is a bot-native website directory. A listing is a two-way link between one site owner and the platform: the owner publishes a link or badge pointing at linkswap.click, and the directory links back to the owner's site. LIVE: discover the 14-category taxonomy, list and read public directory entries, submit a bare domain, place the returned badge, verify the backlink to earn a followed link, poll status, read public stats and pricing, trigger a backlink recheck, create a Stripe Checkout Session, receive Stripe webhooks, and cancel a Featured placement or remove a listing through the self-service cancellation endpoint. A free entry is listed immediately with a ugc nofollow rel attribute in pending_link state; a verified backlink or a paid plan upgrades the directory link to follow (link_rel=follow). Payment does not exempt content review. LIVE MCP: a stateless Streamable HTTP server at https://linkswap.click/mcp with 12 tools covering submit, badge, verify, status, pricing, checkout and cancellation; server card /.well-known/mcp/server-card.json. PLANNED (not enabled): Featured bidding auctions, x402/USDC payments, DeepSeek LLM reranking, and a public per-listing recheck history view. Rechecks already run hourly via a Cloudflare Cron Trigger. Every error response contains a next_action field so an agent can recover without human input. POST /sites/{id}/verify and POST /cancellations require the per-site control token; POST /badge/recheck requires CRON_SECRET; all GET endpoints are public. Every purchase is a one-time prepaid charge with no automatic renewal; Waffo Pancake is the merchant of record and Stripe is the hosted checkout. Terms /terms, privacy /privacy, refunds /refunds, contact /contact and online cancellation /manage are public and reachable without a login.",
    "termsOfService": "https://linkswap.click/terms",
    "contact": {
      "name": "LinkSwap support",
      "url": "https://linkswap.click/contact",
      "email": "support@linkswap.click"
    },
    "license": {
      "name": "See site terms",
      "url": "https://linkswap.click/terms"
    },
    "x-legal": {
      "privacy_policy": "https://linkswap.click/privacy",
      "refund_and_cancellation": "https://linkswap.click/refunds",
      "online_cancellation": "https://linkswap.click/manage",
      "pricing": "https://linkswap.click/pricing",
      "payment_processors": "Waffo Pancake (merchant of record) and Stripe (hosted Checkout)",
      "billing_model": "One-time prepaid charge per checkout; no subscription, no free trial, no automatic renewal."
    }
  },
  "servers": [
    {
      "url": "https://linkswap.click/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "categories",
      "description": "Discover the 14-category directory taxonomy and preview how free-text category input is resolved."
    },
    {
      "name": "sites",
      "description": "Submit, list, read, and verify directory listings."
    },
    {
      "name": "badge",
      "description": "Re-issue the reciprocal-link badge snippet and run backlink rechecks for the two-way link."
    },
    {
      "name": "status",
      "description": "Poll the state of one listing."
    },
    {
      "name": "stats",
      "description": "Public directory statistics."
    },
    {
      "name": "pricing",
      "description": "Machine-readable prices and Featured slot inventory."
    },
    {
      "name": "checkout",
      "description": "Hosted checkout (Waffo Pancake) for the paid no-backlink option and featured placements."
    },
    {
      "name": "webhook",
      "description": "Stripe webhook that writes paid entitlements."
    },
    {
      "name": "cancellation",
      "description": "Self-service cancellation of a Featured placement or removal of a listing."
    }
  ],
  "paths": {
    "/categories": {
      "get": {
        "tags": [
          "categories"
        ],
        "operationId": "listCategories",
        "summary": "List the directory taxonomy",
        "description": "Returns all 14 categories with slug, display name, group, alias, per-category listing count, and landing page URL. Add ?q=<free text> to preview how the category field of POST /sites would resolve the value: the response reports the matched slug, how it matched (slug, name, alias, keyword, explicit_other, or fallback), and suggestions on ambiguity. Public read endpoint.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Optional free-text category value to resolve, e.g. q=an ai newsletter.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The full category taxonomy and, when q is present, a resolution preview.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "x-status": "live"
      }
    },
    "/sites": {
      "get": {
        "tags": [
          "sites"
        ],
        "operationId": "listSites",
        "summary": "List the public directory",
        "description": "Public directory listing. Results are ordered by Featured slots, then paid weight, then backlink status, then content completeness, then submission time. No credentials required.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by category slug.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free-text search over title and description.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Filter by ISO 639-1 content language.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort key for the result set.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plan",
            "in": "query",
            "required": false,
            "description": "Filter by plan.",
            "schema": {
              "$ref": "#/components/schemas/Plan"
            }
          },
          {
            "name": "featured",
            "in": "query",
            "required": false,
            "description": "When true, return only entries currently occupying a Featured slot.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of entries to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public directory page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteList"
                }
              }
            }
          }
        },
        "x-status": "live"
      },
      "post": {
        "tags": [
          "sites"
        ],
        "operationId": "submitSite",
        "summary": "Submit a site for listing",
        "description": "Creates a live directory entry in pending_link state with a ugc nofollow rel attribute and returns a one-time private control token. Supplying a request_key makes retries idempotent. No account is required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SiteSubmission"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Site created in pending_link state; place the badge and verify to earn a followed link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/MachineReadableError"
          },
          "429": {
            "$ref": "#/components/responses/MachineReadableError"
          }
        },
        "x-status": "live"
      }
    },
    "/sites/{domain}": {
      "get": {
        "tags": [
          "sites"
        ],
        "operationId": "getSite",
        "summary": "Read a public site listing by domain",
        "description": "Returns the public detail for one listed domain, including category, content_language, link_rel, badge_state, plan, and featured_until.",
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Public listing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Site"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/MachineReadableError"
          }
        },
        "x-status": "live"
      }
    },
    "/sites/{id}/verify": {
      "post": {
        "tags": [
          "sites"
        ],
        "operationId": "verifySite",
        "summary": "Verify the backlink and domain ownership",
        "description": "LinkSwap fetches the submitted domain and looks for the verification token in a meta tag, a file under /.well-known/, a DNS TXT record, or the LinkSwap badge, and checks that a backlink to linkswap.click is present. On success link_rel is upgraded to follow and the listing becomes active. Requires the per-site control token in X-Control-Token; GET endpoints are public.",
        "security": [
          {
            "ControlToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "method": {
                    "$ref": "#/components/schemas/VerificationMethod"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Check finished. Inspect status, link_rel and next_action before proceeding.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/MachineReadableError"
          }
        },
        "x-status": "live"
      }
    },
    "/status": {
      "get": {
        "tags": [
          "status"
        ],
        "operationId": "getStatus",
        "summary": "Poll the state of one site",
        "description": "Public read of status, link_rel, badge_state, plan, featured_until, and next_action for one domain. No credentials required.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Current state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResult"
                }
              }
            }
          }
        },
        "x-status": "live"
      }
    },
    "/stats": {
      "get": {
        "tags": [
          "stats"
        ],
        "operationId": "getStats",
        "summary": "Read public directory statistics",
        "description": "Public aggregates: total listed sites, added today, backlink survival rate, and Featured slot inventory. No credentials required.",
        "responses": {
          "200": {
            "description": "Public counters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Stats"
                }
              }
            }
          }
        },
        "x-status": "live"
      }
    },
    "/pricing": {
      "get": {
        "tags": [
          "pricing"
        ],
        "operationId": "getPricing",
        "summary": "Read machine-readable pricing and Featured inventory",
        "description": "Public, machine-readable prices for the paid no-backlink option and Featured slots, plus current Featured slot inventory. No credentials required.",
        "responses": {
          "200": {
            "description": "Prices and Featured inventory.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pricing"
                }
              }
            }
          }
        },
        "x-status": "live"
      }
    },
    "/badge": {
      "get": {
        "tags": [
          "badge"
        ],
        "operationId": "getBadge",
        "summary": "Re-issue the reciprocal-link badge snippet for a submitted domain",
        "description": "Public endpoint. Returns badge_html, image_html, meta_tag, verification_file and site_id for an existing listing. The verification token is not secret: proving it appears on a website requires control of that website. Grants no editing rights; verification and cancellation still require the control_token.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Bare root domain of an existing listing.",
            "schema": { "type": "string", "example": "example.com" }
          }
        ],
        "responses": {
          "200": {
            "description": "Badge snippets and the site_id needed by POST /sites/{id}/verify.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domain": { "type": "string" },
                    "site_id": { "type": "string" },
                    "badge_html": { "type": "string" },
                    "image_html": { "type": "string" },
                    "meta_tag": { "type": "string" },
                    "note": { "type": "string" },
                    "public_endpoint": { "type": "boolean" },
                    "next_action": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing or invalid domain." },
          "404": { "description": "No listing exists for that domain." }
        },
        "x-status": "live"
      }
    },
    "/badge/recheck": {
      "post": {
        "tags": [
          "badge"
        ],
        "operationId": "recheckBadges",
        "summary": "Run one backlink recheck pass",
        "description": "Triggers one backlink recheck pass over listings. A missing backlink enters a 7-day grace period; after that the directory link reverts to nofollow and the listing is paused; a rediscovered backlink restores the followed state automatically. Protected by CRON_SECRET and called every hour by a Cloudflare Cron Trigger. Also reclaims expired featured slots.",
        "security": [
          {
            "CronSecret": []
          }
        ],
        "responses": {
          "200": {
            "description": "Recheck pass finished.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecheckResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/MachineReadableError"
          }
        },
        "x-status": "live"
      }
    },
    "/cancellations": {
      "post": {
        "tags": [
          "cancellation"
        ],
        "operationId": "cancelPlacement",
        "summary": "Cancel a Featured placement or remove a listing",
        "description": "Self-service cancellation required by the payment provider's review. Every purchase is a one-time prepaid charge with no automatic renewal, so there is no recurring charge to stop. action=end_placement releases the Featured slot immediately and keeps the ordinary listing; action=remove_listing hides the entry and reverts the link to nofollow. Requires the per-listing control token, either as the control_token body field or in the X-Control-Token header. Cancellation does not issue a refund; see https://linkswap.click/refunds. Browser equivalent: https://linkswap.click/manage.",
        "security": [
          {
            "ControlToken": []
          }
        ],
        "parameters": [
          {
            "name": "X-Control-Token",
            "in": "header",
            "required": false,
            "description": "Alternative to the control_token body field. Returned once by POST /sites.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain",
                  "control_token",
                  "action"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "example.com"
                  },
                  "control_token": {
                    "type": "string",
                    "description": "One-time token returned by POST /sites. May be omitted when X-Control-Token is sent instead."
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "end_placement",
                      "remove_listing"
                    ]
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 300
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancellation applied and confirmed on screen immediately.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "domain": {
                      "type": "string"
                    },
                    "action": {
                      "type": "string"
                    },
                    "canceled_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "had_featured_placement": {
                      "type": "boolean"
                    },
                    "listing_status": {
                      "type": "string"
                    },
                    "link_rel": {
                      "type": "string"
                    },
                    "recurring_charges": {
                      "type": "boolean",
                      "description": "Always false: no subscription exists."
                    },
                    "confirmation": {
                      "type": "string"
                    },
                    "next_action": {
                      "type": "string"
                    },
                    "policy_urls": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/MachineReadableError"
          },
          "401": {
            "$ref": "#/components/responses/MachineReadableError"
          },
          "404": {
            "$ref": "#/components/responses/MachineReadableError"
          }
        },
        "x-status": "live"
      }
    },
    "/checkout": {
      "post": {
        "tags": [
          "checkout"
        ],
        "operationId": "createCheckout",
        "summary": "Create a hosted checkout session",
        "description": "Creates a hosted checkout session with Waffo Pancake (the merchant of record), falling back to Stripe Checkout where only Stripe is configured. On a verified order.completed webhook the entry becomes badge_state=waived, active and link_rel=follow; payment does not exempt content review. When no provider is configured the endpoint returns HTTP 503 payments_not_configured and names the missing configuration.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain",
                  "kind"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "example.com"
                  },
                  "site_id": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": ["badge_waiver", "featured_home", "featured_category"]
                  },
                  "months": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 12,
                    "description": "Prepaid term for featured kinds. Ignored for badge_waiver."
                  },
                  "slot": {
                    "type": "integer"
                  },
                  "category_slug": {
                    "type": "string",
                    "description": "Required for featured_category when the listing has no category."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout Session created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutSession"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/MachineReadableError"
          },
          "503": {
            "$ref": "#/components/responses/MachineReadableError"
          }
        },
        "x-status": "live"
      }
    },
    "/stripe/webhook": {
      "post": {
        "tags": [
          "webhook"
        ],
        "operationId": "stripeWebhook",
        "summary": "Receive Stripe webhook events",
        "description": "Verifies the Stripe signature, then writes the paid entitlement: badge_state=waived, status active, and link_rel=follow. Called by Stripe, not by agents.",
        "parameters": [
          {
            "name": "Stripe-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event accepted and entitlement written.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "received": {
                      "type": "boolean"
                    },
                    "next_action": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/MachineReadableError"
          }
        },
        "x-status": "live"
      }
    },
    "/waffo/webhook": {
      "post": {
        "tags": [
          "webhook"
        ],
        "operationId": "waffoWebhook",
        "summary": "Receive Waffo Pancake webhook events",
        "description": "Verifies the x-waffo-signature header (RSA-SHA256 over the raw request body), records the delivery id for idempotency, then writes or revokes the entitlement. order.completed grants badge_state=waived, status active and link_rel=follow; refund.succeeded revokes it. Called by Waffo Pancake, not by agents.",
        "parameters": [
          {
            "name": "x-waffo-signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event verified and handled (or already applied).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "received": { "type": "boolean" },
                    "event_id": { "type": "string" },
                    "event_type": { "type": "string" },
                    "applied": { "type": "boolean" },
                    "reason": { "type": "string" }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The signature did not verify."
          },
          "500": {
            "description": "The event verified but could not be applied; the provider should retry."
          }
        },
        "x-status": "live"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ControlToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Control-Token",
        "description": "Private token returned once by POST /sites. Scoped to a single site. Required for POST /sites/{id}/verify and POST /cancellations (as the header or as the control_token body field). Not required by any GET endpoint or by POST /sites itself."
      },
      "CronSecret": {
        "type": "apiKey",
        "in": "header",
        "name": "X-CRON-SECRET",
        "description": "Shared secret required by POST /badge/recheck. Only the scheduled task that triggers rechecks should hold it."
      }
    },
    "responses": {
      "MachineReadableError": {
        "description": "Error with a machine-readable recovery hint.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "LinkRel": {
        "type": "string",
        "enum": [
          "nofollow",
          "follow"
        ],
        "description": "The rel attribute on LinkSwap's outbound link to the site. Free and pending entries carry a ugc nofollow rel attribute (nofollow); a verified backlink or a paid plan upgrades it to a followed link (follow)."
      },
      "BadgeState": {
        "type": "string",
        "enum": [
          "required",
          "verified",
          "waived",
          "missing"
        ],
        "description": "required: free entry awaiting a backlink; verified: backlink found and verified; waived: paid plan, no backlink needed; missing: previously verified backlink not found, within the 7-day grace period."
      },
      "Plan": {
        "type": "string",
        "enum": [
          "free",
          "paid",
          "featured"
        ],
        "description": "free: backlink required; paid: backlink waived via Stripe Checkout; featured: occupies a pinned slot at a fixed monthly price."
      },
      "SiteStatus": {
        "type": "string",
        "enum": [
          "pending_link",
          "active",
          "paused"
        ],
        "description": "pending_link: listed with a ugc nofollow link, awaiting a verified backlink; active: followed link; paused: backlink missing beyond the 7-day grace period, link reverted to nofollow."
      },
      "SiteSubmission": {
        "type": "object",
        "required": [
          "domain"
        ],
        "properties": {
          "domain": {
            "type": "string",
            "description": "Bare domain, lowercased, without protocol or www.",
            "example": "example.com"
          },
          "title": {
            "type": "string",
            "description": "Optional; fetched from the homepage when omitted."
          },
          "description": {
            "type": "string",
            "maxLength": 500
          },
          "category": {
            "type": "string",
            "description": "A category slug, a display name, or free text (for example saas, SaaS & Startups, or an ai newsletter). Values are resolved by exact match, alias match, then keyword containment. Unmatched text files the entry under other and the raw text is stored as a reviewable suggestion; the response reports exactly how the value matched via category_resolution. Preview any value first with GET /categories?q=.",
            "examples": [
              "saas",
              "SaaS & Startups",
              "an ai newsletter"
            ]
          },
          "content_language": {
            "type": "string",
            "description": "ISO 639-1 language code of the site content.",
            "example": "en"
          },
          "favicon_url": {
            "type": "string",
            "format": "uri",
            "description": "Optional https URL of the site icon, displayed on the listing. Leave it out: LinkSwap reads the icon (apple-touch-icon / rel=icon) off the submitted homepage on the first verification or recheck. When nothing is declared, the card falls back to the domain's /favicon.ico and then to a letter avatar."
          },
          "preview_image_url": {
            "type": "string",
            "format": "uri",
            "description": "Optional https URL of a homepage screenshot or OG image shown on the listing. Auto-discovered from og:image / twitter:image in the same pass."
          },
          "source": {
            "type": "string",
            "enum": [
              "dashboard",
              "human",
              "agent",
              "api"
            ],
            "description": "Optional label for the submission origin. Submissions through the browser form at /submit are labelled human; API submissions are classified as agent or api automatically."
          },
          "request_key": {
            "type": "string",
            "description": "Client-generated idempotency key. Reusing it never creates a duplicate entry."
          }
        }
      },
      "SiteCreated": {
        "type": "object",
        "properties": {
          "site_id": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/SiteStatus"
          },
          "control_token": {
            "type": "string",
            "description": "Shown once. Store it; it cannot be retrieved again."
          },
          "verification_token": {
            "type": "string"
          },
          "badge_html": {
            "type": "string",
            "description": "HTML snippet containing the verification token. Publish it on your own site as the backlink to linkswap.click."
          },
          "verification_instructions": {
            "type": "string",
            "description": "Agent- and human-readable steps to place the badge and verify the backlink."
          },
          "verification_methods": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "meta_tag",
              "file",
              "dns_txt",
              "badge"
            ]
          },
          "category": {
            "type": "string",
            "description": "The resolved category slug."
          },
          "category_resolution": {
            "type": "object",
            "description": "How the submitted category value was resolved: input, matched_by (slug | name | alias | keyword | explicit_other | fallback), slug, and suggestions when the input was ambiguous.",
            "additionalProperties": true
          },
          "link_rel": {
            "$ref": "#/components/schemas/LinkRel"
          },
          "badge_state": {
            "$ref": "#/components/schemas/BadgeState"
          },
          "next_action": {
            "type": "string",
            "example": "Place badge_html on your site, then POST /sites/{id}/verify"
          }
        }
      },
      "Site": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://linkswap.click/sites/example.com"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "content_language": {
            "type": "string"
          },
          "favicon_url": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "preview_image_url": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "link_rel": {
            "$ref": "#/components/schemas/LinkRel"
          },
          "badge_state": {
            "$ref": "#/components/schemas/BadgeState"
          },
          "plan": {
            "$ref": "#/components/schemas/Plan"
          },
          "featured_until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "status": {
            "$ref": "#/components/schemas/SiteStatus"
          }
        }
      },
      "SiteList": {
        "type": "object",
        "required": [
          "count",
          "results"
        ],
        "properties": {
          "count": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Site"
            }
          },
          "next_action": {
            "type": "string"
          }
        }
      },
      "VerificationMethod": {
        "type": "string",
        "enum": [
          "meta_tag",
          "file",
          "dns_txt",
          "badge"
        ],
        "description": "Publishable channels for the verification token. A LinkSwap badge on the homepage also satisfies ownership when it contains the token."
      },
      "VerificationResult": {
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/SiteStatus"
          },
          "method": {
            "$ref": "#/components/schemas/VerificationMethod"
          },
          "link_rel": {
            "$ref": "#/components/schemas/LinkRel"
          },
          "badge_state": {
            "$ref": "#/components/schemas/BadgeState"
          },
          "checked_url": {
            "type": "string",
            "format": "uri"
          },
          "next_action": {
            "type": "string"
          }
        }
      },
      "StatusResult": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/SiteStatus"
          },
          "link_rel": {
            "$ref": "#/components/schemas/LinkRel"
          },
          "badge_state": {
            "$ref": "#/components/schemas/BadgeState"
          },
          "plan": {
            "$ref": "#/components/schemas/Plan"
          },
          "featured_until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "next_action": {
            "type": "string"
          }
        }
      },
      "Stats": {
        "type": "object",
        "properties": {
          "total_sites": {
            "type": "integer",
            "description": "Total listings in the directory."
          },
          "added_today": {
            "type": "integer",
            "description": "Listings created today."
          },
          "backlink_survival_rate": {
            "type": "number",
            "description": "Fraction of verified backlinks still present, 0 to 1."
          },
          "featured_inventory": {
            "type": "integer",
            "description": "Remaining Featured slots."
          }
        }
      },
      "Pricing": {
        "type": "object",
        "description": "Machine-readable prices and Featured slot inventory. Concrete amounts are returned at runtime.",
        "properties": {
          "currency": {
            "type": "string",
            "example": "usd"
          },
          "free": {
            "type": "object",
            "description": "Free tier: backlink required, ugc nofollow link until verified.",
            "additionalProperties": true
          },
          "paid_plan": {
            "type": "object",
            "description": "Paid no-backlink option: price, billing interval, and description.",
            "additionalProperties": true
          },
          "featured": {
            "type": "object",
            "description": "Featured slots: fixed monthly price, total inventory, and available slots.",
            "additionalProperties": true
          },
          "next_action": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "RecheckResult": {
        "type": "object",
        "properties": {
          "checked": {
            "type": "integer",
            "description": "Number of listings checked in this pass."
          },
          "missing": {
            "type": "integer",
            "description": "Listings whose backlink was not found."
          },
          "grace": {
            "type": "integer",
            "description": "Listings within the 7-day grace period."
          },
          "reverted": {
            "type": "integer",
            "description": "Listings reverted to nofollow and paused."
          },
          "restored": {
            "type": "integer",
            "description": "Listings whose followed state was restored."
          },
          "next_action": {
            "type": "string"
          }
        }
      },
      "CheckoutSession": {
        "type": "object",
        "properties": {
          "checkout_url": {
            "type": "string",
            "format": "uri"
          },
          "session_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "example": "open"
          },
          "next_action": {
            "type": "string"
          }
        }
      },
      "LinkCheck": {
        "type": "object",
        "description": "Result of one backlink check performed during badge verification or POST /badge/recheck.",
        "properties": {
          "found": {
            "type": "boolean"
          },
          "anchor_text": {
            "type": "string",
            "nullable": true
          },
          "rel_value": {
            "type": "string",
            "nullable": true,
            "description": "rel value found on the owner's backlink, recorded as a factual signal."
          },
          "state": {
            "type": "string",
            "enum": [
              "active",
              "soft_drop",
              "removed",
              "redirect"
            ]
          },
          "checked_url": {
            "type": "string",
            "format": "uri"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "next_action"
        ],
        "properties": {
          "error": {
            "type": "string",
            "example": "missing_control_token"
          },
          "message": {
            "type": "string"
          },
          "next_action": {
            "type": "string",
            "description": "Exact instruction for the agent's next call or the exact fix to apply.",
            "example": "Place the badge_html snippet on your site, then POST /sites/{id}/verify"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      }
    }
  },
  "x-capability-status": {
    "live": [
      "GET /categories",
      "GET /sites",
      "POST /sites",
      "GET /sites/{domain}",
      "GET /badge",
      "POST /sites/{id}/verify",
      "GET /status",
      "GET /stats",
      "GET /pricing",
      "POST /badge/recheck",
      "POST /checkout",
      "POST /waffo/webhook",
      "POST /stripe/webhook",
      "POST /cancellations",
      "POST /mcp (12 MCP tools; legacy alias /api/mcp)"
    ],
    "planned": [
      "featured-bidding-auctions",
      "x402-usdc-payments",
      "deepseek-llm-reranking",
      "public-per-listing-recheck-history (badge_checks rows are recorded but not exposed as a page)"
    ],
    "note": "A capability is documented as live only when its route exists. Planned capabilities are not enabled and are explicitly marked as such."
  }
}
