HTTP API - Beige

The HTTP API is also described in Channels → Custom Integrations.

The gateway exposes an HTTP API on port 7433 (configurable via gateway.port). This API is used by the TUI (for LLM proxying and tool execution), by plugin channels, and can be used for custom integrations.

Base URL

http://127.0.0.1:7433

The host and port can be configured in config.json5:

{
  gateway: {
    host: "127.0.0.1",  // default
    port: 7433,          // default
  },
}

Endpoints

Health Check

GET /api/health

Returns the gateway health status. Response:

{
  "status": "ok"
}

Example:

curl http://127.0.0.1:7433/api/health

List Agents

GET /api/agents

Returns all configured agents with their model configuration, tool/skill assignments, and pre-built context strings for the system prompt. Response:

{
  "agents": [
    {
      "name": "assistant",
      "model": {
        "provider": "anthropic",
        "model": "claude-sonnet-4-6",
        "thinkingLevel": "off"
      },
      "fallbackModels": [
        { "provider": "anthropic", "model": "claude-3-5-sonnet-20241022" }
      ],
      "tools": ["git"],
      "skills": ["code-review"],
      "workspaceDir": "/home/user/projects",
      "toolContext": "## Available Tools\n\n### git\n...",
      "skillContext": "## Available Skills\n\n### code-review\n..."
    }
  ]
}

Example:

curl http://127.0.0.1:7433/api/agents

Get Config

GET /api/config

Returns agent configurations and provider metadata (without API keys). Response:

{
  "agents": {
    "assistant": {
      "model": {
        "provider": "anthropic",
        "model": "claude-sonnet-4-6"
      },
      "fallbackModels": [],
      "tools": ["git"],
      "skills": [],
      "workspaceDir": "/home/user/projects"
    }
  },
  "llm": {
    "providers": {
      "anthropic": {
        "baseUrl": null,
        "api": null
      }
    }
  }
}

Example:

curl http://127.0.0.1:7433/api/config

List Agent Models

GET /api/agents/:name/models

Returns model metadata for the agent’s allowed models (primary + fallbacks). The TUI uses this to set up proxy model registrations without needing API keys. Parameters:

:name — Agent name (URL-encoded)

Response:

{
  "models": [
    {
      "id": "claude-sonnet-4-6",
      "name": "Claude Sonnet 4",
      "provider": "anthropic",
      "api": "anthropic-messages",
      "baseUrl": "https://api.anthropic.com",
      "reasoning": false,
      "input": ["text", "image"],
      "cost": { "input": 3, "output": 15, "cacheRead": 0.3, "cacheWrite": 3.75 },
      "contextWindow": 200000,
      "maxTokens": 16384,
      "thinkingLevel": "off"
    }
  ]
}

Example:

curl http://127.0.0.1:7433/api/agents/assistant/models

Execute Tool

POST /api/agents/:name/exec

Execute a core tool (read, write, patch, exec) in the agent’s sandbox. Parameters:

:name — Agent name (URL-encoded)

Request Body:

{
  "tool": "read|write|patch|exec",
  "params": {
    // Tool-specific parameters
  },
  "sessionKey": "optional-session-key"
}

The optional sessionKey is used to derive the channel and session context injected as environment variables into the sandbox (BEIGE_AGENT_NAME, BEIGE_CHANNEL, BEIGE_SESSION_KEY). If omitted, defaults to tui:<agentName>:default. Response:

{
  "content": [
    {
      "type": "text",
      "text": "Tool output..."
    }
  ],
  "isError": false
}

Tool Parameters:

Tool	Parameters
`read`	`path` (string), `offset?` (number), `limit?` (number)
`write`	`path` (string), `content` (string)
`patch`	`path` (string), `oldText` (string), `newText` (string)
`exec`	`command` (string), `timeout?` (number, seconds)

Examples:

# Read a file
curl -X POST http://127.0.0.1:7433/api/agents/assistant/exec \
  -H "Content-Type: application/json" \
  -d '{"tool": "read", "params": {"path": "/workspace/file.txt"}}'

# Write a file
curl -X POST http://127.0.0.1:7433/api/agents/assistant/exec \
  -H "Content-Type: application/json" \
  -d '{"tool": "write", "params": {"path": "/workspace/output.txt", "content": "Hello, world!"}}'

# Execute a command
curl -X POST http://127.0.0.1:7433/api/agents/assistant/exec \
  -H "Content-Type: application/json" \
  -d '{"tool": "exec", "params": {"command": "ls -la /workspace"}}'

Send Prompt

POST /api/agents/:name/prompt

Send a message to an agent and get the full response (non-streaming). The agent session is managed server-side by the gateway’s AgentManager, including fallback model handling and hook execution. Parameters:

:name — Agent name (URL-encoded)

Request Body:

{
  "message": "Your message to the agent",
  "sessionKey": "optional-session-key"
}

If sessionKey is omitted, a default session key is used (api:<agentName>:default). Response:

{
  "response": "Agent's response text..."
}

Example:

curl -X POST http://127.0.0.1:7433/api/agents/assistant/prompt \
  -H "Content-Type: application/json" \
  -d '{"message": "List files in my workspace"}'

Stream LLM Response (LLM Proxy)

POST /api/chat/stream

Proxy an LLM call through the gateway. The gateway resolves API keys server-side, executes prePrompt/postResponse hooks, applies fallback model logic on rate-limit errors, and audit-logs the call. Responses are streamed back as newline-delimited JSON (AssistantMessageEvent objects from the pi SDK). This is the endpoint the TUI uses for all LLM calls — it never needs API keys locally. Request Body:

