API

You can find your full API documentation and OpenAPI reference under

https://<your-installation>/api/v2/docs/swagger

In most cases you only need two methods - Ask a question and Get the answer:

Ask a question

curl -X 'POST' \
  '<ROOT_URL>/api/v2/question/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <INSERT_YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "question": "How to get started?"
}'

will return

{
  "question_id": "xxx",
  "chat_id": "yyy"
}

Get the answer:

curl -X 'GET' \
  '<ROOT_URL>/api/v2/question/xxx/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <INSERT_YOUR_TOKEN>'

which will return

{
  "id": "xxx",
  "text": "How to get started ?",
  "response": "<...here will be a partial answer until is_read is true...>",
  "is_ready": true,
   ...
}

The full answer is available once is_ready is true.

Ask a follow-up question

To contintue the same conversation, pass the chat_id when you post a follow-up question.

curl -X 'POST' \
  '<ROOT_URL>/api/v2/question/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <INSERT_YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "question": "What do I do next?",
  "chat_id", "yyy"
}'

Attach images to a question

SerenityGPT can answer questions about uploaded images, such as screenshots. Attaching an image takes two steps: upload the image to get a file ID, then submit the question with that ID.

Upload the image

Send each image as multipart form data in the files field. Repeat the field to upload several images in one request. The response returns one entry per file with its generated id.

curl -X 'POST' \
  '<ROOT_URL>/api/v2/files/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <INSERT_YOUR_TOKEN>' \
  -F 'files=@screenshot.png'

returns

[
  { "id": "abc123", "filename": "screenshot.png" }
]

Ask a question about the image

Pass the file IDs from the previous step in the file_ids array. The question text is optional when an image is attached, so you can send an image on its own.

curl -X 'POST' \
  '<ROOT_URL>/api/v2/question/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <INSERT_YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "question": "What does this screenshot show?",
  "file_ids": ["abc123"]
}'

Retrieve the answer with the Get the answer endpoint as usual.

Display attached images

GET /api/v2/question/{id}/ includes a files array for the question. Each entry contains a preview path to a thumbnail:

"files": [
  {
    "id": "abc123",
    "filename": "screenshot.png",
    "mime_type": "image/png",
    "preview": "files/abc123/preview/"
  }
]

Request the thumbnail from <ROOT_URL>/api/v2/files/{id}/preview/. This endpoint requires the Authorization header, so fetch the image in code and render the result instead of pointing an <img> tag directly at the URL. The preview value is null for files that have no generated thumbnail.

Remove an upload

To discard an uploaded image before submitting its question, call:

curl -X 'DELETE' \
  '<ROOT_URL>/api/v2/files/{id}/' \
  -H 'Authorization: Bearer <INSERT_YOUR_TOKEN>'

After you submit the question, its files become part of the conversation record and cannot be deleted.

Search API for Distributed RAG

The /api/v2/rag/search/ endpoint allows SereninyGPT to query documents for a given tenant via API. This is useful when you want to:

• Use documentation stored on a remote machine
• Share documentation across multiple SerenityGPT instances
• Enable cross-tenant or cross-project search

See configuration for more details.

Note: This endpoint is intended for use by other backend services, not for direct user queries

Endpoint

POST /api/v2/rag/search/

Request Body

{
  "query": "How to get started?",
  "filters": { ... },
  "search_mode": "semantic",  // or "keyword"
  "question_metadata": { ... }
}

Example Request

curl -X POST \
  '<ROOT_URL>/api/v2/rag/search/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "How to get started?",
    "search_mode": "semantic"
  }'

Healthcheck

The /api/v2/health endpoint allows checking the health status of the SerenityGPT services.

Endpoint

GET /api/v2/health?mode=

Parameter: mode

Type: string

Determines the depth of the health check.

Possible values: full – performs a complete check (DB, embedding service, LLM) basic – default; checks DB and embedding service only minimal – skips all checks and always returns ok

Quick manual check

curl http://<ROOT_URL>/api/v2/health?mode=full