{
  "service": "Bluedoor Answers API",
  "version": "0.2.0",
  "description": "Ask a question in natural language, get back a synthesized text answer with citations to the public web pages it is based on.",
  "authentication": {
    "type": "bearer",
    "header": "Authorization: Bearer <api_key>",
    "alternative": "X-API-Key: <api_key>"
  },
  "rate_limit": "1 request per second, with a small burst allowance",
  "endpoints": {
    "POST /v1/answer": {
      "description": "Answer one question with citations.",
      "request": {
        "query": "string, 1-2000 characters"
      },
      "response": {
        "id": "string",
        "object": "\"answer\"",
        "model": "string",
        "created": "number, unix seconds",
        "query": "string",
        "answer": "string, markdown, citation markers like [1] refer to citations[].ref",
        "citations": [
          {
            "ref": "number",
            "title": "string",
            "url": "string",
            "publisher": "string",
            "snippet": "string"
          }
        ],
        "usage": {
          "citations": "number",
          "latency_ms": "number"
        }
      }
    },
    "GET /v1/health": {
      "description": "Liveness check."
    },
    "GET /openapi.json": {
      "description": "OpenAPI 3.1 description of this API."
    },
    "GET /llms.txt": {
      "description": "Plain-text description for agents."
    }
  },
  "example": {
    "curl": "curl -s https://ask.bluedoor.sh/v1/answer -H \"Authorization: Bearer $BLUEDOOR_API_KEY\" -H \"Content-Type: application/json\" -d '{\"query\":\"Who is the city manager of Sarasota, Florida?\"}'"
  },
  "notes": [
    "Typical latency is 2-8 seconds; allow a 60 second client timeout.",
    "Answers are synthesized from public web sources and should be verified against the cited URLs before use as fact.",
    "Each call is an independent sample. Asking the same question twice may return differently worded answers."
  ]
}