# IntentSite — Public Agent API

IntentSite exposes a public endpoint so external AI agents can ask questions
about IntentSite and get curated answers.

## Endpoint

POST https://api.intentsite.com/api/v1/ask

Content-Type: application/json

## Discovery (no arguments)

GET https://api.intentsite.com/api/v1/ask

Returns the IntentMap: the list of questions this assistant can answer, each
tagged with its category (cluster) and language. Use it to discover what to ask.

  {
    "version": "...",
    "count": 42,
    "intents": [
      { "question": "...", "category": "...", "language": "English" }
    ]
  }

## Headers (optional)

  X-Agent-Identity: <short slug, e.g. "openai-gpt-5", "anthropic-claude">
  X-End-User-Id:    <opaque per-end-user id if the agent acts on behalf of a human>

## Request body

  { "question": "<max 100 chars>", "thread_id": "<from previous response, optional>" }

## Modes

  - Single-shot (default):   POST /api/v1/ask
  - Streaming (SSE):         POST /api/v1/ask?stream=true

## Response (single-shot)

  {
    "answer": "...",
    "language": "English",
    "thread_id": "<pass back to continue the conversation>",
    "turn_id": "..."
  }

## Rate limits

  - Per caller IP: 10 req/min, 200 req/day
  - Per thread:    30 turns/hour
  - Global daily $-cost killswitch

## Documentation

  Interactive (Swagger): https://api.intentsite.com/docs
  OpenAPI spec:          https://api.intentsite.com/openapi.json

## Version

  v1.0.0