API key and SDK
How to get an API key, the /api/v1 base address, Bearer authorization, the main methods for knowledge bases, documents, assistants and sessions, and a Python SDK example.
Everything available in the Gleyk interface is also available through the HTTP API. The key is bound to an organization, so requests see only its knowledge bases, assistants and agents.
Getting a key
- Click the avatar in the top right corner and open settings.
- Go to the "API" page.
- Create a key and save it in a secure store: it is not shown in full again.
The key acts on behalf of the organization in which it was created. Create a separate key for each application so that you can revoke them independently. A public beta token for the embeddable chat is created together with the key; it is covered in the article Embedding a chat on a website.
Warning
An API key gives access to the organization's data. Do not put it in client-side code, repositories or logs.
Base address and authorization
The base address is https://<your-host>/api/v1. Every request carries this header:
Authorization: Bearer <api-key>
Content-Type: application/jsonThe response has the form {"code": 0, "data": ...}. A non-zero code means an error, with the text in the message field. Codes 401 and 403 mean a wrong key or missing permissions.
Main methods
| Group | Method | Purpose |
|---|---|---|
| Knowledge bases | POST /datasets, GET /datasets, PUT /datasets/{id}, DELETE /datasets | Create, list, update, delete |
| Documents | POST /datasets/{id}/documents (multipart), GET /datasets/{id}/documents, POST /datasets/{id}/chunks | Upload, list, start processing |
| Chunks | GET /datasets/{id}/documents/{doc_id}/chunks, POST /retrieval | View chunks, search across knowledge bases |
| Assistants | POST /chats, GET /chats, PUT /chats/{id}, DELETE /chats | Manage assistants |
| Sessions | POST /chats/{id}/sessions, GET /chats/{id}/sessions, DELETE /chats/{id}/sessions | Assistant conversations |
| Answers | POST /chats/{id}/completions | Ask an assistant a question, with a streaming or regular answer |
| Agents | POST /agents/{id}/sessions, POST /agents/{id}/completions | Run an agent from the canvas |
| OpenAI-compatible | POST /chats_openai/{id}/chat/completions, POST /agents_openai/{id}/chat/completions | The messages format, works with ready-made clients |
The full list of parameters is in the HTTP API reference included in the platform documentation.
Streaming answer
A request with "stream": true returns text/event-stream. Each event has the form data: {"code": 0, "data": {"answer": "...", "reference": {...}, "session_id": "..."}}, where answer accumulates, and reference holds the chunks and documents the answer is based on. The last event contains "data": true.
curl -N https://<your-host>/api/v1/chats/<chat_id>/completions \
-H "Authorization: Bearer <api-key>" \
-H "Content-Type: application/json" \
-d '{"question": "What is the approval period for a request?", "stream": true}'If you do not pass session_id, the first call creates a session and returns its identifier in the response. Pass it in the following requests to keep the conversation history.
For assistants on the new chat core, the response additionally contains a smx_runtime object with the turn status, the session and run identifiers, and confirmation details. If the assistant prepares an action in an external system, it stops and waits for a decision: send the decision to the same endpoint with session_id, confirmation_id, decision (approve or reject) and a new operation_id. The operation_id parameter makes retrying a request safe: the same identifier does not cause a second execution.
Python SDK
The package is called ragflow-sdk and is installed with pip install ragflow-sdk. Here is an example of the full cycle: knowledge base, document, assistant, question.
from ragflow_sdk import RAGFlow
rag = RAGFlow(api_key="<api-key>", base_url="https://<your-host>")
dataset = rag.create_dataset(name="Policies")
with open("reglament.pdf", "rb") as f:
dataset.upload_documents([{"display_name": "reglament.pdf", "blob": f.read()}])
docs = dataset.list_documents()
dataset.async_parse_documents([d.id for d in docs])
chat = rag.create_chat(name="Policy assistant", dataset_ids=[dataset.id])
session = chat.create_session()
for chunk in session.ask("What is the approval period for a request?", stream=True):
print(chunk.content)base_url is given without the /api/v1 suffix: the SDK adds it itself. Documents are processed in the background, so before the first question wait until the documents reach the "SUCCESS" state (the list_documents method returns the processing status).
Tip
For search without generation, use rag.retrieve(...) or POST /retrieval: you get chunks with similarity scores and can assemble the answer in your own code.
What next
- Embedding a chat on a website: a public widget without an API key on the client.
- MCP servers: tools for agents and external clients.
- Agents on the canvas: an agent as an endpoint with input parameters.
Ask Sema