LibreFang
中文

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

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)

Agent Endpoints

GET /api/agents

List all running agents.

Response 200 OK:

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "hello-world",
    "state": "Running",
    "created_at": "2025-01-15T10:30:00Z",
    "model_provider": "groq",
    "model_name": "llama-3.3-70b-versatile"
  }
]

GET /api/agents/{id}

Returns detailed information about a single agent.

Response 200 OK:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "hello-world",
  "state": "Running",
  "created_at": "2025-01-15T10:30:00Z",
  "session_id": "s1b2c3d4-...",
  "model": {
    "provider": "groq",
    "model": "llama-3.3-70b-versatile"
  },
  "capabilities": {
    "tools": ["file_read", "file_list", "web_fetch"],
    "network": []
  },
  "description": "A friendly greeting agent",
  "tags": []
}

POST /api/agents

Spawn a new agent from a TOML manifest.

Request Body (JSON):

{
  "manifest_toml": "name = \"my-agent\"\nversion = \"0.1.0\"\ndescription = \"Test agent\"\nauthor = \"me\"\nmodule = \"builtin:chat\"\n\n[model]\nprovider = \"groq\"\nmodel = \"llama-3.3-70b-versatile\"\n\n[capabilities]\ntools = [\"file_read\", \"web_fetch\"]\nmemory_read = [\"*\"]\nmemory_write = [\"self.*\"]\n"
}

Response 201 Created:

{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "my-agent"
}

PUT /api/agents/{id}/update

Update an agent's configuration at runtime.

Request Body:

{
  "description": "Updated description",
  "system_prompt": "You are a specialized assistant.",
  "tags": ["updated", "v2"]
}

Response 200 OK:

{
  "status": "updated",
  "agent_id": "a1b2c3d4-..."
}

PUT /api/agents/{id}/mode

Set an agent's operating mode. Stable mode pins the current model and freezes the skill registry. Normal mode restores default behavior.

Request Body:

{
  "mode": "Stable"
}

Response 200 OK:

{
  "status": "updated",
  "mode": "Stable",
  "agent_id": "a1b2c3d4-..."
}

POST /api/agents/{id}/message

Send a message to an agent and receive the complete response.

Request Body:

{
  "message": "What files are in the current directory?"
}

Response 200 OK:

{
  "response": "Here are the files in the current directory:\n- Cargo.toml\n- README.md\n...",
  "input_tokens": 142,
  "output_tokens": 87,
  "iterations": 1
}

GET /api/agents/{id}/session

Returns the agent's conversation history.

Response 200 OK:

{
  "session_id": "s1b2c3d4-...",
  "agent_id": "a1b2c3d4-...",
  "message_count": 4,
  "context_window_tokens": 1250,
  "messages": [
    {
      "role": "User",
      "content": "Hello"
    },
    {
      "role": "Assistant",
      "content": "Hello! How can I help you?"
    }
  ]
}

DELETE /api/agents/{id}

Terminate an agent and remove it from the registry.

Response 200 OK:

