API

POST /v1/query

Stellt eine Frage. Streaming-Support, Multi-LLM, Citations.

Stellt eine RAG-Anfrage. Synchron oder Streaming.

Request

httpPOST /v1/query
Authorization: Bearer ar_live_...
Content-Type: application/json

{
  "workspace": "ops",
  "query": "Wie ist die Wartung der Hydraulik geregelt?",
  "model": "claude-sonnet-4-6",
  "region": "eu-fra1",
  "max_tokens": 800,
  "stream": false,
  "filters": {
    "tags": ["wartung"],
    "doc_ids": ["doc_01HKQR..."]
  }
}

Parameter

Name	Typ	Pflicht	Default	Beschreibung
workspace	string	ja	—	Workspace-Slug oder -ID
query	string	ja	—	Die Frage in natürlicher Sprache
model	string	nein	claude-sonnet-4-6	Modell-ID (siehe Modell-Liste)
region	string	nein	workspace-region	LLM-Region
max_tokens	int	nein	800	Antwort-Maximum
stream	bool	nein	false	SSE-Streaming für Tokens
filters	object	nein	—	Pre-Filter für Vector-Search (Tags, Doc-IDs etc.)
top_k	int	nein	5	Anzahl Chunks für Kontext
temperature	float	nein	0.2	LLM-Temperatur

Response

json{
  "answer": "Wartung der Hydraulik erfolgt alle 500 Betriebsstunden gemäß Wartungsplan §3.2 ...",
  "citations": [
    {
      "doc_id": "doc_01HKQR...",
      "doc_name": "handbuch.pdf",
      "page": 42,
      "chunk_id": "chunk_01HKQR...",
      "score": 0.87
    }
  ],
  "trace_id": "tr_01HKQR...",
  "tokens": { "input": 1234, "output": 156 },
  "latency_ms": 642,
  "model_used": "claude-sonnet-4-6",
  "region_used": "eu-fra1"
}

Streaming

Mit "stream": true antwortet der Endpoint mit Server-Sent-Events:

textevent: token
data: {"text": "Wartung "}

event: token
data: {"text": "der "}

event: citations
data: {"citations": [...]}

event: done
data: {"trace_id": "tr_..."}

Statuscodes

→200 OK — Antwort generiert.
→400 Bad Request — Validation-Fehler.
→401 Unauthorized — API-Key fehlt oder ungültig.
→403 Forbidden — Keine Berechtigung für Workspace.
→429 Too Many Requests — Rate-Limit überschritten — siehe Rate-Limits.
→502 Bad Gateway — LLM-Provider-Outage. Auto-Failover auf nächstes Modell läuft, Retry empfohlen.