deer-flow/docs/guide/api-and-client.md

API Access and Python Client

Existing-Run Stream Actions

Existing-run SSE joins are observation-only on GET: supplying action=interrupt|rollback returns 405. Cancellation on this stream route is POST-only and requires the runs:cancel permission. Accordingly, the OpenAPI contract exposes action and wait only on POST; the GET operation exposes only its path parameters.

Personal Access Tokens

Non-interactive clients (CI pipelines, scripts, server-to-server integrations) can call the Gateway API with a personal access token (PAT) instead of a browser session. Create one while logged in via POST /api/v1/auth/pats — the raw dfp_... value is shown exactly once; only its SHA-256 digest is stored — then send it as a Bearer credential:

POST /api/threads/search
Authorization: Bearer dfp_...
Content-Type: application/json

{}

Each token runs with its owning user's identity (owner filtering and per-user memory keep working), carries a scope set that can only narrow that user's permissions, and is admitted only to the thread/run lifecycle routes — every other route answers 403 to PAT callers, and a PAT never carries admin capability. Tokens can be listed and revoked at any time; revocation is immediate. PATs require a database backend (SQLite/PostgreSQL). Full reference: API Reference — Personal Access Tokens.

Embedded Python Client

User messages are framed as untrusted input. Reserved XML-like tags are escaped for model context only when present; tag-free URLs and shell commands retain their ampersands unchanged. Encoded payloads include a note to decode exactly once when reproducing the original text in files, code, or tool-call arguments. This preserves XML angle brackets and literal HTML entities in verbatim-content requests while keeping user-supplied tags separate from framework instructions. Copied encoding notes are treated as user text; only request-local program state permits reuse of an already encoded frame.

chat() and stream() preserve text appended by model middleware before the first state snapshot, emitting only the suffix after the streamed text.

For DeerFlowClient(agent_name="researcher"), the named agent's mcp_plugins selection applies to both the lead agent and its task / batch_task delegations: null inherits all enabled MCP plugins, [] selects none, and installation IDs select only those plugins. Call client.reset_agent() after editing the saved agent configuration to refresh the selection.

DeerFlowClient.stream() includes summary_text in each values event. This is the current compacted context summary, or None when absent. Consumers can record changes without reading checkpoint internals; repeated snapshots may carry the same summary, and an initial snapshot may already contain one from an earlier turn.

DeerFlow can be used as an embedded Python library without running the full HTTP services. The DeerFlowClient provides direct in-process access to all agent and Gateway capabilities, returning the same response schemas as the HTTP Gateway API.

The HTTP Gateway exposes DELETE /api/threads/{thread_id} to remove a thread's files, checkpoints, and metadata. If checkpoint deletion fails, the Gateway returns 500 and retains the owner record for retry. Thread cleanup API

An embedded DeerFlowClient(config_path="custom/config.yaml") keeps the process config singleton on that file, even after a working-directory change. Later edits to the file are still detected. Call reload_app_config() without a path to resume ambient config discovery, or reset_app_config() to clear the cached selection.

For database-backed run events, deleting a run preserves its thread's sequence watermark. Thread deletion removes that watermark once no events remain, allowing a recreated thread to restart at sequence 1. Owner-scoped deletion preserves the watermark when another owner's events remain.

Single-process JSONL event storage also retains the thread sequence watermark across run deletion and restarts, so clients using after_seq do not miss later messages. Keep runs/.seq-watermark with the run files when backing up this backend. New or replaced watermarks inherit the deleted run file's permission bits. Deleting the complete thread removes the watermark and resets allocation.

Thread IDs may be supplied by callers and do not have to be UUIDs. Explicit IDs must contain 1–64 ASCII letters, digits, hyphens, or underscores (^[A-Za-z0-9_-]{1,64}$). DeerFlow generates a UUID only when thread_id is omitted or None; an explicitly supplied empty string is invalid. Concurrent POST /api/threads requests and automatic run metadata creation share same-ID admission in one Gateway, preserving the first thread's metadata and status. HTTP retries also preserve its current checkpoint. SQL-backed Gateways retain duplicate-insert recovery across workers. Existing route-addressable threads created under older, looser rules remain readable and deletable, but cannot start new runs or create new filesystem or sandbox state. Legacy deletion skips local path cleanup when the ID is not safe under the canonical contract. For canonical legacy threads whose conversation exists only in LangGraph checkpoints, DeerFlow seeds an empty run-event feed from the checkpoint before the first new run so /messages/page keeps both the old and new turns.

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

# Chat
response = client.chat("Analyze this paper for me", thread_id="my-thread")

# Streaming (LangGraph SSE protocol: values, messages-tuple, end)
for event in client.stream("hello"):
    if event.type == "messages-tuple" and event.data.get("type") == "ai":
        print(event.data["content"])
    elif event.type == "messages-tuple" and event.data.get("type") == "tool" and "artifact" in event.data:
        # Structured tool artifacts (for example, ask_clarification cards)
        # are preserved when the ToolMessage provides one.
        print(event.data["artifact"])

# Configuration & management — returns Gateway-aligned dicts
models = client.list_models()        # {"models": [...]}
skills = client.list_skills()        # {"skills": [...]}
client.update_skill("web-search", enabled=True)
client.upload_files("thread-1", ["./report.pdf"])  # {"success": True, "files": [...]}
client.set_goal("thread-1", "finish the implementation and make all tests pass")
client.get_goal("thread-1")       # {"goal": {...}} or {"goal": None}
client.clear_goal("thread-1")

When continuing a thread, values still contains the full conversation state, while messages-tuple and end.usage cover only the current turn.

The embedded client's end.usage sums usage deltas across streamed chunks, including providers such as native Gemini that report usage more than once per reply. The completed message's usage is reconciled without counting those chunks again; a lower completed-message count does not subtract tokens already reported by chunks. Signed provider corrections in chunks remain supported, as do providers that report usage only at completion.

Concurrent upload_files() calls preserve filenames absent at the start of each call by assigning numeric suffixes and returning the actual saved names. The same rule applies to new Markdown companions. Exact names already present retain replacement behavior. Convertible files use one private source capture through all filename retries and conversion, preserving the original permissions and timestamps. Detected staging-file substitution is rejected; staging cleanup failures are logged without masking the upload outcome.

The HTTP Gateway accepts values, messages-tuple, updates, debug, tasks, checkpoints, and custom stream modes. Unsupported modes such as messages and events, unsupported non-default run options such as webhooks, delayed execution, or multitask_strategy="enqueue", and undeclared SDK options such as checkpoint durability overrides return 422 before execution instead of being silently ignored or downgraded.

All dict-returning methods are validated against Gateway Pydantic response models in CI (TestGatewayConformance), ensuring the embedded client stays in sync with the HTTP API schemas. See backend/packages/harness/deerflow/client.py for full API documentation.