---

name: sdk-http-integration description: "Use RAGFlow public HTTP APIs, the Python SDK, OpenAI-compatible chat completions, API keys, streaming, references, and client error handling." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

SDK and HTTP Integration

Use this sub-skill when a task needs to call RAGFlow through its public REST API, Python SDK, OpenAI-compatible chat completions, retrieval endpoint, API keys, or client-side troubleshooting.

Start here

• For endpoint families, SDK objects, request shapes, and migration notes, read references/api-sdk-reference.md.
• For authentication, status codes, RAGFlow response codes, and safe error handling, read references/auth-and-errors.md.
• For common failures such as wrong base_url, API key errors, stream parsing, ID confusion, DELETE bodies, and server availability, read references/troubleshooting.md.
• To prepare or optionally run a harmless health check request, use scripts/ragflow_api_smoke.py --help.

Public integration boundaries

• Prefer the Python package ragflow-sdk for Python clients and RAGFlow(api_key, base_url, version="v1") for SDK entrypoints.
• Use HTTP paths under /api/v1 for public REST calls; do not depend on backend module internals or frontend hooks.
• For OpenAI-compatible chat calls, configure OpenAI clients with base_url="<server>/api/v1/openai/<chat_id>/chat" and call client.chat.completions.create(...).
• Treat dataset, document, chunk, chat, agent, session, and memory IDs as distinct resource identifiers; do not substitute one ID type for another.
• Use the public examples in these references as distilled patterns; do not require future agents to open repository examples or tests.

Typical workflows

• Dataset/document/chunk flow: create or list a dataset, upload or create documents, parse documents, list or update chunks, then retrieve chunks through /api/v1/retrieval or RAGFlow.retrieve(...).
• Chat flow: create or list a chat assistant, create or list sessions, ask through Session.ask(...) or /api/v1/chat/completions, and preserve reference metadata when citations matter.
• Agent flow: list or get agents, create sessions when needed, call /api/v1/agents/chat/completions, and request traces only when debugging component behavior.
• Memory flow: create/list/update/delete memories and add/search/retrieve messages through the SDK methods summarized in references/api-sdk-reference.md.

Safety defaults

• Never print real API keys in generated curl commands or logs.
• Do not run destructive deletes unless the user explicitly provides target IDs or asks for delete_all semantics.
• Prefer non-stream requests while debugging request shape; add streaming only after auth, URL, and payload validation pass.
• Run scripts/ragflow_api_smoke.py without --execute first; it only prints a redacted prepared request by default.