# STELQ Answers API

Grounded answers with citations, tuned for the agent loop. Ask a question, get a synthesized answer plus the sources it stands on. Synchronous: one request, one response.

- **Endpoint:** `POST https://api.stelq.com/v1/answers/ask`
- **Auth:** `Authorization: Bearer $STELQ_KEY`
- **Price:** $0.002 / answer
- **Mode:** synchronous
- **Canonical URL:** https://stelq.com/api/docs/answers (public, no auth, always current)

## Authentication

Every request needs a bearer token: `Authorization: Bearer $STELQ_KEY`. Create and scope keys in the console under API Keys — the secret is shown once. In the in-console Playground the key is injected for you; copied payloads reference the `$STELQ_KEY` environment variable, so set it in your agent's environment instead of pasting a live secret into a prompt.

## Request

`POST /v1/answers/ask`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | The question to answer. |
| `maxTokens` | integer | no | Cap the answer length (default 512). |
| `citations` | boolean | no | Return the sources behind the answer (default true). |

```json
{
  "query": "RAG vs fine-tuning for enterprise?",
  "maxTokens": 512,
  "citations": true
}
```

## Response

```json
{
  "answer": "Use RAG when the knowledge changes often or must be cited; fine-tune when you need…",
  "citations": [
    {
      "url": "https://example.com/rag-vs-ft",
      "title": "RAG vs fine-tuning, compared"
    }
  ]
}
```

## Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request — a field is missing or malformed (the body says which). |
| 401 | Missing or invalid API key. |
| 402 | Insufficient balance — top up credits to continue. |
| 429 | Rate limited — back off and retry after the Retry-After header. |
| 502 | Upstream temporarily unavailable — safe to retry; not charged. |

## Rate limits

Up to 50 requests/second per key.