API Reference

LibreFang exposes a REST API, WebSocket endpoints, and SSE streaming when the daemon is running. The default listen address is http://127.0.0.1:4545.

All responses include security headers (CSP, X-Frame-Options, X-Content-Type-Options, HSTS) and are protected by a GCRA cost-aware rate limiter with per-IP token bucket tracking and automatic stale entry cleanup. LibreFang implements 16 security systems including Merkle audit trails, taint tracking, WASM dual metering, Ed25519 manifest signing, SSRF protection, subprocess sandboxing, and secret zeroization.

Table of Contents

Agent & Workflow API

Agent Endpoints, Workflow Endpoints, Trigger Endpoints, Schedule Endpoints, Goals Endpoints, Cron Endpoints

System & Configuration API

Template Endpoints, System Endpoints, Config Management, Session Management, Task Queue, Backup & Restore, Migration, Bindings & Commands

Intelligence & Skills API

Memory Endpoints, Skills & Marketplace, ClawHub, Hands, Extensions, Plugins, Media Generation

Provider & Model API

Model Catalog, Provider Configuration

Communication & Network API

Channel Endpoints, MCP & A2A Protocol, Audit & Security, Usage & Analytics, Budget, Webhooks, Integrations, Pairing, OAuth/OIDC, Comms, Approvals, Network & Peers

Real-time API

WebSocket Protocol, SSE Streaming, OpenAI-Compatible API

• Authentication
• Error Responses
• Endpoint Summary

Authentication

When an API key is configured in config.toml, all endpoints (except /api/health and /) require a Bearer token:

Authorization: Bearer <your-api-key>

Setting the API Key

Add to ~/.librefang/config.toml:

api_key = "your-secret-api-key"

No Authentication

If api_key is empty or not set, the API is accessible without authentication. CORS is restricted to localhost origins in this mode.

Public Endpoints (No Auth Required)

• GET /api/health
• GET / (WebChat UI)

Error Responses

All error responses use a consistent JSON format:

{
  "error": "Description of what went wrong"
}

HTTP Status Codes

Request IDs

Every response includes an x-request-id header with a UUID for tracing:

x-request-id: 550e8400-e29b-41d4-a716-446655440000

Use this value when reporting issues or correlating requests in logs.

Security Headers

Every response includes security headers:

Rate Limiting

The GCRA (Generic Cell Rate Algorithm) rate limiter provides cost-aware token bucket rate limiting with per-IP tracking and automatic stale entry cleanup. Different endpoints consume different token costs (e.g., /api/agents/{id}/message costs more than /api/health). When the limit is exceeded, the server returns 429 Too Many Requests:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{"error": "Rate limit exceeded"}

The Retry-After header indicates the window duration in seconds.

Endpoint Summary

230+ endpoints total across 35 groups.