Context Window
Query a knowledge space
Endpoint
https://claix.dev/space-context/{space_id}Persisted documents can be grouped into knowledge spaces. This endpoint answers questions using every document in a space at once instead of a single one, so you can compare, add up, or reconcile data spread over several files.
It is the sibling of POST /document-context/{document_id}: the input and output are exactly the same. The only differences are the scope of the answer and that the URL carries a space_id instead of a document_id.
Public URL: POST https://claix.dev/space-context/{space_id}. Never expose the raw Supabase URL.
Designed for server-to-server integrations. Requires a secret API key.
1. Authentication
Every request must include your API key.
Option A — Dedicated header (recommended):
x-api-key: <YOUR_API_KEY>
Option B — Standard Authorization header:
Authorization: Bearer <YOUR_API_KEY>
The system checks that the key exists and is active, and that the account is not suspended. Failures return 401.
2. How documents get grouped
Before you can query a space, documents have to be inside it. That is why the five extraction endpoints (/api/excel-json, /api/pdf-json, /api/doc-json, /api/img-json, /api/txt-json) and the five Agent mode endpoints (/agent/*-json) accept an optional space_id field.
- The space must belong to the same account that owns the API key. If it does not exist or belongs to another account, the extraction returns 404.
- It only takes effect when the schema has the context window enabled, which is when the document is stored. Without it there is nothing to group.
- Reuse the same
space_idacross as many extractions as you want: every document joins that space.
See the right-hand panel, Group on extraction tab, for the full flow: extract with space_id, then query the space.
3. Request format
HTTP method: POST · Content-Type: application/json
space_id (UUID) is part of the path. The body is identical to document-context and has a single field:
| Field | Type | Required | Description |
|---|---|---|---|
| questions | array of strings | Yes | Questions to answer using only the content of the documents in the space. Max 5 per turn. Max 400 characters per question. |
{
"questions": [
"Which supplier bills the most across all invoices?",
"Is there any contract whose amount does not match its invoice?"
]
}- At least 1 question; at most 5.
- Each string must have content (not whitespace only).
- The space must belong to the API key account and hold at least one live document.
4. Context limits
A space can grow indefinitely, so the call caps how much information reaches the AI. This keeps cost under control and prevents accuracy from degrading once there is too much text in play.
| Limit | Value | What happens past it |
|---|---|---|
| Documents per query | 50 | The 50 most recent documents in the space are used. |
| Total context characters | 200,000 | The budget is shared across the selected documents, so none is dropped entirely. |
| Questions per call | 5 | Returns 400. Split the questions across several calls. |
- Expired documents are excluded: once a document expires it stops counting toward the space.
- When a document is trimmed to fit the budget, the AI knows it and will not make claims about the part it did not see.
- If the space exists but holds no live document with content, the call returns 400.
5. Step-by-step request
- Create a knowledge space in the dashboard and copy its
space_id. - Extract your documents with the context window enabled, passing that
space_idon every call. - Obtain your API key.
- POST to
https://claix.dev/space-context/{space_id}. - Send
{ "questions": ["..."] }as JSON. - Check HTTP 200 and read
ia_response.
6. Request examples
See the right-hand panel for cURL, JavaScript, Node.js, Python, PHP, and n8n examples.
7. Successful response
Status: 200 OK · Content-Type: application/json
The shape is identical to document-context, so you can switch between the two calls without touching the code that reads the response.
{
"user_ask": [
"¿Qué proveedor factura más en total sumando todas las facturas?",
"¿Hay algún contrato cuyo importe no coincida con su factura?"
],
"ia_response": [
"Suministros Omega S.A., 48.320 € entre tres facturas (febrero, marzo y abril).",
"Sí: contrato-omega.pdf fija 12.000 € y factura-omega-03.pdf cobra 13.450 €."
]
}| Field | Type | Description |
|---|---|---|
| user_ask | array of strings | The questions you sent, in the same order. |
| ia_response | array of string or null | Answers aligned 1:1 with user_ask. If the fact is in none of the documents in the space, the value is JSON null — not a sentence. When an answer comes from cross-referencing several documents, it briefly cites which files it came from. |
8. Error codes
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos)."
}400 — Invalid space_id, malformed JSON, missing questions, empty array, more than 5 items, a question longer than 400 characters, or a space with no live documents holding content.
401 — Missing, invalid, or inactive API key, or suspended account.
404 — The space does not exist or does not belong to the account.
502 — AI service failure. 405 — Method other than POST. 500 — Unexpected server error.
9. Error code summary
| Code | Category | Retry? |
|---|---|---|
| 200 | Success | — |
| 400 | Client error (malformed document or data) | No — fix the request first |
| 401 | Authentication error | No — fix credentials first |
| 404 | Resource not found | No — fix schema_id first |
| 405 | Incorrect HTTP method | No — fix the method first |
| 413 | File or extracted text too large | No — reduce size first |
| 422 | No extractable data | No — review document/schema first |
| 500 | Internal server error | Yes, with caution |
| 502 | AI service failure | Yes, recommended with backoff |