Skip to main content

​
Base URL

The OpenFang API runs on your local machine by default: 
http://127.0.0.1:4200
The base URL can be configured via the api_listen setting in ~/.openfang/config.toml.

​
API Architecture

OpenFang exposes a RESTful HTTP API for managing agents, workflows, memory, and system configuration. The API is built with:
  • Axum web framework
  • JSON request/response format
  • Server-Sent Events (SSE) for streaming responses
  • WebSocket for real-time agent communication

​
Core Resources

Agents

Spawn, manage, and communicate with AI agents

Memory

Semantic memory, knowledge graphs, and key-value storage

Workflows

Multi-agent pipelines and orchestration

Models

Model catalog, providers, and cost tracking

Channels

Connect to Telegram, Discord, Slack, and 40+ platforms

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeDescription
200Success
201Created (resource spawned)
400Bad Request (invalid input)
401Unauthorized (invalid API key)
403Forbidden (signature verification failed)
404Not Found (agent/resource doesn’t exist)
413Payload Too Large (message/manifest exceeds limit)
429Too Many Requests (rate limit exceeded or quota reached)
500Internal Server Error

​
Rate Limiting

The API implements GCRA (Generic Cell Rate Algorithm) rate limiting:
  • Default limit: 30 requests per second per IP
  • Response headers: X-RateLimit-Remaining, X-RateLimit-Reset
  • Status: Returns 429 Too Many Requests when exceeded

​
CORS

When no API key is configured, CORS is restricted to localhost origins:
  • http://127.0.0.1:<port>
  • http://localhost:<port>
  • Common dev ports: 3000, 8080
With an API key configured, CORS allows the configured origins plus localhost.

​
Health Check

curl http://127.0.0.1:4200/api/health

{
  "status": "healthy"
}

​
Version Info

curl http://127.0.0.1:4200/api/version

{
  "name": "openfang",
  "version": "0.1.0",
  "build_date": "2025-03-06",
  "git_sha": "a1b2c3d",
  "rust_version": "1.83.0",
  "platform": "linux",
  "arch": "x86_64"
}

​
System Status

Get comprehensive kernel status including agents, uptime, and configuration: 
curl http://127.0.0.1:4200/api/status

{
  "status": "running",
  "agent_count": 3,
  "default_provider": "anthropic",
  "default_model": "claude-sonnet-4-20250514",
  "uptime_seconds": 86400,
  "api_listen": "127.0.0.1:4200",
  "home_dir": "/home/user/.openfang",
  "log_level": "info",
  "network_enabled": false,
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "assistant",
      "state": "Running",
      "mode": "Auto",
      "created_at": "2025-03-06T12:00:00Z",
      "model_provider": "anthropic",
      "model_name": "claude-sonnet-4-20250514",
      "profile": "Full"
    }
  ]
}

​
Next Steps

Authentication

Secure your API with Bearer tokens

Agents

Start spawning and managing agents