Gateway API Overview

Introduction to the DeerFlow Gateway API, authentication, and common patterns

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