# Choosing a RAG API that can show its sources

> Choosing a RAG API for production: the eight criteria that decide answer quality, provenance and data control - plus the exact Uthereal Cortex endpoints for cited answers and raw retrieval.

- Canonical page: https://uthereal.ai/developers/rag-api
- Last updated: 2026-09-18
- Product: Uthereal Cortex (sovereign enterprise AI, Swiss/EU data residency)
- npm package: `@uthereal-sdk/cortex` (https://www.npmjs.com/package/@uthereal-sdk/cortex)
- Repository: https://github.com/Uthereal-Labs/Uthereal-Cortex-SDK

## Short answer

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.

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.

## 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.

```
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
```
_API surface_

```
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?"}'
```
_Cited answer, streamed_

## 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.

## Related pages

- [How to add citations to an AI chatbot](https://uthereal.ai/developers/rag-with-citations): The architecture behind cited answers.
- [Build vs buy for RAG](https://uthereal.ai/developers/rag-sdk-comparison): What DIY retrieval really costs.
- [Uthereal Cortex SDK](https://uthereal.ai/developers/sdk): Full developer guide.
- [What Cortex is](https://uthereal.ai/cortex): The platform behind the API.

## Next steps

- Create an agent and a scoped server key: https://agent.uthereal.ai
- Full SDK guide (HTML): https://uthereal.ai/developers/sdk
- Full SDK guide (Markdown): https://uthereal.ai/developers/sdk.md
- AI index for this site: https://uthereal.ai/llms.txt and https://uthereal.ai/llms-full.txt
- Help: sdk@uthereal.ai