An HTTP interface that takes a question, retrieves relevant passages from your own content, and returns either ranked evidence or a generated answer grounded in that evidence. It removes the need to operate embeddings, a vector store, a reranker and a citation layer yourself.

What should a RAG API return besides text?

Passage identifiers, document and page references, ranking scores and claim-to-source mapping. Without those, the answer cannot be verified and citations cannot be rendered.

Where does Uthereal Cortex store data?

In EU or Swiss data residency, with zero data retention and no training on customer data. Model choice and exit remain with the customer.

Can I use the retrieval without the generation?

Yes. POST to the rag endpoint and you get ranked JSON evidence to feed any model, agent or workflow you already run.

How is the API authenticated?

A scoped server-side key sent as Authorization: Bearer, with an X-App-Code header. Scopes are per capability (ask, rag), and the key must never be exposed to the browser.

Guide

Choosing a RAG API that can show its sources

Most retrieval APIs return plausible text. Production knowledge products need answers a reader, an auditor or a regulator can check. These are the criteria that separate the two.

Short answer: judge a RAG API on provenance, not on demo quality. It should return stable passage identifiers, claim-to-source mapping, page-level evidence, retrieval-only output, scoped server keys and a clear data-residency and retention posture. Uthereal Cortex exposes exactly that through two endpoints: ask and rag.

Create your agent Read the SDK guide

Eight criteria for production RAG

Provenance — claim-level citations, not a document list appended to the answer
Page-level evidence — the cited PDF page opens with the passage highlighted
Retrieval-only mode — ranked JSON you can feed to your own model
Ingestion quality — layout-aware parsing of tables, headings and footnotes
Refusal behaviour — no supporting passage means no invented answer
Key hygiene — scoped, server-side keys; nothing usable in a browser bundle
Data posture — residency, retention and whether your content trains someone's model
Exit — model choice and the ability to leave with your own knowledge intact

The Cortex endpoints

Base URL https://agent.uthereal.ai/api/functions/v1/api-server-proxy, with Authorization: Bearer <key> and X-App-Code: selfserve.

API surface

POST /external/v1/assistants/{assistant}/sessions/{session}/ask
  → NDJSON stream of answer snapshots, references and claims

POST /external/v1/assistants/{assistant}/rag
  → { results: [{ id_element, id_datasource, content, rank, metadata }] }

GET  /chat/reference/pdf/{token}?page={page}
POST /chat/reference/pdf/refresh
  → the cited source page, highlighted

Cited answer, streamed

curl -N -X POST \
  "$BASE/external/v1/assistants/$ASSISTANT_ID/sessions/$SESSION/ask" \
  -H "Authorization: Bearer $CORTEX_SHARED_API_KEY" \
  -H "X-App-Code: selfserve" \
  -H "Content-Type: application/json" \
  -d '{"id_user":"user-123","message":"What does the policy say about refunds?"}'

Accuracy is a provenance problem

In regulated products — medical, legal, financial, government, professional publishing — an answer that cannot be traced is worth less than no answer at all. Provenance is what makes accuracy measurable: you can audit a cited answer, correct the source, and see the correction flow through.

Every claim carries the passage that supports it
Sources stay under your control, in your jurisdiction
Corrections happen in the source document, not in prompt patches
Failure is visible: missing evidence produces a refusal, not a guess

Getting started in three steps

Create an agent and upload sources at agent.uthereal.ai
Create a scoped server key with the ask and/or rag scope
Install the SDK guide into your AI coding tool and describe the feature

Frequently asked questions

What is a RAG API?: An HTTP interface that takes a question, retrieves relevant passages from your own content, and returns either ranked evidence or a generated answer grounded in that evidence. It removes the need to operate embeddings, a vector store, a reranker and a citation layer yourself.
What should a RAG API return besides text?: Passage identifiers, document and page references, ranking scores and claim-to-source mapping. Without those, the answer cannot be verified and citations cannot be rendered.
Where does Uthereal Cortex store data?: In EU or Swiss data residency, with zero data retention and no training on customer data. Model choice and exit remain with the customer.
Can I use the retrieval without the generation?: Yes. POST to the rag endpoint and you get ranked JSON evidence to feed any model, agent or workflow you already run.
How is the API authenticated?: A scoped server-side key sent as Authorization: Bearer, with an X-App-Code header. Scopes are per capability (ask, rag), and the key must never be exposed to the browser.

How to add citations to an AI chatbot

The architecture behind cited answers.

Build vs buy for RAG

What DIY retrieval really costs.

Uthereal Cortex SDK

Full developer guide.

What Cortex is

The platform behind the API.