Deer-flow API Documentation: Complete Reference for Backend Integration

Deer-flow exposes a unified FastAPI gateway that provides HTTP endpoints for models, file uploads, skills management, and streaming chat, alongside an embedded Python client that mirrors the REST interface for in-process programmatic access.

Deer-flow is a modular "super-agent" framework built on LangGraph and LangChain within the bytedance/deer-flow repository. Its public API surface is anchored by a centralized gateway architecture that stitches together model management, skill orchestration, and sandboxed agent execution, all configurable through a Pydantic-based configuration system.

Core API Architecture

FastAPI Gateway and Routers

The API entry point is created in backend/src/gateway/app.py via the create_app() factory function. This lifespan-managed FastAPI instance registers domain-specific routers that each handle a logical functional area:

• backend/src/gateway/routers/models.py – Model listing and metadata retrieval
• backend/src/gateway/routers/uploads.py – File ingestion and markdown conversion
• backend/src/gateway/routers/skills.py – Runtime skill enablement and validation

Each router depends on the AppConfig singleton (accessed via get_app_config() from backend/src/config/app_config.py) to resolve runtime settings, ensuring consistent behavior across HTTP and embedded clients.

Configuration System

Configuration is centralized in backend/src/config/app_config.py using Pydantic models. The AppConfig class loads config.yaml, extension files (MCP servers, skill state), and environment variables through the resolve_env_variables() method. Values such as $OPENAI_API_KEY are interpolated at load time, allowing secrets to be injected without modifying committed configuration files.

HTTP API Endpoints

Model Management

List all configured LLMs and their capabilities:

curl -X GET http://localhost:8001/api/models \
     -H "Accept: application/json"

The response returns a ModelsListResponse containing model metadata including supports_thinking and supports_reasoning_effort flags. Retrieve a single model's details by appending the model name to the path:

curl -X GET http://localhost:8001/api/models/gpt-4

Implementation resides in backend/src/gateway/routers/models.py, which constructs ModelResponse objects from the active configuration.

File Uploads and Artifacts

Upload files to a specific conversation thread:

curl -X POST http://localhost:8001/api/threads/12345/uploads \
     -F "files=@/path/to/report.pdf"

The handler in backend/src/gateway/routers/uploads.py stores files under the sandbox uploads/ directory and generates markdown previews for supported document types. Uploaded files become accessible to the agent runtime for processing.

Skill Management

Enable or disable skills dynamically without restarting the service:

curl -X PATCH http://localhost:8001/api/skills/web-search \
     -H "Content-Type: application/json" \
     -d '{"enabled": true}'

The backend/src/gateway/routers/skills.py router validates the request against skill front-matter definitions and updates extensions_config.json. The next agent invocation automatically loads the modified skill set.

Embedded Python Client

Synchronous and Streaming Chat

For programmatic access within Python processes, backend/src/client.py provides DeerFlowClient, which mirrors every HTTP endpoint while re-using the same Pydantic models for guaranteed API parity.

from src.client import DeerFlowClient

client = DeerFlowClient()  # Reads config.yaml automatically

thread_id = "demo-thread"

# Blocking call returning final answer

answer = client.chat(
    "Summarize the attached PDF and suggest a slide outline.",
    thread_id=thread_id,
)
print("AI:", answer)

Streaming and Artifact Retrieval

Stream incremental LangGraph events to observe tool calls and partial responses:

for ev in client.stream(
    "Summarize the attached PDF and suggest a slide outline.",
    thread_id=thread_id,
):
    if ev.type == "messages-tuple" and ev.data["type"] == "ai":
        print(">>", ev.data["content"])
    elif ev.type == "messages-tuple" and ev.data["type"] == "tool":
        print("[tool]", ev.data["name"], "→", ev.data["content"])

Retrieve generated artifacts with path traversal protection:

bytes_data, mime = client.get_artifact(
    thread_id="demo-thread",
    path="mnt/user-data/outputs/report.pdf",
)
with open("report.pdf", "wb") as f:
    f.write(bytes_data)

The get_artifact method validates virtual paths against the sandbox root to prevent directory traversal attacks.

Agent Runtime and Extensibility

When processing chat requests, the gateway forwards messages to the lead agent (src.agents.lead_agent.agent). This agent loads required tools (from backend/src/tools/builtins/), skills (markdown definitions in skills/public/), and sandbox configurations (Docker, local, or Kubernetes providers in backend/src/sandbox/).

Dynamic sub-agents can be spawned for parallel work, registered via backend/src/subagents/registry.py. Long-term memory and conversation checkpointing are handled by backend/src/agents/memory/ and backend/src/agents/checkpointer.py, enabling multi-turn conversational state.

Summary

• Deer-flow provides a FastAPI gateway at localhost:8001 exposing REST endpoints for models, uploads, and skills.
• The backend/src/client.py embedded client offers identical functionality for Python scripts without HTTP overhead.
• Configuration is centralized in backend/src/config/app_config.py with environment variable resolution via resolve_env_variables().
• File uploads are processed by backend/src/gateway/routers/uploads.py, storing content in isolated sandbox directories.
• Agent execution occurs in configurable sandboxes (Docker/K8s/local) with extensible skills defined in markdown files.

Frequently Asked Questions

What is the default base URL for Deer-flow API requests?

The FastAPI gateway binds to http://localhost:8001 by default when running locally. All HTTP examples assume this endpoint, though the host and port are configurable via config.yaml or environment variables resolved by AppConfig.

How does the embedded Python client differ from direct HTTP calls?

DeerFlowClient in backend/src/client.py provides an in-process wrapper that internally constructs the same Pydantic models (ModelResponse, etc.) used by the gateway. It eliminates HTTP serialization overhead for local scripts while maintaining identical validation and response structures.

Where are skill configurations stored and validated?

Skill metadata lives in markdown front-matter within skills/public/**/*.md. The backend/src/gateway/routers/skills.py router validates enable/disable requests and persists state to extensions_config.json, allowing runtime modification without service restarts.

Can I override configuration values with environment variables?

Yes. The AppConfig class in backend/src/config/app_config.py calls resolve_env_variables() during initialization, interpolating values like $OPENAI_API_KEY or custom variables defined in your shell environment. These overrides take precedence over config.yaml values.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}