{
  "provider": "anthropic",
  "modelId": "claude-sonnet-4-6",
  "context": { /* pi SDK Context object (messages array + system prompt) */ },
  "options": {
    "reasoning": true,
    "maxTokens": 8192,
    "temperature": 0.7
  },
  "agentName": "assistant",
  "sessionKey": "tui:assistant:default"
}

Response: Newline-delimited JSON stream (application/x-ndjson). Each line is a JSON object — standard pi AssistantMessageEvent types plus two gateway-specific event types:

Event type	Description
`text_delta`	Streaming text chunk
`done`	Stream complete, includes full message with usage stats
`error`	LLM error (includes error message)
`blocked`	Gateway prePrompt hook blocked the message (includes `reason`)
`model_fallback`	Gateway switched to a fallback model due to rate limiting (includes `provider`, `modelId`)

Example:

curl -X POST http://127.0.0.1:7433/api/chat/stream \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "modelId": "claude-sonnet-4-6",
    "context": {"messages": [{"role": "user", "content": "Hello!"}]},
    "agentName": "assistant"
  }'

List Sessions

GET /api/agents/:name/sessions

List saved sessions for an agent. Parameters:

:name — Agent name (URL-encoded)

Response:

{
  "sessions": [
    {
      "id": "telegram:123456:789",
      "file": "/Users/you/.beige/sessions/assistant/abc123.jsonl",
      "createdAt": "2025-03-06T12:00:00.000Z",
      "updatedAt": "2025-03-06T14:30:00.000Z"
    }
  ]
}

Example:

curl http://127.0.0.1:7433/api/agents/assistant/sessions

Restart Gateway

POST /api/gateway/restart

Trigger a graceful in-place restart of the gateway:

Drain all in-flight LLM/tool calls (including proxied TUI streams)
Tear down sandboxes, sockets, API, and channels
Reload config from disk
Restart everything fresh

Response:

{
  "status": "restarting",
  "message": "Graceful restart initiated. Follow progress with: beige gateway logs -f"
}

Returns 202 Accepted immediately; the restart happens asynchronously. Example:

curl -X POST http://127.0.0.1:7433/api/gateway/restart

Hook Endpoints

These endpoints execute plugin hooks. They are used by the TUI for session lifecycle events and are available for custom integrations. The prePrompt and postResponse hooks for TUI LLM calls are now executed server-side inside the /api/chat/stream endpoint automatically.

Run prePrompt Hooks

POST /api/agents/:name/hooks/pre-prompt

Request Body:

{
  "message": "User's message",
  "sessionKey": "tui:assistant:default",
  "channel": "tui"
}

Response:

{
  "message": "Possibly transformed message",
  "block": false,
  "reason": null
}

Run postResponse Hooks

POST /api/agents/:name/hooks/post-response

Request Body:

{
  "response": "LLM's response text",
  "sessionKey": "tui:assistant:default",
  "channel": "tui"
}

Response:

{
  "response": "Possibly transformed response",
  "block": false
}

Fire sessionCreated Hook

POST /api/agents/:name/hooks/session-created

Request Body:

{
  "sessionKey": "tui:assistant:default",
  "channel": "tui"
}

Response: { "ok": true }

Fire sessionDisposed Hook

POST /api/agents/:name/hooks/session-disposed

Request Body:

{
  "sessionKey": "tui:assistant:default",
  "channel": "tui"
}

Response: { "ok": true }

Error Responses

All endpoints return errors in a consistent format:

{
  "error": "Error message describing what went wrong"
}

Common HTTP status codes:

Code	Meaning
200	Success
202	Accepted (async operation started)
400	Bad request (missing/invalid parameters)
404	Not found (unknown agent, etc.)
500	Internal server error

Authentication

The HTTP API currently has no authentication. It binds to 127.0.0.1 by default and is intended for local use only. If you expose the API to a network, you are responsible for adding authentication (e.g., via a reverse proxy with basic auth, or by modifying the gateway code).

Rate Limiting

There is no built-in rate limiting on the HTTP API itself. The gateway tracks per-provider rate limits internally and applies fallback logic automatically (see LLM Providers → Model Fallback).

Using the API from Code

JavaScript/TypeScript

const GATEWAY_URL = "http://127.0.0.1:7433";

async function execTool(agent: string, tool: string, params: Record<string, any>) {
  const res = await fetch(`${GATEWAY_URL}/api/agents/${agent}/exec`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ tool, params }),
  });
  return res.json();
}

// Example usage
const result = await execTool("assistant", "exec", {
  command: "ls -la /workspace",
});
console.log(result);

Python

import requests

GATEWAY_URL = "http://127.0.0.1:7433"

def exec_tool(agent: str, tool: str, params: dict):
    response = requests.post(
        f"{GATEWAY_URL}/api/agents/{agent}/exec",
        json={"tool": tool, "params": params},
    )
    return response.json()

# Example usage
result = exec_tool("assistant", "exec", {"command": "ls -la /workspace"})
print(result)

​Base URL

​Endpoints

​Health Check

​List Agents

​Get Config

​List Agent Models

​Execute Tool

​Send Prompt

​Stream LLM Response (LLM Proxy)

​List Sessions

​Restart Gateway

​Hook Endpoints

​Run prePrompt Hooks

​Run postResponse Hooks

​Fire sessionCreated Hook

​Fire sessionDisposed Hook

​Error Responses

​Authentication

​Rate Limiting

​Using the API from Code

​JavaScript/TypeScript

​Python

Base URL

Endpoints

Health Check

List Agents

Get Config

List Agent Models

Execute Tool

Send Prompt

Stream LLM Response (LLM Proxy)

List Sessions

Restart Gateway

Hook Endpoints

Run prePrompt Hooks

Run postResponse Hooks

Fire sessionCreated Hook

Fire sessionDisposed Hook

Error Responses

Authentication

Rate Limiting

Using the API from Code

JavaScript/TypeScript

Python