Skip to main content

​
Introduction

The DeerFlow Gateway API provides RESTful endpoints for managing models, skills, MCP servers, memory, file uploads, and artifacts. It runs as a separate FastAPI service alongside the LangGraph Server.

​
Base URL

The API Gateway runs on port 8001 by default: 
http://localhost:8001
All API endpoints are prefixed with /api: 
http://localhost:8001/api/models
http://localhost:8001/api/skills
http://localhost:8001/api/memory

​
Architecture

The Gateway API is built with FastAPI and provides:
  • Models Management: Query available AI models and their capabilities
  • Custom Agents: Create and manage specialized agents with SOUL.md profiles
  • Skills Management: List, enable/disable, and install custom skills
  • MCP Configuration: Manage Model Context Protocol server configurations
  • Memory Management: Access and reload global memory data
  • File Uploads: Upload files to thread-specific directories
  • Artifacts: Access and download thread-generated files
LangGraph requests are handled by nginx reverse proxy, while the Gateway provides custom endpoints for configuration and file management.

​
Authentication

The Gateway API currently does not require authentication for local development. CORS is handled by nginx in production deployments. CORS Origins: Configurable via CORS_ORIGINS environment variable (default: http://localhost:3000)

​
Configuration

The Gateway can be configured using environment variables:
​
GATEWAY_HOST
string
default:"0.0.0.0"
Host to bind the gateway server
​
GATEWAY_PORT
integer
default:"8001"
Port to bind the gateway server
​
CORS_ORIGINS
string
default:"http://localhost:3000"
Comma-separated list of allowed CORS origins

​
Error Handling

The API uses standard HTTP status codes:
​
200
OK
Request succeeded
​
400
Bad Request
Invalid request parameters or malformed data
​
403
Forbidden
Access denied (e.g., path traversal attempt)
​
404
Not Found
Resource not found
​
409
Conflict
Resource already exists (e.g., duplicate skill)
​
500
Internal Server Error
Server error

​
Error Response Format

Error responses follow this format: 
{
  "detail": "Error message describing what went wrong"
}

​
Interactive Documentation

The Gateway API provides interactive documentation:
  • Swagger UI: http://localhost:8001/docs
  • ReDoc: http://localhost:8001/redoc
  • OpenAPI Schema: http://localhost:8001/openapi.json

​
Health Check

Check the Gateway service health: 
curl http://localhost:8001/health
Response: 
{
  "status": "healthy",
  "service": "deer-flow-gateway"
}

​
Next Steps

Models API

Query available AI models

Custom Agents API

Create specialized agents

Skills API

Manage skills and extensions

MCP API

Configure MCP servers

Memory API

Access global memory

Uploads API

Manage file uploads

Build docs developers (and LLMs) love

Get started for freeTalk to us