HTTP API

Call flow

Rendering diagram…

Endpoint inventory

Agents

Method	Path	Notes
`POST`	`/v1/combo/agents`	Create
`GET`	`/v1/combo/agents`	List
`GET`	`/v1/combo/agents/{agent_id}`	Inspect
`PUT`	`/v1/combo/agents/{agent_id}`	Update
`DELETE`	`/v1/combo/agents/{agent_id}`	Delete

Sessions

Method	Path	Notes
`POST`	`/v1/combo/agents/{agent_id}/sessions`	Create
`GET`	`/v1/combo/agents/{agent_id}/sessions`	List
`GET`	`/v1/combo/sessions/{session_id}`	Inspect
`DELETE`	`/v1/combo/sessions/{session_id}`	Delete
`POST`	`/v1/combo/sessions/{session_id}/archive`	Archive

Completions / messaging

Method	Path	Notes
`POST`	`/v1/combo/agents/{agent_id}/completions`	Chat with streaming support
`POST`	`/v1/combo/sessions/{session_id}/messages`	Append transcript without advancing automation

Knowledge bases

Method	Path	Notes
`POST`	`/v1/kb`	Create KB
`GET`	`/v1/kb`	List KBs
`POST`	`/v1/document`	Upload docs
`GET`	`/v1/document/{doc_id}`	Metadata + parse status
`POST`	`/v1/chunk/search`	Hybrid retrieval

Skills

Method	Path	Notes
`GET`	`/v1/skills`	Installed catalog
`POST`	`/v1/skills/install`	Install package
`POST`	`/v1/skills/{skill_id}/activate`	Bind to session
`GET`	`/v1/skills/{skill_id}`	Metadata

Cron jobs

Method	Path	Notes
`POST`	`/v1/cron`	Schedule
`GET`	`/v1/cron`	Enumerate
`DELETE`	`/v1/cron/{cron_id}`	Delete

Event triggers

Method	Path	Notes
`POST`	`/v1/event-trigger`	Create trigger
`GET`	`/v1/event-trigger`	List

Metadata / health

Method	Path	Notes
`GET`	`/v1/combo/scenarios`	Supported scenarios
`GET`	`/v1/combo/processors`	Processor registry
`GET`	`/v1/health`	Liveness
`GET`	`/v1/ready`	Readiness
`GET`	`/v1/openapi.json`	OpenAPI spec

Completions detail

POST /v1/combo/agents/{agent_id}/completions
Content-Type: application/json
Authorization: Bearer ragflow-<key>
 
{
  "session_id": "sess_abc123",
  "question": "Review https://gerrit.../c/456",
  "stream": true,
  "route": "@code-review@combo_solo@strict@"
}

Fields

Field	Type	Required	Notes
`session_id`	string	✅	Provision session beforehand
`question`	string	✅	User utterance
`stream`	boolean	❌	Default `false`; `true` → SSE stream
`route`	string	❌	Router pattern `@scenario@processor@mode@`
`attachments`	array	❌	File IDs
`context_ids`	array	❌	KB doc references

Streaming sequence

Rendering diagram…

event: thinking
data: {"phase": "plan"}

event: tool_call
data: {"tool": "gerrit.fetch_change", "args": {...}}

event: tool_result
data: {"tool": "gerrit.fetch_change", "result": {...}}

event: message
data: {"answer": "## Review\n\n..."}

event: done
data: {"session_id": "sess_abc123", "cost": {"tokens": 4320, "duration_ms": 18500}}

Non-streaming body

{
  "code": 0,
  "data": {
    "session_id": "sess_abc123",
    "answer": "## Review\n\n...",
    "reference": [...],
    "trace_id": "trc_xyz789",
    "cost": {
      "tokens": 4320,
      "duration_ms": 18500
    }
  }
}

File upload

POST /v1/document
Content-Type: multipart/form-data
 
file: <binary>
kb_id: <knowledge_base_id>
parser_id: naive | laws | paper | patent | ...

Response:

{
  "code": 0,
  "data": {
    "doc_id": "doc_abc123",
    "status": "parsing",
    "chunk_count": 0
  }
}

Poll GET /v1/document/{doc_id} for parser progress.

Hybrid search

POST /v1/chunk/search
Content-Type: application/json
 
{
  "question": "MCAL timeout retry",
  "kb_ids": ["kb_1", "kb_2"],
  "top_k": 10,
  "similarity_threshold": 0.7,
  "vector_similarity_weight": 0.3,
  "keyword_weight": 0.7,
  "rerank_top_n": 5
}

Error codes

Code	HTTP	Meaning
`0`	200	Success
`10001`	400	Bad request
`10002`	401	Unauthenticated
`10003`	403	Forbidden
`10004`	404	Missing resource
`10005`	409	Conflict
`10006`	429	Rate limited
`20001`	500	Internal error
`30001`	502	LLM failure
`30002`	504	Tool timeout

Rate-limit headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1699999999

HTTP API

On this page