{
  "openapi": "3.1.0",
  "info": {
    "title": "EarnCitations API",
    "version": "0.1.0",
    "description": "Free checks of how AI crawlers and assistants read a site. No key: requests are rate-limited per IP address. Fields are documented at https://earncitations.com/developers.html#api and errors at https://earncitations.com/developers.html#errors. Private, loopback and link-local addresses are refused."
  },
  "servers": [
    {
      "url": "https://earncitations.com"
    },
    {
      "url": "http://127.0.0.1:4317",
      "description": "Your own copy (earncitations serve)"
    }
  ],
  "externalDocs": {
    "url": "https://earncitations.com/developers.html"
  },
  "paths": {
    "/api/audit": {
      "get": {
        "operationId": "audit",
        "summary": "AI-readiness audit of a site",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "A domain or URL, e.g. example.com",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          },
          {
            "name": "fresh",
            "in": "query",
            "description": "1 to skip the cached report (results are cached briefly)",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The audit report.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "score": {
                      "type": "number"
                    },
                    "grade": {
                      "type": "string"
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "checks": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The input is missing or invalid. Fix the request; retrying it unchanged fails again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The site resolves to an address we don't fetch (private, loopback or link-local). Not retryable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from your address for this endpoint. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The check failed on our side. Retrying once is safe; if it fails again, the site may be sending something unusual.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Either we are busy with other checks, or the site you asked about rate-limited our crawler. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "The check ran out of time, usually because the site is slow. Retrying is safe.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/fix": {
      "get": {
        "operationId": "fixKit",
        "summary": "Fix kit: files to add and manual steps",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "A domain or URL",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          },
          {
            "name": "fresh",
            "in": "query",
            "description": "1 to skip the cached report (results are cached briefly)",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The fix kit.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "score": {
                      "type": "number"
                    },
                    "grade": {
                      "type": "string"
                    },
                    "files": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "manual": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The input is missing or invalid. Fix the request; retrying it unchanged fails again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The site resolves to an address we don't fetch (private, loopback or link-local). Not retryable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from your address for this endpoint. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The check failed on our side. Retrying once is safe; if it fails again, the site may be sending something unusual.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Either we are busy with other checks, or the site you asked about rate-limited our crawler. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "The check ran out of time, usually because the site is slow. Retrying is safe.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/badge": {
      "get": {
        "operationId": "badge",
        "summary": "SVG badge with the live score",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "A domain or URL",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          },
          {
            "name": "fresh",
            "in": "query",
            "description": "1 to skip the cached report (results are cached briefly)",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A 20px-high badge. Errors render as n/a, never as an error response, because badges sit in other sites' pages.",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/card": {
      "get": {
        "operationId": "card",
        "summary": "1200×630 SVG score card",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "A domain or URL",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          },
          {
            "name": "fresh",
            "in": "query",
            "description": "1 to skip the cached report (results are cached briefly)",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "theme",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "light",
                "dark"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The score card.",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "The input is missing or invalid. Fix the request; retrying it unchanged fails again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The site resolves to an address we don't fetch (private, loopback or link-local). Not retryable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from your address for this endpoint. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The check failed on our side. Retrying once is safe; if it fails again, the site may be sending something unusual.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Either we are busy with other checks, or the site you asked about rate-limited our crawler. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "The check ran out of time, usually because the site is slow. Retrying is safe.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/presence": {
      "get": {
        "operationId": "presence",
        "summary": "Training-data presence (prototype): Common Crawl, Wikidata, Wikipedia",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "A domain",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          },
          {
            "name": "only",
            "in": "query",
            "description": "wikidata to skip Common Crawl",
            "schema": {
              "type": "string",
              "enum": [
                "wikidata"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Presence per source; a source that is down is {\"available\": false}, never \"absent\".",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "description": "The input is missing or invalid. Fix the request; retrying it unchanged fails again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from your address for this endpoint. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The check failed on our side. Retrying once is safe; if it fails again, the site may be sending something unusual.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/diagnose": {
      "get": {
        "operationId": "diagnose",
        "summary": "Question doctor: why a site is or isn't the answer to one question",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "A domain",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The question (300 characters at most). `question` is accepted too.",
            "schema": {
              "type": "string",
              "maxLength": 300
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "software",
                "local"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The diagnosis.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verdict": {
                      "type": "string",
                      "enum": [
                        "crawl",
                        "missing",
                        "weak",
                        "answers"
                      ]
                    },
                    "page": {
                      "type": "object"
                    },
                    "answer": {
                      "type": "object"
                    },
                    "findings": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "nextStep": {
                      "type": "string"
                    },
                    "draft": {
                      "type": "object"
                    },
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "candidates": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The input is missing or invalid. Fix the request; retrying it unchanged fails again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from your address for this endpoint. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The check failed on our side. Retrying once is safe; if it fails again, the site may be sending something unusual.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Either we are busy with other checks, or the site you asked about rate-limited our crawler. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/map": {
      "get": {
        "operationId": "map",
        "summary": "Question map: the questions a site's own pages suggest, each diagnosed",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "A domain",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Your own question; repeat up to 12 times.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 300
              },
              "maxItems": 12
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "software",
                "local"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The map.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "site": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string"
                    },
                    "questions": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "tally": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The input is missing or invalid. Fix the request; retrying it unchanged fails again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from your address for this endpoint. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The check failed on our side. Retrying once is safe; if it fails again, the site may be sending something unusual.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Either we are busy with other checks, or the site you asked about rate-limited our crawler. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/view": {
      "get": {
        "operationId": "view",
        "summary": "One page as an AI crawler that doesn't run JavaScript reads it",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "A page URL",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          }
        ],
        "responses": {
          "200": {
            "description": "What the crawler gets.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "finalUrl": {
                      "type": "string"
                    },
                    "status": {
                      "type": "number"
                    },
                    "words": {
                      "type": "number"
                    },
                    "problems": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "facts": {
                      "type": "object"
                    },
                    "widgets": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "agents": {
                      "type": "object"
                    },
                    "aiText": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "lines": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "outline": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "markdownCopy": {
                      "type": "object"
                    },
                    "dates": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The input is missing or invalid. Fix the request; retrying it unchanged fails again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from your address for this endpoint. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The check failed on our side. Retrying once is safe; if it fails again, the site may be sending something unusual.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Either we are busy with other checks, or the site you asked about rate-limited our crawler. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/delivery": {
      "get": {
        "operationId": "delivery",
        "summary": "Delivery check: did a page change reach AI crawlers?",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "The page URL",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          },
          {
            "name": "expect",
            "in": "query",
            "description": "A sentence from the change; repeat up to five times (300 characters each).",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 300
              },
              "maxItems": 5
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "since",
            "in": "query",
            "description": "YYYY-MM-DD: the date the change shipped.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The verdict and each step.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "checkedAt": {
                      "type": "string"
                    },
                    "expect": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "since": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "finalUrl": {
                      "type": "string"
                    },
                    "status": {
                      "type": "number"
                    },
                    "verdict": {
                      "type": "string",
                      "enum": [
                        "delivered",
                        "delivered-with-gaps",
                        "blocked"
                      ]
                    },
                    "steps": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "agents": {
                      "type": "object"
                    },
                    "facts": {
                      "type": "object",
                      "description": "What each step found: canonical, inSitemap, lastmod, linkedFromHome, inLlms, llmsFile (which llms.txt listed the page, or the nearest one read), markdownCopy ({ path, stale } for a Markdown copy the page advertises), and more."
                    },
                    "next": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "What to do next, most important first."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The input is missing or invalid. Fix the request; retrying it unchanged fails again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from your address for this endpoint. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The check failed on our side. Retrying once is safe; if it fails again, the site may be sending something unusual.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Either we are busy with other checks, or the site you asked about rate-limited our crawler. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "The check ran out of time, usually because the site is slow. Retrying is safe.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/docs": {
      "get": {
        "operationId": "docs",
        "summary": "Docs check: could a coding agent set the product up from its public docs?",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "The site or docs URL",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Each step, scored and unscored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "site": {
                      "type": "string"
                    },
                    "docs": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "steps": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "passed": {
                      "type": "number"
                    },
                    "of": {
                      "type": "number"
                    },
                    "nextStep": {
                      "type": "string"
                    },
                    "pagesRead": {
                      "type": "number"
                    },
                    "checkedAt": {
                      "type": "string"
                    },
                    "partial": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The input is missing or invalid. Fix the request; retrying it unchanged fails again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from your address for this endpoint. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The check failed on our side. Retrying once is safe; if it fails again, the site may be sending something unusual.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Either we are busy with other checks, or the site you asked about rate-limited our crawler. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "The check ran out of time, usually because the site is slow. Retrying is safe.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/claims": {
      "post": {
        "operationId": "claims",
        "summary": "Answer check: each claim in an AI answer against the pages it cites",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "answer"
                ],
                "properties": {
                  "answer": {
                    "type": "string",
                    "maxLength": 20000
                  },
                  "urls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 2048
                    },
                    "maxItems": 8
                  },
                  "brand": {
                    "type": "string",
                    "maxLength": 80
                  },
                  "domain": {
                    "type": "string",
                    "maxLength": 253
                  },
                  "competitors": {
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "maxLength": 340
                        },
                        "maxItems": 10
                      },
                      {
                        "type": "string",
                        "maxLength": 2000
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Each claim with a verdict.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tally": {
                      "type": "object"
                    },
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "claims": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "next": {
                      "type": "string"
                    },
                    "entity": {
                      "type": "object"
                    },
                    "competitors": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The input is missing or invalid. Fix the request; retrying it unchanged fails again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "The body is over 40 KB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Send Content-Type: application/json.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from your address for this endpoint. Wait for Retry-After, then retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The check failed on our side. Retrying once is safe; if it fails again, the site may be sending something unusual.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/ipranges": {
      "get": {
        "operationId": "ipranges",
        "summary": "AI operators' published IP range files, cached for a day",
        "parameters": [],
        "responses": {
          "200": {
            "description": "The files.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "fetchedAt": {
                      "type": "string"
                    },
                    "sources": {
                      "type": "object"
                    },
                    "files": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Wrong HTTP method; the Allow header says which one to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "One or more operators' IP range files could not be loaded. Retry in about ten minutes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "health",
        "summary": "Liveness",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Always {\"ok\": true}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in a sentence."
          },
          "detail": {
            "type": "string"
          }
        }
      }
    }
  }
}
