Query (RAG)

Der zentrale Endpoint von Anirag — RAG-Query mit Citations, Multi-LLM-Routing und optional Streaming.

POST/v1/query

RAG-Query gegen eine Collection. Liefert Antwort mit Citations und vollständigem Trace.

Request-Body

Parameter	Typ	Required	Beschreibung
`collection_id`	string	REQ	Collection-ID (`col_…`), gegen die geantwortet werden soll.
`question`	string	REQ	Frage in natürlicher Sprache. Bis 4 000 Zeichen.
`llm`	string	OPT	Default: `claude-haiku-4-5`. Andere: `claude-sonnet-4-6`, `claude-opus-4-7`, `gpt-4`, `gpt-4o-mini`, `mistral-large`, `pharia-1`.
`include_sources`	boolean	OPT	Default `true`. Wenn `false`: nur `answer`, keine Citations.
`top_k`	integer	OPT	Anzahl Chunks im Retrieval (1–20). Default 4. Höhere Werte = bessere Recall, höhere Kosten.
`stream`	boolean	OPT	Default `false`. Wenn `true`: SSE-Stream mit Token-für-Token-Output.
`metadata_filter`	object	OPT	Optionaler Filter auf Document-Metadaten, z. B. nach Department oder ID-Bereich.
`language`	string	OPT	ISO-Code (`de`, `en`, `pl`, `tr`, ...). Default: aus Question erkannt.

Response

{
  "id": "qry_8f3a2b1c",
  "trace_id": "trc_8f3a2b1c",
  "answer": "Verwende ausschließlich Mineralöl HLP 46 (Spez. nach DIN 51524-2). Maschine zuvor abschalten und 30 Min. abkühlen lassen.",
  "citations": [
    {
      "source": "handbuch-hx2400.pdf",
      "page": 47,
      "chunk_id": "chunk_a1b2c3",
      "score": 0.92,
      "snippet": "Mineralöl HLP 46 nach DIN 51524-2..."
    }
  ],
  "llm_model": "claude-haiku-4-5",
  "tokens": {
    "input": 1240,
    "output": 87,
    "embedding": 12
  },
  "cost_eur": 0.0042,
  "latency_ms": {
    "embedding": 58,
    "retrieval": 142,
    "rerank": 95,
    "generation": 412,
    "total": 707
  },
  "region": "eu_fra"
}

Status-Codes

Code	Label	Bedeutung
`200`	OK	Query erfolgreich. Antwort + Citations im Body.
`400`	Validation Error	Ungültige Parameter (z. B. fehlende `collection_id` oder `question` über 4 000 Zeichen).
`401`	Unauthorized	Bearer-Token fehlt oder ist ungültig.
`403`	Forbidden	API-Key hat keinen Zugriff auf diese Collection (Workspace-Isolation).
`404`	Not Found	Collection existiert nicht oder ist gelöscht.
`429`	Rate Limited	Plan-Limit überschritten. `Retry-After`-Header beachten.
`500`	Internal Error	Unerwarteter Fehler. `trace_id` aufbewahren für Support-Anfrage.
`503`	LLM Provider Unavailable	Alle LLM-Provider haben gerade Probleme. Automatischer Failover läuft, retry empfohlen.

Streaming (SSE)

Mit stream: true liefert die API einen Server-Sent-Events-Stream. Der Client kann Token-für-Token rendern:

const stream = await client.query({
  collection_id: "col_abc123",
  question: "...",
  llm: "claude-sonnet-4-6",
  stream: true,
});
 
for await (const event of stream) {
  if (event.type === "token") {
    process.stdout.write(event.content);
  }
  if (event.type === "citation") {
    console.log("\n[Citation]", event.citation);
  }
  if (event.type === "done") {
    console.log("\nCost:", event.cost_eur);
  }
}

Beispiel: BYOK (Bring Your Own Key)

const result = await client.query({
  collection_id: "col_abc123",
  question: "...",
  llm: "claude-sonnet-4-6",
  byok: {
    provider: "anthropic",
    api_key: process.env.ANTHROPIC_API_KEY,
  },
});
 
// → cost_eur enthält nur die Anirag-Plattform-Gebühr
//    Die LLM-Kosten werden direkt von Anthropic abgerechnet