Skip to main content
OpenFang exposes a comprehensive REST API, WebSocket endpoints, and SSE streaming when the daemon is running. The API provides full programmatic control over agents, workflows, memory, skills, and system configuration.

​
Base URL

The default API listen address is: 
http://127.0.0.1:4200
You can configure a custom address in ~/.openfang/config.toml: 
api_listen = "127.0.0.1:4200"

​
Endpoint Count

OpenFang provides 140+ API endpoints across the following categories:
  • Agent management and lifecycle
  • Workflow orchestration and execution
  • Memory (KV store, sessions, knowledge graph)
  • Channel adapters (40+ messaging platforms)
  • Skills and marketplace (FangHub + ClawHub)
  • MCP server integration
  • A2A (Agent-to-Agent) protocol
  • Security and audit trails
  • Usage tracking and budgets
  • System configuration

​
Communication Protocols

​
REST API

All endpoints follow RESTful conventions:
  • GET for retrieval operations
  • POST for creation operations
  • PUT for full updates
  • PATCH for partial updates
  • DELETE for removal operations
All request and response bodies use JSON format unless otherwise specified.

​
WebSocket

Real-time bidirectional communication with agents: 
ws://127.0.0.1:4200/api/agents/{id}/ws
Supports streaming responses, live agent status updates, and chat commands.

​
Server-Sent Events (SSE)

Token-by-token streaming for long-running responses: 
POST /api/agents/{id}/message/stream
Returns an SSE stream with text_delta, tool_use, and done events.

​
Rate Limiting

OpenFang implements a GCRA (Generic Cell Rate Algorithm) cost-aware rate limiter with:
  • Per-IP token bucket tracking
  • Automatic stale entry cleanup
  • Cost-based limits (expensive operations consume more tokens)
  • Hourly reset window
When rate limited, responses return: 
HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": "Rate limit exceeded"
}

​
Security Headers

All API responses include comprehensive security headers:
  • Content-Security-Policy: Restricts resource loading
  • X-Frame-Options: DENY: Prevents clickjacking
  • X-Content-Type-Options: nosniff: Prevents MIME sniffing
  • Strict-Transport-Security: Forces HTTPS (when TLS enabled)
  • Referrer-Policy: no-referrer: Protects sensitive URLs

​
Error Responses

All errors follow a consistent JSON structure: 
{
  "error": "Human-readable error message"
}
Common HTTP status codes:
Status CodeMeaning
200 OKRequest succeeded
201 CreatedResource created successfully
400 Bad RequestInvalid request format or parameters
401 UnauthorizedMissing or invalid API key
403 ForbiddenValid auth but insufficient permissions
404 Not FoundResource does not exist
413 Payload Too LargeRequest body exceeds size limit
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorServer-side error

​
Public Endpoints

The following endpoints do not require authentication:
  • GET /api/health — Basic health check
  • GET / — WebChat UI
  • GET /logo.png — Logo image
  • GET /favicon.ico — Favicon
All other endpoints require authentication when an API key is configured.

​
Content Negotiation

All endpoints accept and return application/json unless otherwise specified: 
Content-Type: application/json
SSE endpoints return text/event-stream: 
Content-Type: text/event-stream

​
Versioning

The API is currently unversioned. Breaking changes will be communicated via:
  • Release notes
  • Migration guides
  • Deprecation warnings in responses
Future versions may introduce /v2/ prefixed endpoints.

​
Next Steps

Authentication

Learn how to authenticate API requests

Agents

Create and manage agent lifecycles

Workflows

Orchestrate multi-agent workflows

Memory

Store and retrieve agent memory

Build docs developers (and LLMs) love

Get started for freeTalk to us