# Deer-flow API Documentation: Complete Reference for Backend Integration

> Explore the complete Deer-flow API documentation for backend integration. Access HTTP endpoints for models, file uploads, skills, and chat via FastAPI gateway and Python client.

- Repository: [Bytedance Inc./deer-flow](https://github.com/bytedance/deer-flow)
- Tags: api-reference
- Published: 2026-03-08

---

**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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/routers/models.py)** – Model listing and metadata retrieval
- **[`backend/src/gateway/routers/uploads.py`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/routers/uploads.py)** – File ingestion and markdown conversion
- **[`backend/src/gateway/routers/skills.py`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/config/app_config.py) using Pydantic models. The `AppConfig` class loads [`config.yaml`](https://github.com/bytedance/deer-flow/blob/main/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:

```bash
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:

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

```

Implementation resides in [`backend/src/gateway/routers/models.py`](https://github.com/bytedance/deer-flow/blob/main/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:

```bash
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`](https://github.com/bytedance/deer-flow/blob/main/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:

```bash
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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/routers/skills.py) router validates the request against skill front-matter definitions and updates [`extensions_config.json`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/client.py) provides `DeerFlowClient`, which mirrors every HTTP endpoint while re-using the same Pydantic models for guaranteed API parity.

```python
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:

```python
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:

```python
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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/subagents/registry.py). Long-term memory and conversation checkpointing are handled by `backend/src/agents/memory/` and [`backend/src/agents/checkpointer.py`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/backend/src/gateway/routers/skills.py) router validates enable/disable requests and persists state to [`extensions_config.json`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/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`](https://github.com/bytedance/deer-flow/blob/main/config.yaml) values.