{
  "status": "killed",
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Workflow Endpoints

GET /api/workflows

List all registered workflows.

Response 200 OK:

[
  {
    "id": "w1b2c3d4-...",
    "name": "code-review-pipeline",
    "description": "Automated code review workflow",
    "steps": 3,
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST /api/workflows

Create a new workflow definition.

Request Body (JSON):

{
  "name": "code-review-pipeline",
  "description": "Review code changes with multiple agents",
  "steps": [
    {
      "name": "analyze",
      "agent_name": "coder",
      "prompt": "Analyze this code for potential issues: {&lbrace;input&rbrace;}",
      "mode": "sequential",
      "timeout_secs": 120,
      "error_mode": "fail",
      "output_var": "analysis"
    },
    {
      "name": "security-check",
      "agent_name": "security-auditor",
      "prompt": "Review this code analysis for security vulnerabilities: {&lbrace;analysis&rbrace;}",
      "mode": "sequential",
      "timeout_secs": 120,
      "error_mode": "skip"
    },
    {
      "name": "summarize",
      "agent_name": "writer",
      "prompt": "Write a concise code review summary based on: {&lbrace;analysis&rbrace;}",
      "mode": "sequential",
      "timeout_secs": 60,
      "error_mode": "fail"
    }
  ]
}

Step configuration options:

FieldTypeDescription
namestringStep name
agent_idstringAgent UUID (use either this or agent_name)
agent_namestringAgent name (use either this or agent_id)
promptstringPrompt template with {&lbrace;input&rbrace;} and {&lbrace;output_var&rbrace;} placeholders
modestring"sequential", "fan_out", "collect", "conditional", "loop"
timeout_secsintegerTimeout per step (default: 120)
error_modestring"fail", "skip", "retry"
max_retriesintegerFor "retry" error mode (default: 3)
output_varstringVariable name to store output for later steps
conditionstringFor "conditional" mode
max_iterationsintegerFor "loop" mode (default: 5)
untilstringFor "loop" mode: stop condition

Response 201 Created:

{
  "workflow_id": "w1b2c3d4-..."
}

POST /api/workflows/{id}/run

Execute a workflow.

Request Body:

{
  "input": "Review this pull request: ..."
}

Response 200 OK:

{
  "run_id": "r1b2c3d4-...",
  "output": "Code review summary:\n- No critical issues found\n...",
  "status": "completed"
}

GET /api/workflows/{id}/runs

List execution history for a workflow.

Response 200 OK:

[
  {
    "id": "r1b2c3d4-...",
    "workflow_name": "code-review-pipeline",
    "state": "Completed",
    "steps_completed": 3,
    "started_at": "2025-01-15T10:30:00Z",
    "completed_at": "2025-01-15T10:32:15Z"
  }
]

Trigger Endpoints

GET /api/triggers

List all triggers. Optionally filter by agent.

Query Parameters:

  • agent_id (optional): Filter by agent UUID

Response 200 OK:

[
  {
    "id": "t1b2c3d4-...",
    "agent_id": "a1b2c3d4-...",
    "pattern": {"lifecycle": {}},
    "prompt_template": "Event: {&lbrace;event&rbrace;}",
    "enabled": true,
    "fire_count": 5,
    "max_fires": 0,
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST /api/triggers

Create a new event trigger.

Request Body:

{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "pattern": {
    "agent_spawned": {
      "name_pattern": "*"
    }
  },
  "prompt_template": "A new agent was spawned: {&lbrace;event&rbrace;}. Review its capabilities.",
  "max_fires": 0
}

Supported pattern types:

PatternDescription
{"lifecycle": {}}All lifecycle events
{"agent_spawned": {"name_pattern": "*"}}Agent spawn events
{"agent_terminated": {}}Agent termination events
{"all": {}}All events

Response 201 Created:

{
  "trigger_id": "t1b2c3d4-...",
  "agent_id": "a1b2c3d4-..."
}

PUT /api/triggers/{id}

Update an existing trigger's configuration.

Request Body:

{
  "prompt_template": "Updated template: {&lbrace;event&rbrace;}",
  "enabled": false,
  "max_fires": 10
}

Response 200 OK:

{
  "status": "updated",
  "trigger_id": "t1b2c3d4-..."
}

DELETE /api/triggers/{id}

Remove a trigger.

Response 200 OK:

{
  "status": "removed",
  "trigger_id": "t1b2c3d4-..."
}

Memory Endpoints

GET /api/memory/agents/{id}/kv

List all key-value pairs for an agent.

Response 200 OK:

{
  "kv_pairs": [
    {"key": "preferences", "value": {"theme": "dark"}},
    {"key": "state", "value": {"step": 3}}
  ]
}

GET /api/memory/agents/{id}/kv/{key}

Get a specific key-value pair.

Response 200 OK:

{
  "key": "preferences",
  "value": {"theme": "dark"}
}

Response 404 Not Found (key does not exist):

{
  "error": "Key 'preferences' not found"
}

PUT /api/memory/agents/{id}/kv/{key}

Set a key-value pair. Creates or overwrites.

Request Body:

{
  "value": {"theme": "dark", "language": "en"}
}

Response 200 OK:

{
  "status": "stored",
  "key": "preferences"
}

DELETE /api/memory/agents/{id}/kv/{key}

Delete a key-value pair.

Response 200 OK:

{
  "status": "deleted",
  "key": "preferences"
}

Channel Endpoints

GET /api/channels

List configured channel adapters and their status. Supports 40 channel adapters including Telegram, Discord, Slack, WhatsApp, Matrix, Email, Teams, Mattermost, IRC, Google Chat, Twitch, Rocket.Chat, Zulip, XMPP, LINE, Viber, Messenger, Reddit, Mastodon, Bluesky, and more.

Response 200 OK:

{
  "channels": [
    {
      "name": "telegram",
      "enabled": true,
      "has_token": true
    },
    {
      "name": "discord",
      "enabled": true,
      "has_token": false
    }
  ],
  "total": 2
}

Template Endpoints

GET /api/templates

List available agent templates from the agents directory.

Response 200 OK:

{
  "templates": [
    {
      "name": "hello-world",
      "description": "A friendly greeting agent",
      "path": "/home/user/.librefang/agents/hello-world/agent.toml"
    },
    {
      "name": "coder",
      "description": "Expert coding assistant",
      "path": "/home/user/.librefang/agents/coder/agent.toml"
    }
  ],
  "total": 30
}

GET /api/templates/{name}

Get a specific template's manifest and raw TOML.

Response 200 OK:

{
  "name": "hello-world",
  "manifest": {
    "name": "hello-world",
    "description": "A friendly greeting agent",
    "module": "builtin:chat",
    "tags": [],
    "model": {
      "provider": "groq",
      "model": "llama-3.3-70b-versatile"
    },
    "capabilities": {
      "tools": ["file_read", "file_list", "web_fetch"],
      "network": []
    }
  },
  "manifest_toml": "name = \"hello-world\"\nversion = \"0.1.0\"\n..."
}

Hands Endpoints

Hands are autonomous background capabilities (e.g., browser automation, code execution) that run alongside agents. Each hand has a definition, requirements, and can be activated as instances.

GET /api/hands

List all available hand definitions with their requirements status.

Response 200 OK:

{
  "hands": [
    {
      "id": "browser",
      "name": "Browser Automation",
      "description": "Headless browser for web scraping and testing",
      "category": "automation",
      "icon": "globe",
      "tools": ["browser_navigate", "browser_click"],
      "requirements_met": true,
      "active": false,
      "degraded": false,
      "requirements": [
        {"key": "playwright", "label": "Playwright", "satisfied": true, "optional": false}
      ],
      "has_settings": true,
      "settings_count": 3
    }
  ],
  "total": 5
}

Example:

curl -s http://127.0.0.1:4545/api/hands

GET /api/hands/active

List currently active hand instances.

Response 200 OK:

{
  "instances": [
    {
      "instance_id": "inst-1234",
      "hand_id": "browser",
      "status": "running",
      "agent_id": "a1b2c3d4-...",
      "agent_name": "web-scraper",
      "activated_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:35:00Z"
    }
  ],
  "total": 1
}

Example:

curl -s http://127.0.0.1:4545/api/hands/active

GET /api/hands/{hand_id}

Get detailed information about a specific hand definition including requirements and settings.

Response 200 OK:

{
  "id": "browser",
  "name": "Browser Automation",
  "description": "Headless browser for web scraping and testing",
  "category": "automation",
  "icon": "globe",
  "tools": ["browser_navigate", "browser_click"],
  "requirements_met": true,
  "active": false,
  "requirements": [
    {
      "key": "playwright",
      "label": "Playwright",
      "type": "Binary",
      "satisfied": true,
      "optional": false,
      "install": {"command": "npx playwright install"}
    }
  ],
  "agent": {"name": "browser-agent", "provider": "groq", "model": "llama-3.3-70b-versatile"},
  "dashboard": [],
  "settings": []
}

Example:

curl -s http://127.0.0.1:4545/api/hands/browser

POST /api/hands/install

Install a hand from a definition path or URL.

Request Body:

{
  "source": "/path/to/hand"
}

Response 201 Created:

{
  "status": "installed",
  "hand_id": "custom-hand"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/hands/install \
  -H "Content-Type: application/json" \
  -d '{"source": "/path/to/hand"}'

POST /api/hands/{hand_id}/activate

Activate a hand, creating a running instance with its associated agent.

Response 200 OK:

{
  "status": "activated",
  "instance_id": "inst-5678",
  "hand_id": "browser"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/hands/browser/activate

POST /api/hands/{hand_id}/check-deps

Re-check dependency status for a hand.

Response 200 OK:

{
  "hand_id": "browser",
  "requirements": [
    {"key": "playwright", "label": "Playwright", "satisfied": true}
  ],
  "all_met": true
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/hands/browser/check-deps

POST /api/hands/{hand_id}/install-deps

Install missing dependencies for a hand.

Response 200 OK:

{
  "status": "ok",
  "installed": ["playwright"]
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/hands/browser/install-deps

GET /api/hands/{hand_id}/settings

Get the current settings for a hand.

Response 200 OK:

{
  "hand_id": "browser",
  "settings": [
    {"key": "headless", "value": true, "type": "boolean"},
    {"key": "timeout_ms", "value": 30000, "type": "integer"}
  ]
}

Example:

curl -s http://127.0.0.1:4545/api/hands/browser/settings

PUT /api/hands/{hand_id}/settings

Update settings for a hand.

Request Body:

{
  "headless": false,
  "timeout_ms": 60000
}

Response 200 OK:

{
  "status": "ok",
  "hand_id": "browser"
}

Example:

curl -s -X PUT http://127.0.0.1:4545/api/hands/browser/settings \
  -H "Content-Type: application/json" \
  -d '{"headless": false}'

POST /api/hands/instances/{id}/pause

Pause a running hand instance.

Response 200 OK:

{
  "status": "paused",
  "instance_id": "inst-1234"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/hands/instances/inst-1234/pause

POST /api/hands/instances/{id}/resume

Resume a paused hand instance.

Response 200 OK:

{
  "status": "resumed",
  "instance_id": "inst-1234"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/hands/instances/inst-1234/resume

DELETE /api/hands/instances/{id}

Deactivate and remove a hand instance.

Response 200 OK:

{
  "status": "deactivated",
  "instance_id": "inst-1234"
}

Example:

curl -s -X DELETE http://127.0.0.1:4545/api/hands/instances/inst-1234

GET /api/hands/instances/{id}/stats

Get runtime statistics for a hand instance.

Response 200 OK:

{
  "instance_id": "inst-1234",
  "hand_id": "browser",
  "uptime_seconds": 3600,
  "tasks_completed": 42,
  "errors": 0
}

Example:

curl -s http://127.0.0.1:4545/api/hands/instances/inst-1234/stats

GET /api/hands/instances/{id}/browser

Get the browser state for a browser hand instance (live DOM snapshot, URL, etc.).

Response 200 OK:

{
  "instance_id": "inst-1234",
  "url": "https://example.com",
  "title": "Example Domain",
  "screenshot_base64": "iVBOR..."
}

Example:

curl -s http://127.0.0.1:4545/api/hands/instances/inst-1234/browser

Schedule Endpoints

Manage cron-based scheduled jobs that trigger agent actions on a time schedule.

GET /api/schedules

List all scheduled jobs.

Response 200 OK:

{
  "schedules": [
    {
      "id": "sched-1234",
      "name": "daily-report",
      "cron": "0 9 * * *",
      "agent_id": "a1b2c3d4-...",
      "prompt": "Generate the daily status report",
      "enabled": true,
      "last_run": "2025-01-15T09:00:00Z",
      "next_run": "2025-01-16T09:00:00Z"
    }
  ],
  "total": 1
}

Example:

curl -s http://127.0.0.1:4545/api/schedules

POST /api/schedules

Create a new scheduled job.

Request Body:

{
  "name": "daily-report",
  "cron": "0 9 * * *",
  "agent_id": "a1b2c3d4-...",
  "prompt": "Generate the daily status report",
  "enabled": true
}

Response 201 Created:

{
  "id": "sched-1234",
  "status": "created"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/schedules \
  -H "Content-Type: application/json" \
  -d '{"name": "daily-report", "cron": "0 9 * * *", "agent_id": "AGENT_ID", "prompt": "Generate report"}'

PUT /api/schedules/{id}

Update an existing scheduled job.

Request Body:

{
  "cron": "0 8 * * *",
  "prompt": "Updated prompt",
  "enabled": false
}

Response 200 OK:

{
  "status": "updated",
  "id": "sched-1234"
}

Example:

curl -s -X PUT http://127.0.0.1:4545/api/schedules/sched-1234 \
  -H "Content-Type: application/json" \
  -d '{"cron": "0 8 * * *"}'

DELETE /api/schedules/{id}

Delete a scheduled job.

Response 200 OK:

{
  "status": "deleted",
  "id": "sched-1234"
}

Example:

curl -s -X DELETE http://127.0.0.1:4545/api/schedules/sched-1234

POST /api/schedules/{id}/run

Manually trigger an immediate run of a scheduled job.

Response 200 OK:

{
  "status": "triggered",
  "id": "sched-1234",
  "response": "Daily report generated..."
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/schedules/sched-1234/run

Cron Job Endpoints

Lower-level cron job management tied to specific agents.

GET /api/cron/jobs

List all cron jobs, optionally filtered by agent.

Query Parameters:

  • agent_id (optional): Filter by agent UUID

Response 200 OK:

{
  "jobs": [
    {
      "id": "job-5678",
      "agent_id": "a1b2c3d4-...",
      "cron_expr": "*/30 * * * *",
      "prompt": "Check system health",
      "enabled": true,
      "last_run": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Example:

curl -s http://127.0.0.1:4545/api/cron/jobs
curl -s "http://127.0.0.1:4545/api/cron/jobs?agent_id=AGENT_ID"

POST /api/cron/jobs

Create a new cron job.

Request Body:

{
  "agent_id": "a1b2c3d4-...",
  "cron_expr": "*/30 * * * *",
  "prompt": "Check system health"
}

Response 201 Created:

{
  "id": "job-5678",
  "status": "created"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/cron/jobs \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_ID", "cron_expr": "0 * * * *", "prompt": "Hourly check"}'

DELETE /api/cron/jobs/{id}

Delete a cron job.

Response 200 OK:

{
  "status": "deleted",
  "id": "job-5678"
}

Example:

curl -s -X DELETE http://127.0.0.1:4545/api/cron/jobs/job-5678

PUT /api/cron/jobs/{id}/enable

Enable or disable a cron job.

Request Body:

{
  "enabled": false
}

Response 200 OK:

{
  "status": "ok",
  "id": "job-5678",
  "enabled": false
}

Example:

curl -s -X PUT http://127.0.0.1:4545/api/cron/jobs/job-5678/enable \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

GET /api/cron/jobs/{id}/status

Get the current status of a cron job.

Response 200 OK:

{
  "id": "job-5678",
  "enabled": true,
  "last_run": "2025-01-15T10:30:00Z",
  "next_run": "2025-01-15T11:00:00Z",
  "run_count": 42,
  "last_error": null
}

Example:

curl -s http://127.0.0.1:4545/api/cron/jobs/job-5678/status

Budget Endpoints

Track and control spending across agents with hourly, daily, and monthly budget limits.

GET /api/budget

Get global budget status including spend vs. limits.

Response 200 OK:

{
  "hourly": {"spend": 0.05, "limit": 1.0, "pct": 0.05},
  "daily": {"spend": 0.42, "limit": 10.0, "pct": 0.042},
  "monthly": {"spend": 8.50, "limit": 100.0, "pct": 0.085},
  "alert_threshold": 0.8
}

Example:

curl -s http://127.0.0.1:4545/api/budget

PUT /api/budget

Update global budget limits (in-memory, not persisted to config.toml).

Request Body:

{
  "max_hourly_usd": 2.0,
  "max_daily_usd": 20.0,
  "max_monthly_usd": 200.0,
  "alert_threshold": 0.9,
  "default_max_llm_tokens_per_hour": 500000
}

All fields are optional.

Response 200 OK: Returns updated budget status (same format as GET).

Example:

curl -s -X PUT http://127.0.0.1:4545/api/budget \
  -H "Content-Type: application/json" \
  -d '{"max_daily_usd": 25.0}'

GET /api/budget/agents

Get per-agent cost ranking (top spenders).

Response 200 OK:

{
  "agents": [
    {
      "agent_id": "a1b2c3d4-...",
      "name": "coder",
      "daily_cost_usd": 0.35,
      "hourly_limit": 0.5,
      "daily_limit": 5.0,
      "monthly_limit": 50.0,
      "max_llm_tokens_per_hour": 100000
    }
  ],
  "total": 2
}

Example:

curl -s http://127.0.0.1:4545/api/budget/agents

GET /api/budget/agents/{id}

Get detailed budget and quota status for a specific agent.

Response 200 OK:

{
  "agent_id": "a1b2c3d4-...",
  "agent_name": "coder",
  "hourly": {"spend": 0.02, "limit": 0.5, "pct": 0.04},
  "daily": {"spend": 0.35, "limit": 5.0, "pct": 0.07},
  "monthly": {"spend": 4.20, "limit": 50.0, "pct": 0.084},
  "tokens": {"used": 45000, "limit": 100000, "pct": 0.45}
}

Example:

curl -s http://127.0.0.1:4545/api/budget/agents/AGENT_ID

PUT /api/budget/agents/{id}

Update per-agent budget limits at runtime.

Request Body:

{
  "max_cost_per_hour_usd": 1.0,
  "max_cost_per_day_usd": 10.0,
  "max_cost_per_month_usd": 100.0,
  "max_llm_tokens_per_hour": 200000
}

At least one field must be provided.

Response 200 OK:

{
  "status": "ok",
  "message": "Agent budget updated"
}

Example:

curl -s -X PUT http://127.0.0.1:4545/api/budget/agents/AGENT_ID \
  -H "Content-Type: application/json" \
  -d '{"max_cost_per_day_usd": 10.0}'

Integration Endpoints

Manage external service integrations (MCP-based). Integrations provide tools from third-party services like GitHub, Jira, Notion, etc.

GET /api/integrations

List installed integrations with their status.

Response 200 OK:

{
  "installed": [
    {
      "id": "github",
      "name": "GitHub",
      "icon": "octocat",
      "category": "development",
      "status": "ready",
      "tool_count": 12,
      "installed_at": "2025-01-10T08:00:00Z"
    }
  ],
  "count": 1
}

Example:

curl -s http://127.0.0.1:4545/api/integrations

GET /api/integrations/available

List all available integration templates (both installed and not-yet-installed).

Response 200 OK:

{
  "integrations": [
    {
      "id": "github",
      "name": "GitHub",
      "description": "GitHub API integration",
      "icon": "octocat",
      "category": "development",
      "installed": true,
      "tags": ["vcs", "issues", "pr"],
      "required_env": [
        {"name": "GITHUB_TOKEN", "label": "GitHub Token", "is_secret": true, "get_url": "https://github.com/settings/tokens"}
      ],
      "has_oauth": false,
      "setup_instructions": "Create a personal access token..."
    }
  ],
  "count": 15
}

Example:

curl -s http://127.0.0.1:4545/api/integrations/available

POST /api/integrations/add

Install an integration by ID.

Request Body:

{
  "id": "github"
}

Response 201 Created:

{
  "id": "github",
  "status": "installed",
  "connected": true,
  "message": "Integration 'github' installed"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/integrations/add \
  -H "Content-Type: application/json" \
  -d '{"id": "github"}'

DELETE /api/integrations/{id}

Remove an installed integration.

Response 200 OK:

{
  "id": "github",
  "status": "removed"
}

Example:

curl -s -X DELETE http://127.0.0.1:4545/api/integrations/github

POST /api/integrations/{id}/reconnect

Reconnect an integration's MCP server.

Response 200 OK:

{
  "id": "github",
  "status": "connected",
  "tool_count": 12
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/integrations/github/reconnect

GET /api/integrations/health

Get health status for all installed integrations.

Response 200 OK:

{
  "health": [
    {
      "id": "github",
      "status": "Ready",
      "tool_count": 12,
      "last_ok": "2025-01-15T10:30:00Z",
      "last_error": null,
      "consecutive_failures": 0,
      "reconnecting": false
    }
  ],
  "count": 1
}

Example:

curl -s http://127.0.0.1:4545/api/integrations/health

POST /api/integrations/reload

Hot-reload integration configs and reconnect all MCP servers.

Response 200 OK:

{
  "status": "reloaded",
  "new_connections": 2
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/integrations/reload

Comms & Network Endpoints

Inter-agent communication topology, event bus, and peer networking.

GET /api/comms/topology

Get the agent communication topology graph (nodes and edges).

Response 200 OK:

{
  "nodes": [
    {"id": "a1b2c3d4-...", "name": "coder", "state": "Running", "model": "llama-3.3-70b-versatile"}
  ],
  "edges": [
    {"from": "a1b2c3d4-...", "to": "e5f6a7b8-...", "kind": "ParentChild"}
  ]
}

Example:

curl -s http://127.0.0.1:4545/api/comms/topology

GET /api/comms/events

Get recent inter-agent communication events.

Query Parameters:

  • limit (optional): Number of events (default: 100)

Response 200 OK:

{
  "events": [
    {
      "id": "evt-1234",
      "timestamp": "2025-01-15T10:30:00Z",
      "kind": "AgentMessage",
      "source_id": "a1b2c3d4-...",
      "source_name": "coder",
      "target_id": "e5f6a7b8-...",
      "target_name": "reviewer",
      "detail": "Review this code..."
    }
  ],
  "total": 42
}

Example:

curl -s http://127.0.0.1:4545/api/comms/events

GET /api/comms/events/stream

SSE stream of real-time inter-agent communication events.

Response: Server-Sent Events stream.

event: comms
data: {"id":"evt-1234","kind":"AgentMessage","source_name":"coder","target_name":"reviewer","detail":"..."}

Example:

curl -s -N http://127.0.0.1:4545/api/comms/events/stream

POST /api/comms/send

Send a message from one agent to another.

Request Body:

{
  "from": "a1b2c3d4-...",
  "to": "e5f6a7b8-...",
  "message": "Please review this code"
}

Response 200 OK:

{
  "status": "sent",
  "event_id": "evt-5678"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/comms/send \
  -H "Content-Type: application/json" \
  -d '{"from": "AGENT1_ID", "to": "AGENT2_ID", "message": "Hello"}'

POST /api/comms/task

Delegate a task from one agent to another.

Request Body:

{
  "from": "a1b2c3d4-...",
  "to": "e5f6a7b8-...",
  "prompt": "Analyze this data and return findings"
}

Response 200 OK:

{
  "status": "completed",
  "response": "Analysis results...",
  "usage": {"input_tokens": 150, "output_tokens": 200}
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/comms/task \
  -H "Content-Type: application/json" \
  -d '{"from": "AGENT1_ID", "to": "AGENT2_ID", "prompt": "Summarize the data"}'

GET /api/network/status

Get OFP (LibreFang Protocol) network status.

Response 200 OK:

{
  "network_enabled": true,
  "peer_count": 3,
  "node_id": "node-abc123",
  "listen_addr": "0.0.0.0:4000"
}

Example:

curl -s http://127.0.0.1:4545/api/network/status

Approval Endpoints

Human-in-the-loop approval gates for high-risk tool invocations.

GET /api/approvals

List all pending approval requests.

Response 200 OK:

{
  "approvals": [
    {
      "id": "appr-1234",
      "agent_id": "a1b2c3d4-...",
      "agent_name": "coder",
      "tool_name": "shell_exec",
      "description": "Execute: rm -rf /tmp/old-files",
      "action_summary": "shell_exec",
      "risk_level": "High",
      "requested_at": "2025-01-15T10:30:00Z",
      "timeout_secs": 300,
      "status": "pending"
    }
  ],
  "total": 1
}

Example:

curl -s http://127.0.0.1:4545/api/approvals

POST /api/approvals

Create a manual approval request (for external integrations).

Request Body:

{
  "agent_id": "a1b2c3d4-...",
  "tool_name": "deploy",
  "description": "Deploy to production",
  "action_summary": "Production deployment"
}

Response 201 Created:

{
  "id": "appr-5678",
  "status": "pending"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/approvals \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_ID", "tool_name": "deploy", "description": "Deploy to prod"}'

POST /api/approvals/{id}/approve

Approve a pending request.

Response 200 OK:

{
  "id": "appr-1234",
  "status": "approved",
  "decided_at": "2025-01-15T10:31:00Z"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/approvals/appr-1234/approve

POST /api/approvals/{id}/reject

Reject a pending request.

Response 200 OK:

{
  "id": "appr-1234",
  "status": "rejected",
  "decided_at": "2025-01-15T10:31:00Z"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/approvals/appr-1234/reject

Device Pairing Endpoints

Pair mobile devices and external clients with the LibreFang daemon for push notifications and remote control.

POST /api/pairing/request

Create a new pairing request. Returns a token and QR URI for device scanning.

Response 200 OK:

{
  "token": "pair-abc123def456",
  "qr_uri": "librefang://pair?token=pair-abc123def456",
  "expires_at": "2025-01-15T10:35:00Z"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/pairing/request

POST /api/pairing/complete

Complete a pairing with the token and device information.

Request Body:

{
  "token": "pair-abc123def456",
  "display_name": "My iPhone",
  "platform": "ios",
  "push_token": "apns-token-here"
}

Response 200 OK:

{
  "device_id": "dev-1234",
  "display_name": "My iPhone",
  "platform": "ios",
  "paired_at": "2025-01-15T10:31:00Z"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/pairing/complete \
  -H "Content-Type: application/json" \
  -d '{"token": "pair-abc123", "display_name": "My Phone", "platform": "android"}'

GET /api/pairing/devices

List all paired devices.

Response 200 OK:

{
  "devices": [
    {
      "device_id": "dev-1234",
      "display_name": "My iPhone",
      "platform": "ios",
      "paired_at": "2025-01-15T10:31:00Z",
      "last_seen": "2025-01-15T10:35:00Z"
    }
  ]
}

Example:

curl -s http://127.0.0.1:4545/api/pairing/devices

DELETE /api/pairing/devices/{id}

Remove a paired device.

Response 200 OK:

{
  "ok": true
}

Example:

curl -s -X DELETE http://127.0.0.1:4545/api/pairing/devices/dev-1234

POST /api/pairing/notify

Push a notification to all paired devices.

Request Body:

{
  "title": "LibreFang Alert",
  "message": "Agent 'coder' completed the code review"
}

Response 200 OK:

{
  "ok": true,
  "notified": 2
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/pairing/notify \
  -H "Content-Type: application/json" \
  -d '{"title": "Alert", "message": "Task completed"}'

Config Management Endpoints

Read, modify, and reload the daemon configuration at runtime.

GET /api/config/schema

Get a JSON description of the configuration structure with field types and defaults.

Response 200 OK:

{
  "sections": [
    {
      "name": "default_model",
      "fields": [
        {"key": "provider", "type": "string", "default": "groq"},
        {"key": "model", "type": "string", "default": "llama-3.3-70b-versatile"}
      ]
    },
    {
      "name": "budget",
      "fields": [
        {"key": "max_daily_usd", "type": "float", "default": 10.0}
      ]
    }
  ]
}

Example:

curl -s http://127.0.0.1:4545/api/config/schema

POST /api/config/set

Set a configuration value by dotted path. Writes to config.toml and triggers a hot-reload.

Request Body:

{
  "path": "budget.max_daily_usd",
  "value": 25.0
}

Supports up to 3-level paths (e.g., section.subsection.key).

Response 200 OK:

{
  "status": "applied",
  "path": "budget.max_daily_usd"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/config/set \
  -H "Content-Type: application/json" \
  -d '{"path": "default_model.provider", "value": "anthropic"}'

POST /api/config/reload

Reload configuration from disk and apply hot-reloadable changes.

Response 200 OK:

{
  "status": "applied",
  "restart_required": false,
  "restart_reasons": [],
  "hot_actions_applied": ["ApprovalPolicy", "BudgetLimits"],
  "noop_changes": []
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/config/reload

Catalog Endpoints

Manage the external model catalog sync.

POST /api/catalog/update

Trigger an update of the model catalog from the upstream source.

Response 200 OK:

{
  "status": "updated",
  "models_added": 3,
  "models_updated": 1
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/catalog/update

GET /api/catalog/status

Get the current catalog sync status.

Response 200 OK:

{
  "last_sync": "2025-01-15T08:00:00Z",
  "source": "built-in",
  "model_count": 51
}

Example:

curl -s http://127.0.0.1:4545/api/catalog/status

Binding Endpoints

Agent bindings map channels or triggers to specific agents.

GET /api/bindings

List all agent bindings.

Response 200 OK:

{
  "bindings": [
    {
      "agent": "coder",
      "channel": "telegram",
      "filter": "*"
    }
  ]
}

Example:

curl -s http://127.0.0.1:4545/api/bindings

POST /api/bindings

Add a new agent binding.

Request Body:

{
  "agent": "coder",
  "channel": "telegram",
  "filter": "*"
}

Response 201 Created:

{
  "status": "created"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/bindings \
  -H "Content-Type: application/json" \
  -d '{"agent": "coder", "channel": "telegram"}'

DELETE /api/bindings/{index}

Remove a binding by index.

Response 200 OK:

{
  "status": "removed"
}

Example:

curl -s -X DELETE http://127.0.0.1:4545/api/bindings/0

Webhook Endpoints

External event injection via authenticated webhooks.

POST /hooks/wake

Inject a wake event through the full event processing pipeline. Requires a bearer token configured via the LIBREFANG_WEBHOOK_TOKEN environment variable (min 32 chars).

Headers: Authorization: Bearer <webhook-token>

Request Body:

{
  "mode": "event",
  "text": "New deployment completed for service-x"
}

Response 200 OK:

{
  "status": "accepted",
  "mode": "event"
}

Example:

curl -s -X POST http://127.0.0.1:4545/hooks/wake \
  -H "Authorization: Bearer $WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "event", "text": "Deploy complete"}'

POST /hooks/agent

Send a message to a specific agent via webhook and get the response. Useful for CI/CD, Slack bots, and other external integrations.

Headers: Authorization: Bearer <webhook-token>

Request Body:

{
  "agent": "coder",
  "message": "Review the latest commit"
}

The agent field can be a name or UUID. If omitted, the first available agent is used.

Response 200 OK:

{
  "status": "completed",
  "agent_id": "a1b2c3d4-...",
  "response": "I've reviewed the commit...",
  "usage": {
    "input_tokens": 150,
    "output_tokens": 200
  }
}

Example:

curl -s -X POST http://127.0.0.1:4545/hooks/agent \
  -H "Authorization: Bearer $WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent": "coder", "message": "Summarize recent changes"}'

System Endpoints

GET /api/health

Public health check. Does not require authentication. Returns a redacted subset of system status (no database or agent_count details).

Response 200 OK:

{
  "status": "ok",
  "uptime_seconds": 3600,
  "panic_count": 0,
  "restart_count": 0
}

The status field is "ok" when all systems are healthy, or "degraded" when the database is unreachable.

GET /api/health/detail

Full health check with all dependency status. Requires authentication. Unlike the public /api/health, this endpoint includes database connectivity and agent counts.

Response 200 OK:

{
  "status": "ok",
  "uptime_seconds": 3600,
  "panic_count": 0,
  "restart_count": 0,
  "agent_count": 3,
  "database": "connected",
  "config_warnings": []
}

GET /api/status

Detailed kernel status including all agents.

Response 200 OK:

{
  "status": "running",
  "agent_count": 2,
  "data_dir": "/home/user/.librefang/data",
  "default_provider": "groq",
  "default_model": "llama-3.3-70b-versatile",
  "uptime_seconds": 3600,
  "agents": [
    {
      "id": "a1b2c3d4-...",
      "name": "hello-world",
      "state": "Running",
      "created_at": "2025-01-15T10:30:00Z",
      "model_provider": "groq",
      "model_name": "llama-3.3-70b-versatile"
    }
  ]
}

GET /api/version

Build and version information.

Response 200 OK:

{
  "name": "librefang",
  "version": "0.1.0",
  "build_date": "2025-01-15",
  "git_sha": "abc1234",
  "rust_version": "1.82.0",
  "platform": "linux",
  "arch": "x86_64"
}

POST /api/shutdown

Initiate graceful shutdown. Agent states are preserved to SQLite for restore on next boot.

Response 200 OK:

{
  "status": "shutting_down"
}

GET /api/profiles

List available agent profiles (predefined configurations for common use cases).

Response 200 OK:

{
  "profiles": [
    {
      "name": "coder",
      "tier": "smart",
      "description": "Expert coding assistant"
    },
    {
      "name": "researcher",
      "tier": "frontier",
      "description": "Deep research and analysis"
    }
  ]
}

GET /api/tools

List all available tools that agents can use.

Response 200 OK:

{
  "tools": [
    "file_read",
    "file_write",
    "file_list",
    "web_fetch",
    "web_search",
    "shell_exec",
    "kv_get",
    "kv_set",
    "agent_call"
  ],
  "total": 23
}

GET /api/config

Retrieve current kernel configuration (secrets are redacted).

Response 200 OK:

{
  "data_dir": "/home/user/.librefang/data",
  "default_provider": "groq",
  "default_model": "llama-3.3-70b-versatile",
  "listen_addr": "127.0.0.1:4200",
  "api_key_set": true,
  "channels_configured": 2,
  "mcp_servers": 1
}

GET /api/metrics

Prometheus-compatible metrics endpoint. Returns metrics in Prometheus text exposition format.

Response 200 OK (text/plain):

# HELP librefang_agents_total Total number of agents
# TYPE librefang_agents_total gauge
librefang_agents_total 5
# HELP librefang_requests_total Total API requests
# TYPE librefang_requests_total counter
librefang_requests_total 1042

Example:

curl -s http://127.0.0.1:4545/api/metrics

GET /api/logs/stream

SSE stream of real-time daemon log entries. Useful for live monitoring.

Response: Server-Sent Events stream.

event: log
data: {"timestamp":"2025-01-15T10:30:00Z","level":"INFO","target":"librefang_api","message":"Request completed"}

Example:

curl -s -N http://127.0.0.1:4545/api/logs/stream

GET /api/commands

List available chat commands for the dynamic slash menu in WebChat.

Response 200 OK:

{
  "commands": [
    {"cmd": "/help", "desc": "Show available commands"},
    {"cmd": "/new", "desc": "Reset session (clear history)"},
    {"cmd": "/compact", "desc": "Trigger LLM session compaction"},
    {"cmd": "/model", "desc": "Show or switch model (/model [name])"},
    {"cmd": "/stop", "desc": "Cancel current agent run"},
    {"cmd": "/usage", "desc": "Show session token usage & cost"},
    {"cmd": "/think", "desc": "Toggle extended thinking (/think [on|off|stream])"},
    {"cmd": "/github", "desc": "Skill: GitHub integration", "source": "skill"}
  ]
}

Example:

curl -s http://127.0.0.1:4545/api/commands

GET /api/peers

List OFP (LibreFang Protocol) wire peers and their connection status.

Response 200 OK:

{
  "peers": [
    {
      "node_id": "peer-1",
      "address": "192.168.1.100:4000",
      "state": "connected",
      "authenticated": true,
      "last_seen": "2025-01-15T10:30:00Z"
    }
  ]
}

Model Catalog Endpoints

LibreFang maintains a built-in catalog of 51+ models across 20 providers. These endpoints allow you to browse available models, check provider authentication status, and resolve model aliases.

GET /api/models

List the full model catalog. Returns all known models with their provider, tier, context window, and pricing information.

Response 200 OK:

{
  "models": [
    {
      "id": "claude-sonnet-4-20250514",
      "provider": "anthropic",
      "display_name": "Claude Sonnet 4",
      "tier": "frontier",
      "context_window": 200000,
      "input_cost_per_1m": 3.0,
      "output_cost_per_1m": 15.0,
      "supports_tools": true,
      "supports_vision": true,
      "supports_streaming": true
    },
    {
      "id": "gemini-2.5-flash",
      "provider": "gemini",
      "display_name": "Gemini 2.5 Flash",
      "tier": "smart",
      "context_window": 1048576,
      "input_cost_per_1m": 0.15,
      "output_cost_per_1m": 0.6,
      "supports_tools": true,
      "supports_vision": true,
      "supports_streaming": true
    }
  ],
  "total": 51
}

GET /api/models/{id}

Get detailed information about a specific model.

Response 200 OK:

{
  "id": "llama-3.3-70b-versatile",
  "provider": "groq",
  "display_name": "Llama 3.3 70B",
  "tier": "fast",
  "context_window": 131072,
  "input_cost_per_1m": 0.59,
  "output_cost_per_1m": 0.79,
  "supports_tools": true,
  "supports_vision": false,
  "supports_streaming": true
}

Response 404 Not Found:

{
  "error": "Model 'unknown-model' not found in catalog"
}

GET /api/models/aliases

List all model aliases. Aliases provide short names that resolve to full model IDs (e.g., sonnet resolves to claude-sonnet-4-20250514).

Response 200 OK:

{
  "aliases": {
    "sonnet": "claude-sonnet-4-20250514",
    "opus": "claude-opus-4-20250514",
    "haiku": "claude-3-5-haiku-20241022",
    "flash": "gemini-2.5-flash",
    "gpt4": "gpt-4o",
    "llama": "llama-3.3-70b-versatile",
    "deepseek": "deepseek-chat",
    "grok": "grok-2",
    "jamba": "jamba-1.5-large"
  },
  "total": 23
}

GET /api/providers

List all known LLM providers and their authentication status. Auth status is detected by checking environment variable presence (never reads secret values).

Response 200 OK:

{
  "providers": [
    {
      "name": "anthropic",
      "display_name": "Anthropic",
      "auth_status": "configured",
      "env_var": "ANTHROPIC_API_KEY",
      "base_url": "https://api.anthropic.com",
      "model_count": 3
    },
    {
      "name": "groq",
      "display_name": "Groq",
      "auth_status": "configured",
      "env_var": "GROQ_API_KEY",
      "base_url": "https://api.groq.com/openai",
      "model_count": 4
    },
    {
      "name": "ollama",
      "display_name": "Ollama",
      "auth_status": "no_key_needed",
      "base_url": "http://localhost:11434",
      "model_count": 0
    }
  ],
  "total": 20
}

Provider Configuration Endpoints

Manage LLM provider API keys at runtime without editing config files or restarting the daemon.

POST /api/providers/{name}/key

Set an API key for a provider. The key is stored securely and takes effect immediately.

Request Body:

{
  "api_key": "sk-..."
}

Response 200 OK:

{
  "status": "configured",
  "provider": "anthropic"
}

DELETE /api/providers/{name}/key

Remove the API key for a provider. Agents using this provider will fall back to the FallbackDriver or fail.

Response 200 OK:

{
  "status": "removed",
  "provider": "anthropic"
}

POST /api/providers/{name}/test

Test provider connectivity by making a minimal API call. Verifies that the configured API key is valid and the provider endpoint is reachable.

Response 200 OK:

{
  "status": "ok",
  "provider": "anthropic",
  "latency_ms": 245,
  "model_tested": "claude-sonnet-4-20250514"
}

Response 401 Unauthorized:

{
  "status": "failed",
  "provider": "anthropic",
  "error": "Invalid API key"
}

PUT /api/providers/{name}/url

Set a custom base URL for a provider (e.g., for self-hosted instances or proxy endpoints).

Request Body:

{
  "base_url": "https://my-proxy.example.com/v1"
}

Response 200 OK:

{
  "status": "ok",
  "provider": "openai",
  "base_url": "https://my-proxy.example.com/v1"
}

Example:

curl -s -X PUT http://127.0.0.1:4545/api/providers/openai/url \
  -H "Content-Type: application/json" \
  -d '{"base_url": "https://my-proxy.example.com/v1"}'

POST /api/providers/github-copilot/oauth/start

Start GitHub Copilot OAuth device flow for authentication.

Response 200 OK:

{
  "poll_id": "poll-1234",
  "user_code": "ABCD-1234",
  "verification_uri": "https://github.com/login/device"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/providers/github-copilot/oauth/start

GET /api/providers/github-copilot/oauth/poll/{poll_id}

Poll for completion of a GitHub Copilot OAuth device flow.

Response 200 OK (pending):

{
  "status": "pending"
}

Response 200 OK (completed):

{
  "status": "authorized",
  "provider": "github-copilot"
}

Example:

curl -s http://127.0.0.1:4545/api/providers/github-copilot/oauth/poll/poll-1234

POST /api/models/custom

Add a custom model to the catalog.

Request Body:

{
  "id": "my-fine-tuned-model",
  "provider": "openai",
  "display_name": "My Fine-tuned GPT-4",
  "context_window": 128000,
  "input_cost_per_1m": 5.0,
  "output_cost_per_1m": 15.0,
  "supports_tools": true,
  "supports_vision": false,
  "supports_streaming": true
}

Response 201 Created:

{
  "status": "added",
  "model_id": "my-fine-tuned-model"
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/models/custom \
  -H "Content-Type: application/json" \
  -d '{"id": "ft-gpt4", "provider": "openai", "display_name": "Fine-tuned GPT-4", "context_window": 128000}'

DELETE /api/models/custom/{id}

Remove a custom model from the catalog.

Response 200 OK:

{
  "status": "removed",
  "model_id": "my-fine-tuned-model"
}

Example:

curl -s -X DELETE http://127.0.0.1:4545/api/models/custom/my-fine-tuned-model

Skills & Marketplace Endpoints

Manage the skill registry. Skills extend agent capabilities with Python, Node.js, WASM, or prompt-only modules. All skill installations go through SHA256 verification and prompt injection scanning.

GET /api/skills

List all installed skills.

Response 200 OK:

{
  "skills": [
    {
      "name": "github",
      "version": "1.0.0",
      "runtime": "prompt_only",
      "description": "GitHub integration for issues, PRs, and repos",
      "bundled": true
    },
    {
      "name": "docker",
      "version": "1.0.0",
      "runtime": "prompt_only",
      "description": "Docker container management",
      "bundled": true
    }
  ],
  "total": 60
}

POST /api/skills/install

Install a skill from a local path or URL. The skill manifest is verified (SHA256 checksum) and scanned for prompt injection before installation.

Request Body:

{
  "source": "/path/to/skill",
  "verify": true
}

Response 201 Created:

{
  "status": "installed",
  "skill": "my-custom-skill",
  "version": "1.0.0"
}

POST /api/skills/uninstall

Remove an installed skill. Bundled skills cannot be uninstalled.

Request Body:

{
  "name": "my-custom-skill"
}

Response 200 OK:

{
  "status": "uninstalled",
  "skill": "my-custom-skill"
}

POST /api/skills/create

Create a new skill from a template.

Request Body:

{
  "name": "my-skill",
  "runtime": "python",
  "description": "A custom skill"
}

Response 201 Created:

{
  "status": "created",
  "skill": "my-skill",
  "path": "/home/user/.librefang/skills/my-skill"
}

GET /api/marketplace/search

Search the FangHub marketplace for community skills.

Query Parameters:

  • q (required): Search query string
  • page (optional): Page number (default: 1)

Response 200 OK:

{
  "results": [
    {
      "name": "weather-api",
      "author": "community",
      "description": "Real-time weather data integration",
      "downloads": 1250,
      "version": "2.1.0"
    }
  ],
  "total": 1,
  "page": 1
}

ClawHub Endpoints

Browse and install skills from ClawHub (OpenClaw ecosystem compatibility). All installations go through the full security pipeline: SHA256 verification, SKILL.md security scanning, and trust boundary enforcement.

GET /api/clawhub/search

Search ClawHub for compatible skills.

Query Parameters:

  • q (required): Search query

Response 200 OK:

{
  "results": [
    {
      "slug": "data-pipeline",
      "name": "Data Pipeline",
      "description": "ETL data pipeline automation",
      "author": "clawhub-community",
      "version": "1.2.0"
    }
  ],
  "total": 1
}

GET /api/clawhub/browse

Browse ClawHub categories.

Query Parameters:

  • category (optional): Filter by category
  • page (optional): Page number (default: 1)

Response 200 OK:

{
  "skills": [
    {
      "slug": "data-pipeline",
      "name": "Data Pipeline",
      "category": "data",
      "description": "ETL data pipeline automation"
    }
  ],
  "total": 15,
  "page": 1
}

GET /api/clawhub/skill/{slug}

Get detailed information about a specific ClawHub skill.

Response 200 OK:

{
  "slug": "data-pipeline",
  "name": "Data Pipeline",
  "description": "ETL data pipeline automation",
  "author": "clawhub-community",
  "version": "1.2.0",
  "runtime": "python",
  "readme": "# Data Pipeline\n\nAutomated ETL...",
  "sha256": "a1b2c3d4..."
}

POST /api/clawhub/install

Install a skill from ClawHub. Downloads, verifies SHA256 checksum, scans for prompt injection, and converts SKILL.md format to LibreFang skill.toml automatically.

Request Body:

{
  "slug": "data-pipeline"
}

Response 201 Created:

{
  "status": "installed",
  "skill": "data-pipeline",
  "version": "1.2.0",
  "converted_from": "SKILL.md"
}

MCP & A2A Protocol Endpoints

LibreFang supports both Model Context Protocol (MCP) for tool interoperability and Agent-to-Agent (A2A) protocol for cross-system agent communication.

GET /api/mcp/servers

List configured and connected MCP servers with their available tools.

Response 200 OK:

{
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "connected": true,
      "tools": [
        {
          "name": "mcp_filesystem_read_file",
          "description": "Read a file from the filesystem"
        },
        {
          "name": "mcp_filesystem_write_file",
          "description": "Write content to a file"
        }
      ]
    }
  ],
  "total": 1
}

POST /mcp

MCP HTTP transport endpoint. Accepts JSON-RPC 2.0 requests and exposes LibreFang tools via the MCP protocol to external clients.

Request Body (JSON-RPC 2.0):

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

Response 200 OK:

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "file_read",
        "description": "Read a file's contents",
        "inputSchema": {
          "type": "object",
          "properties": {
            "path": {"type": "string"}
          }
        }
      }
    ]
  },
  "id": 1
}

GET /.well-known/agent.json

A2A agent card discovery endpoint. Returns the server's A2A agent card, which describes its capabilities, supported protocols, and available agents.

Response 200 OK:

{
  "name": "LibreFang",
  "description": "LibreFang Agent Operating System",
  "url": "http://127.0.0.1:4545",
  "version": "0.1.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "chat",
      "name": "Chat",
      "description": "General-purpose chat with any agent"
    }
  ]
}

GET /a2a/agents

List agents available via A2A protocol.

Response 200 OK:

{
  "agents": [
    {
      "id": "a1b2c3d4-...",
      "name": "coder",
      "description": "Expert coding assistant",
      "skills": ["code-review", "debugging", "refactoring"]
    }
  ]
}

POST /a2a/tasks/send

Send a task to an agent via A2A protocol. Follows the Google A2A specification for inter-agent task delegation.

Request Body:

{
  "agent_id": "a1b2c3d4-...",
  "message": {
    "role": "user",
    "parts": [
      {"text": "Review this code for security issues"}
    ]
  }
}

Response 200 OK:

{
  "task_id": "task-1234-...",
  "status": "completed",
  "result": {
    "role": "agent",
    "parts": [
      {"text": "I found 2 potential security issues..."}
    ]
  }
}

GET /a2a/tasks/{id}

Get the status and result of an A2A task.

Response 200 OK:

{
  "task_id": "task-1234-...",
  "status": "completed",
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:30:05Z",
  "result": {
    "role": "agent",
    "parts": [
      {"text": "Analysis complete..."}
    ]
  }
}

POST /a2a/tasks/{id}/cancel

Cancel a running A2A task.

Response 200 OK:

{
  "task_id": "task-1234-...",
  "status": "cancelled"
}

A2A Management Endpoints

Manage outbound A2A (Agent-to-Agent) connections to external agent systems.

GET /api/a2a/agents

List discovered external A2A agents.

Response 200 OK:

{
  "agents": [
    {
      "name": "External Coder",
      "url": "https://remote-server.example.com",
      "description": "Remote coding agent",
      "skills": ["code-review"]
    }
  ]
}

Example:

curl -s http://127.0.0.1:4545/api/a2a/agents

POST /api/a2a/discover

Discover an A2A agent at a given URL by fetching its agent card.

Request Body:

{
  "url": "https://remote-server.example.com"
}

Response 200 OK:

{
  "name": "External Coder",
  "url": "https://remote-server.example.com",
  "description": "Remote coding agent",
  "skills": ["code-review", "debugging"]
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/a2a/discover \
  -H "Content-Type: application/json" \
  -d '{"url": "https://remote-server.example.com"}'

POST /api/a2a/send

Send a task to an external A2A agent.

Request Body:

{
  "url": "https://remote-server.example.com",
  "message": "Review this code for security issues"
}

Response 200 OK:

{
  "task_id": "ext-task-1234",
  "status": "completed",
  "response": "I found 2 potential issues..."
}

Example:

curl -s -X POST http://127.0.0.1:4545/api/a2a/send \
  -H "Content-Type: application/json" \
  -d '{"url": "https://remote-server.example.com", "message": "Hello"}'

GET /api/a2a/tasks/{id}/status

Check the status of an external A2A task.

Response 200 OK:

{
  "task_id": "ext-task-1234",
  "status": "completed",
  "result": "Analysis complete..."
}

Example:

curl -s http://127.0.0.1:4545/api/a2a/tasks/ext-task-1234/status

Audit & Security Endpoints

LibreFang maintains a Merkle hash chain audit trail for all security-relevant operations. These endpoints allow inspection and verification of the audit log integrity.

GET /api/audit/recent

Retrieve recent audit log entries.

Query Parameters:

  • limit (optional): Number of entries to return (default: 50, max: 500)

Response 200 OK:

{
  "entries": [
    {
      "id": 1042,
      "timestamp": "2025-01-15T10:30:00Z",
      "event_type": "agent_spawned",
      "agent_id": "a1b2c3d4-...",
      "details": "Agent 'coder' spawned with model groq/llama-3.3-70b-versatile",
      "hash": "a1b2c3d4e5f6...",
      "prev_hash": "f6e5d4c3b2a1..."
    }
  ],
  "total": 1042
}

GET /api/audit/verify

Verify the integrity of the Merkle hash chain audit trail. Walks the entire chain and reports any broken links.

Response 200 OK:

{
  "status": "valid",
  "chain_length": 1042,
  "first_entry": "2025-01-10T08:00:00Z",
  "last_entry": "2025-01-15T10:30:00Z"
}

Response 200 OK (chain broken):

{
  "status": "broken",
  "chain_length": 1042,
  "break_at": 847,
  "error": "Hash mismatch at entry 847"
}

GET /api/security

Security status overview showing the state of all 16 security systems.

Response 200 OK:

{
  "security_systems": {
    "merkle_audit_trail": "active",
    "taint_tracking": "active",
    "wasm_dual_metering": "active",
    "security_headers": "active",
    "health_redaction": "active",
    "subprocess_sandbox": "active",
    "manifest_signing": "active",
    "gcra_rate_limiter": "active",
    "secret_zeroization": "active",
    "path_traversal_prevention": "active",
    "ssrf_protection": "active",
    "capability_inheritance_validation": "active",
    "ofp_hmac_auth": "active",
    "prompt_injection_scanning": "active",
    "loop_guard": "active",
    "session_repair": "active"
  },
  "total_systems": 16,
  "all_active": true
}

Usage & Analytics Endpoints

Track token usage, costs, and model utilization across all agents. Powered by the metering engine with cost estimation from the model catalog.

GET /api/usage

Get overall usage statistics.

Query Parameters:

  • period (optional): Time period (hour, day, week, month; default: day)

Response 200 OK:

{
  "period": "day",
  "total_input_tokens": 125000,
  "total_output_tokens": 87000,
  "total_cost_usd": 0.42,
  "request_count": 156,
  "active_agents": 5
}

GET /api/usage/summary

Get a high-level usage summary with quota information.

Response 200 OK:

{
  "today": {
    "input_tokens": 125000,
    "output_tokens": 87000,
    "cost_usd": 0.42,
    "requests": 156
  },
  "quota": {
    "hourly_token_limit": 1000000,
    "hourly_tokens_used": 45000,
    "hourly_reset_at": "2025-01-15T11:00:00Z"
  }
}

GET /api/usage/by-model

Get usage breakdown by model.

Response 200 OK:

{
  "models": [
    {
      "model": "llama-3.3-70b-versatile",
      "provider": "groq",
      "input_tokens": 80000,
      "output_tokens": 55000,
      "cost_usd": 0.09,
      "request_count": 120
    },
    {
      "model": "gemini-2.5-flash",
      "provider": "gemini",
      "input_tokens": 45000,
      "output_tokens": 32000,
      "cost_usd": 0.33,
      "request_count": 36
    }
  ]
}

GET /api/usage/daily

Get daily usage time series data.

Response 200 OK:

{
  "daily": [
    {
      "date": "2025-01-14",
      "input_tokens": 200000,
      "output_tokens": 150000,
      "cost_usd": 0.85,
      "request_count": 250
    },
    {
      "date": "2025-01-15",
      "input_tokens": 125000,
      "output_tokens": 87000,
      "cost_usd": 0.42,
      "request_count": 156
    }
  ]
}

Example:

curl -s http://127.0.0.1:4545/api/usage/daily

Migration Endpoints

Import data from OpenClaw or other agent frameworks. The migration engine handles YAML-to-TOML manifest conversion, SKILL.md parsing, and session history import.

GET /api/migrate/detect

Auto-detect migration sources on the system. Scans common locations for OpenClaw installations, config files, and agent data.

Response 200 OK:

{
  "sources": [
    {
      "type": "openclaw",
      "path": "/home/user/.openclaw",
      "version": "2.1.0",
      "agents_found": 12,
      "skills_found": 8
    }
  ]
}

POST /api/migrate/scan

Scan a specific path for importable data.

Request Body:

{
  "path": "/home/user/.openclaw"
}

Response 200 OK:

{
  "agents": [
    {
      "name": "my-agent",
      "format": "yaml",
      "convertible": true
    }
  ],
  "skills": [
    {
      "name": "custom-skill",
      "format": "SKILL.md",
      "convertible": true
    }
  ],
  "sessions": 45
}

POST /api/migrate

Run the migration. Converts manifests, imports skills, and optionally imports session history.

Request Body:

{
  "source": "/home/user/.openclaw",
  "import_agents": true,
  "import_skills": true,
  "import_sessions": false
}

Response 200 OK:

{
  "status": "completed",
  "agents_imported": 12,
  "skills_imported": 8,
  "sessions_imported": 0,
  "warnings": [
    "Skill 'legacy-plugin' uses unsupported runtime 'ruby', skipped"
  ]
}

WebSocket Protocol

Connecting

GET /api/agents/&lbrace;id&rbrace;/ws

Upgrades to a WebSocket connection for real-time bidirectional chat with an agent. Returns 400 if the agent ID is invalid, or 404 if the agent does not exist.

Message Format

All messages are JSON-encoded strings.

Client to Server

Send a message:

{
  "type": "message",
  "content": "What is the weather like?"
}

Plain text (non-JSON) is also accepted and treated as a message.

Chat commands (sent as messages with / prefix):

CommandDescription
/newStart a new session (clear history)
/compactTrigger LLM session compaction
/model <name>Switch the agent's model
/stopCancel current LLM run
/usageShow token usage and cost
/thinkToggle extended thinking mode
/modelsList available models
/providersList LLM providers and auth status

Ping:

{
  "type": "ping"
}

Server to Client

Connection confirmed (sent immediately on connect):

{
  "type": "connected",
  "agent_id": "a1b2c3d4-..."
}

Thinking indicator (sent when agent starts processing):

{
  "type": "thinking"
}

Text delta (streaming token, sent as the LLM generates output):

{
  "type": "text_delta",
  "content": "The weather"
}

Tool use started (sent when the agent invokes a tool):

{
  "type": "tool_start",
  "tool": "web_fetch"
}

Complete response (sent when agent finishes, contains final aggregated response):

{
  "type": "response",
  "content": "The weather today is sunny with a high of 72F.",
  "input_tokens": 245,
  "output_tokens": 32,
  "iterations": 2,
  "cost_usd": 0.0012
}

Error:

{
  "type": "error",
  "content": "Agent not found"
}

Agent list update (sent every 5 seconds with current agent states):

{
  "type": "agents_updated",
  "agents": [
    {
      "id": "a1b2c3d4-...",
      "name": "hello-world",
      "state": "Running",
      "model_provider": "groq",
      "model_name": "llama-3.3-70b-versatile"
    }
  ]
}

Pong (response to ping):

{
  "type": "pong"
}

Connection Lifecycle

  1. Client connects to ws://host:port/api/agents/&lbrace;id&rbrace;/ws.
  2. Server sends {"type": "connected"}.
  3. Client sends {"type": "message", "content": "..."}.
  4. Server sends {"type": "thinking"}, then zero or more {"type": "text_delta"} events, then {"type": "response"}.
  5. Server periodically sends {"type": "agents_updated"} every 5 seconds.
  6. Client sends a Close frame or disconnects to end the session.

SSE Streaming

POST /api/agents/{id}/message/stream

Send a message and receive the response as a Server-Sent Events stream. This enables real-time token-by-token streaming.

Request Body (JSON):

{
  "message": "Explain quantum computing"
}

SSE Event Stream:

event: chunk
data: {"content":"Quantum","done":false}

event: chunk
data: {"content":" computing","done":false}

event: chunk
data: {"content":" is a type","done":false}

event: tool_use
data: {"tool":"web_search"}

event: tool_result
data: {"tool":"web_search","input":{"query":"quantum computing basics"}}

event: done
data: {"done":true,"usage":{"input_tokens":150,"output_tokens":340}}

SSE Event Types

Event NameDescription
chunkText delta from the LLM. "done": false indicates more tokens are coming.
tool_useThe agent is invoking a tool. Contains the tool name.
tool_resultA tool invocation has completed. Contains the tool name and input.
doneFinal event. Contains "done": true and token usage statistics.

OpenAI-Compatible API

LibreFang exposes an OpenAI-compatible API for drop-in integration with tools that support the OpenAI API format (Cursor, Continue, Open WebUI, etc.).

POST /v1/chat/completions

Send a chat completion request using the OpenAI message format.

Request Body:

{
  "model": "librefang:coder",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1024
}

Model resolution (the model field maps to an LibreFang agent):

FormatExampleBehavior
librefang:<name>librefang:coderFind agent by name
UUIDa1b2c3d4-...Find agent by ID
Plain stringcoderTry as agent name
Any othergpt-4oFalls back to first registered agent

Image support --- messages can include image content parts:

{
  "model": "librefang:analyst",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBOR..."}}
      ]
    }
  ]
}

Response (non-streaming) 200 OK:

{
  "id": "chatcmpl-a1b2c3d4-...",
  "object": "chat.completion",
  "created": 1708617600,
  "model": "coder",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 12,
    "total_tokens": 37
  }
}

Streaming --- Set "stream": true for SSE:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":25,"completion_tokens":12,"total_tokens":37}}

data: [DONE]

GET /v1/models

List available models (agents) in OpenAI format.

Response 200 OK:

{
  "object": "list",
  "data": [
    {
      "id": "librefang:coder",
      "object": "model",
      "created": 1708617600,
      "owned_by": "librefang"
    },
    {
      "id": "librefang:researcher",
      "object": "model",
      "created": 1708617600,
      "owned_by": "librefang"
    }
  ]
}

Error Responses

All error responses use a consistent JSON format:

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

HTTP Status Codes

CodeMeaning
200Success
201Created (spawn agent, create workflow, create trigger, install skill)
400Bad request (invalid UUID, missing required fields, malformed TOML/JSON)
401Unauthorized (missing or invalid Authorization: Bearer header)
404Not found (agent, workflow, trigger, template, model, skill, or KV key does not exist)
429Too many requests (GCRA rate limit exceeded)
500Internal server error (agent loop failure, database error, driver error)

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:

HeaderValue
Content-Security-Policydefault-src 'self' (with appropriate directives)
X-Frame-OptionsDENY
X-Content-Type-Optionsnosniff
Strict-Transport-Securitymax-age=63072000; includeSubDomains
X-Request-IdUnique UUID per request

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/&lbrace;id&rbrace;/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

150+ endpoints across 25+ groups.

MethodPathDescription
System
GET/WebChat UI
GET/api/healthHealth check (no auth, redacted)
GET/api/health/detailFull health check (auth required)
GET/api/statusKernel status
GET/api/versionVersion info
POST/api/shutdownGraceful shutdown
GET/api/profilesList agent profiles
GET/api/toolsList available tools
GET/api/configConfiguration (secrets redacted)
GET/api/metricsPrometheus metrics
GET/api/logs/streamLive log streaming (SSE)
GET/api/commandsChat slash commands
GET/api/peersList OFP wire peers
GET/api/network/statusOFP network status
Agents
GET/api/agentsList agents
POST/api/agentsSpawn agent
GET/api/agents/&lbrace;id&rbrace;Get agent details
PATCH/api/agents/&lbrace;id&rbrace;Partial update agent
DELETE/api/agents/&lbrace;id&rbrace;Kill agent
PUT/api/agents/&lbrace;id&rbrace;/updateFull update agent
PUT/api/agents/&lbrace;id&rbrace;/modeSet agent mode
POST/api/agents/&lbrace;id&rbrace;/messageSend message (blocking)
POST/api/agents/&lbrace;id&rbrace;/message/streamSend message (SSE stream)
GET/api/agents/&lbrace;id&rbrace;/sessionGet conversation history
GET/api/agents/&lbrace;id&rbrace;/wsWebSocket chat
POST/api/agents/&lbrace;id&rbrace;/session/resetReset session
POST/api/agents/&lbrace;id&rbrace;/session/compactLLM-based compaction
POST/api/agents/&lbrace;id&rbrace;/stopCancel current run
PUT/api/agents/&lbrace;id&rbrace;/modelSwitch model
DELETE/api/agents/&lbrace;id&rbrace;/historyClear all history
GET/api/agents/&lbrace;id&rbrace;/toolsGet tool allowlist/blocklist
PUT/api/agents/&lbrace;id&rbrace;/toolsSet tool allowlist/blocklist
GET/api/agents/&lbrace;id&rbrace;/skillsGet skill config
PUT/api/agents/&lbrace;id&rbrace;/skillsSet skill config
GET/api/agents/&lbrace;id&rbrace;/mcp_serversGet MCP servers
PUT/api/agents/&lbrace;id&rbrace;/mcp_serversSet MCP servers
PATCH/api/agents/&lbrace;id&rbrace;/identityUpdate visual identity
PATCH/api/agents/&lbrace;id&rbrace;/configHot-update agent config
POST/api/agents/&lbrace;id&rbrace;/cloneClone agent
POST/api/agents/&lbrace;id&rbrace;/uploadUpload file attachment
GET/api/agents/&lbrace;id&rbrace;/filesList workspace files
GET/api/agents/&lbrace;id&rbrace;/files/&lbrace;name&rbrace;Read workspace file
PUT/api/agents/&lbrace;id&rbrace;/files/&lbrace;name&rbrace;Write workspace file
GET/api/agents/&lbrace;id&rbrace;/deliveriesDelivery receipts
GET/api/agents/&lbrace;id&rbrace;/sessionsList agent sessions
POST/api/agents/&lbrace;id&rbrace;/sessionsCreate agent session
POST/api/agents/&lbrace;id&rbrace;/sessions/&lbrace;sid&rbrace;/switchSwitch session
GET/api/agents/&lbrace;id&rbrace;/sessions/by-label/&lbrace;l&rbrace;Find session by label
GET/api/uploads/&lbrace;file_id&rbrace;Serve uploaded file
Sessions
GET/api/sessionsList all sessions
DELETE/api/sessions/&lbrace;id&rbrace;Delete session
PUT/api/sessions/&lbrace;id&rbrace;/labelSet session label
Workflows
GET/api/workflowsList workflows
POST/api/workflowsCreate workflow
POST/api/workflows/&lbrace;id&rbrace;/runRun workflow
GET/api/workflows/&lbrace;id&rbrace;/runsList workflow runs
Triggers
GET/api/triggersList triggers
POST/api/triggersCreate trigger
PUT/api/triggers/&lbrace;id&rbrace;Update trigger
DELETE/api/triggers/&lbrace;id&rbrace;Delete trigger
Schedules
GET/api/schedulesList scheduled jobs
POST/api/schedulesCreate scheduled job
PUT/api/schedules/&lbrace;id&rbrace;Update scheduled job
DELETE/api/schedules/&lbrace;id&rbrace;Delete scheduled job
POST/api/schedules/&lbrace;id&rbrace;/runManually trigger job
Cron Jobs
GET/api/cron/jobsList cron jobs
POST/api/cron/jobsCreate cron job
DELETE/api/cron/jobs/&lbrace;id&rbrace;Delete cron job
PUT/api/cron/jobs/&lbrace;id&rbrace;/enableEnable/disable cron job
GET/api/cron/jobs/&lbrace;id&rbrace;/statusCron job status
Memory
GET/api/memory/agents/&lbrace;id&rbrace;/kvList KV pairs
GET/api/memory/agents/&lbrace;id&rbrace;/kv/&lbrace;key&rbrace;Get KV value
PUT/api/memory/agents/&lbrace;id&rbrace;/kv/&lbrace;key&rbrace;Set KV value
DELETE/api/memory/agents/&lbrace;id&rbrace;/kv/&lbrace;key&rbrace;Delete KV value
Channels
GET/api/channelsList channels
POST/api/channels/&lbrace;name&rbrace;/configureConfigure channel
DELETE/api/channels/&lbrace;name&rbrace;/configureRemove channel config
POST/api/channels/&lbrace;name&rbrace;/testTest channel
POST/api/channels/reloadHot-reload channels
POST/api/channels/whatsapp/qr/startWhatsApp QR login
GET/api/channels/whatsapp/qr/statusWhatsApp QR status
Templates
GET/api/templatesList templates
GET/api/templates/&lbrace;name&rbrace;Get template
Hands
GET/api/handsList hand definitions
GET/api/hands/activeList active instances
GET/api/hands/&lbrace;id&rbrace;Get hand details
POST/api/hands/installInstall hand
POST/api/hands/&lbrace;id&rbrace;/activateActivate hand
POST/api/hands/&lbrace;id&rbrace;/check-depsCheck dependencies
POST/api/hands/&lbrace;id&rbrace;/install-depsInstall dependencies
GET/api/hands/&lbrace;id&rbrace;/settingsGet settings
PUT/api/hands/&lbrace;id&rbrace;/settingsUpdate settings
POST/api/hands/instances/&lbrace;id&rbrace;/pausePause instance
POST/api/hands/instances/&lbrace;id&rbrace;/resumeResume instance
DELETE/api/hands/instances/&lbrace;id&rbrace;Deactivate instance
GET/api/hands/instances/&lbrace;id&rbrace;/statsInstance statistics
GET/api/hands/instances/&lbrace;id&rbrace;/browserBrowser state
Budget
GET/api/budgetGlobal budget status
PUT/api/budgetUpdate budget limits
GET/api/budget/agentsPer-agent cost ranking
GET/api/budget/agents/&lbrace;id&rbrace;Agent budget detail
PUT/api/budget/agents/&lbrace;id&rbrace;Update agent budget
Integrations
GET/api/integrationsList installed
GET/api/integrations/availableList available
POST/api/integrations/addInstall integration
DELETE/api/integrations/&lbrace;id&rbrace;Remove integration
POST/api/integrations/&lbrace;id&rbrace;/reconnectReconnect MCP
GET/api/integrations/healthHealth status
POST/api/integrations/reloadHot-reload
Comms & Network
GET/api/comms/topologyAgent topology graph
GET/api/comms/eventsCommunication events
GET/api/comms/events/streamEvents SSE stream
POST/api/comms/sendSend inter-agent message
POST/api/comms/taskDelegate task
Approvals
GET/api/approvalsList pending approvals
POST/api/approvalsCreate approval request
POST/api/approvals/&lbrace;id&rbrace;/approveApprove request
POST/api/approvals/&lbrace;id&rbrace;/rejectReject request
Device Pairing
POST/api/pairing/requestCreate pairing request
POST/api/pairing/completeComplete pairing
GET/api/pairing/devicesList paired devices
DELETE/api/pairing/devices/&lbrace;id&rbrace;Remove device
POST/api/pairing/notifyPush notification
Config
GET/api/config/schemaConfig structure
POST/api/config/setSet config value
POST/api/config/reloadHot-reload config
Catalog
POST/api/catalog/updateSync model catalog
GET/api/catalog/statusCatalog sync status
Bindings
GET/api/bindingsList bindings
POST/api/bindingsAdd binding
DELETE/api/bindings/&lbrace;index&rbrace;Remove binding
Webhooks
POST/hooks/wakeInject wake event
POST/hooks/agentWebhook agent message
Model Catalog
GET/api/modelsFull model catalog
GET/api/models/&lbrace;id&rbrace;Model details
GET/api/models/aliasesModel aliases
POST/api/models/customAdd custom model
DELETE/api/models/custom/&lbrace;id&rbrace;Remove custom model
GET/api/providersProvider list
Provider Config
POST/api/providers/&lbrace;name&rbrace;/keySet provider API key
DELETE/api/providers/&lbrace;name&rbrace;/keyRemove provider API key
POST/api/providers/&lbrace;name&rbrace;/testTest provider
PUT/api/providers/&lbrace;name&rbrace;/urlSet provider URL
POST/api/providers/github-copilot/oauth/startCopilot OAuth start
GET/api/providers/github-copilot/oauth/poll/&lbrace;id&rbrace;Copilot OAuth poll
Skills & Marketplace
GET/api/skillsList installed skills
POST/api/skills/installInstall skill
POST/api/skills/uninstallUninstall skill
POST/api/skills/createCreate new skill
GET/api/marketplace/searchSearch FangHub
ClawHub
GET/api/clawhub/searchSearch ClawHub
GET/api/clawhub/browseBrowse ClawHub
GET/api/clawhub/skill/&lbrace;slug&rbrace;Skill details
GET/api/clawhub/skill/&lbrace;slug&rbrace;/codeSkill source code
POST/api/clawhub/installInstall from ClawHub
MCP & A2A Protocol
GET/api/mcp/serversMCP server connections
POST/mcpMCP HTTP transport
GET/.well-known/agent.jsonA2A agent card
GET/a2a/agentsA2A agent list
POST/a2a/tasks/sendSend A2A task
GET/a2a/tasks/&lbrace;id&rbrace;Get A2A task status
POST/a2a/tasks/&lbrace;id&rbrace;/cancelCancel A2A task
A2A Management
GET/api/a2a/agentsList external A2A agents
POST/api/a2a/discoverDiscover external agent
POST/api/a2a/sendSend to external agent
GET/api/a2a/tasks/&lbrace;id&rbrace;/statusExternal task status
Audit & Security
GET/api/audit/recentRecent audit logs
GET/api/audit/verifyVerify Merkle chain
GET/api/securitySecurity status
Usage & Analytics
GET/api/usageUsage statistics
GET/api/usage/summaryUsage summary
GET/api/usage/by-modelUsage by model
GET/api/usage/dailyDaily usage series
Migration
GET/api/migrate/detectDetect migration sources
POST/api/migrate/scanScan for importable data
POST/api/migrateRun migration
OpenAI Compatible
POST/v1/chat/completionsOpenAI-compatible chat
GET/v1/modelsOpenAI-compatible model list