Skip to content

API quickstart

This page walks through the whole flow against the public /v1 API of the RAG Platform: upload a document, wait until it's processed, and ask a question about it.

Before you start

For development it is recommended to run a local dev-instance.

Send the created key as a bearer token on every /v1 request:

Authorization: Bearer local-dev-key-change-me

The key determines your tenant: all your files and collections are visible only to keys of the same tenant. Requests carry no tenant field. A missing or unknown key returns 401.

Request and response bodies use JSON with snake_case field names. Route paths are case-insensitive.

1. Pick a model

curl http://localhost:8000/v1/models -H "Authorization: Bearer local-dev-key-change-me"

The list comes from the configured inference provider. Every completion request must name a model from it.

2. Upload a file

Uploads are multipart/form-data. A collection is addressed by up to three integers: ApplicationId and InstanceId (required) and EntityId (optional). Choose numbers that map to your application's structure, for example one collection per rag chat-instance.

curl http://localhost:8000/v1/rag/upload \
  -H "Authorization: Bearer local-dev-key-change-me" \
  -F purpose="assistants" \
  -F file="@handbook.pdf" \
  -F ApplicationId=1 \
  -F InstanceId=1 \
  -F EntityId=1

The response contains the file's id and its collection_id, which is built from the three numbers:

{"id": "eb8a7f36-03f2-4114-99f4-965d7cb40fca", "collection_id": "app_1_instance_1_entity_1", "detail": "…", "…": "…"}

Limits and rules:

  • Accepted file types: .pdf, .txt, .png, .jpg, .jpeg. The file's leading bytes must match its extension, and .txt files must be UTF-8.
  • Maximum file size: 256 MB.
  • purpose is currently ignored. Send assistants.
  • Uploading the same content into the same collection again doesn't create a second file. You get the existing file's id. A file whose processing FAILED is processed again. To reprocess a COMPLETED file, delete it first.

3. Wait for processing

Ingestion runs in the background. Poll the file status until it's COMPLETED (or FAILED). Name the collection with the same numbers as in the upload, as JSON in snake_case:

curl http://localhost:8000/v1/rag/status \
  -H "Authorization: Bearer local-dev-key-change-me" \
  -H "Content-Type: application/json" \
  -d '{"id": "eb8a7f36-03f2-4114-99f4-965d7cb40fca", "application_id": 1, "instance_id": 1, "entity_id": 1}'

status is one of PENDING, PROCESSING, COMPLETED and FAILED. If it's FAILED, error_message says why. Only COMPLETED files are used for answers.

4. Ask a question

POST /v1/rag/completions takes an OpenAI-style chat completion request plus collection_ids, the collections to search:

curl http://localhost:8000/v1/rag/completions \
  -H "Authorization: Bearer local-dev-key-change-me" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_FROM_STEP_1",
    "messages": [{"role": "user", "content": "How many vacation days do I have?"}],
    "collection_ids": ["app_1_instance_1_entity_1"]
  }'
  • The platform searches the named collections for the last user message, adds the best matches as sources to that message, and generates the answer.
  • top_k (default 10) sets how many chunks are retrieved.
  • Without collection_ids, the tenant's default collection is searched.
  • The usual chat parameters are supported: model, messages, stream, temperature, top_p, max_completion_tokens and more. See the API reference.
  • The response is a chat completion with an extra chunks field containing the retrieved sources. The answer cites them with markers containing the reference_index such as [cit-1].
  • The API is stateless. Send the full conversation in messages on every request.

For streaming and for rendering citations, read Streaming and citations.

Other endpoints

Endpoint Purpose
POST /v1/rag/augmentation Retrieval only: returns the augmented messages and the chunks, without generating an answer. Use it to send the prompt to a model yourself
POST /v1/rag/delete Delete a file and all its chunks. Same body as the status request
POST /v1/chat/completions Plain chat completion through the configured provider, without retrieval
GET /version Running version. Needs no API key

The complete request and response schemas are in the API reference. How errors are reported is described in Errors.

API version

/v1 is the version of the HTTP API. These docs describe it as shipped with RAG Platform 1.1.