Skip to content

http-api.md

Latest commit

 

History

History
187 lines (141 loc) · 7.64 KB

http-api.md

File metadata and controls

187 lines (141 loc) · 7.64 KB
Raw

HTTP API

The AgentOS gateway is a Starlette ASGI application that exposes a REST HTTP API alongside its streaming WebSocket. Every AgentOS surface — CLI, Web UI, channels, and external clients — talks to this same gateway, so the HTTP endpoints below are a stable integration point for your own applications and automation.

Use this page when you want to call AgentOS from an external app, script, or service instead of the CLI.

Base URL and Auth

The gateway binds to loopback by default:

http://127.0.0.1:18791

On the default loopback bind, no token is required. The gateway ships with auth.mode = "none", and a loopback peer is admitted as a Control connection, so curl http://127.0.0.1:18791/api/... works with no credentials.

A token is only enforced when auth.mode = "token". That mode is required before the gateway will bind to a public address (0.0.0.0 / LAN): the startup guard refuses to serve an unauthenticated public bind, and a token is auto-generated when unset. See gateway.md for bind safety.

When auth is enabled, send the token via HTTP headers (checked in order):

Authorization: Bearer <token>
X-Agentos-Token: <token>

Note: Query-string tokens (?token=<token>) are rejected (401 Unauthorized). Passing tokens in URL query parameters is not supported to prevent token leaks in access logs, browser history, and HTTP referrers.

The gateway implements exactly three auth modes — none, token, and trusted-proxy. Any other value (including the never-implemented "password", or a typo like "tokenn") is refused when the config loads rather than silently admitting every request; the startup error names the supported modes.

/health and /ready never require a token. Cross-origin browser requests are governed by CORS configuration regardless of auth mode.

Liveness and Readiness

Method Path Purpose
GET /health, /healthz Liveness probe — {"ok": true, "status": "live"}.
GET /ready, /readyz Readiness probe — 503 until the gateway is ready.

These require no auth and are safe for load balancers and container probes.

Core Endpoints

Method Path Purpose
GET /api/config Effective gateway configuration.
GET /api/system/status Version, uptime, active provider, auth mode, plus circuitBreaker (the active provider's breaker) and circuitBreakers (every tracked provider).
GET /api/sessions List sessions.
POST /api/chat Send a chat turn. Body: message (required), sessionKey (optional).
GET /api/chat/history?sessionKey=<key> Fetch a session transcript.
GET /api/agents List durable agents.
GET /api/cron List scheduled jobs.
GET /api/usage Token usage and cost breakdown.
GET /metrics Prometheus metrics exposition (observability.metrics_path).

Channels

Method Path Purpose
GET /api/channels/status Channel connection status.
POST /api/channels/logout Log a channel out.

Approvals and Permissions

Method Path Purpose
GET /api/approvals Pending approvals + current mode/patterns.
POST /api/approvals/settings Set mode (prompt / auto-approve / auto-deny).
POST /api/approvals/resolve Approve or deny a pending item.
POST /api/elevated-mode Set per-session elevated mode (admitted Control connection only).

GET /api/approvals serializes every pending command and its arguments, so it is rate limited per client IP like the rest of /api/* — just in its own bucket, because the Web UI polls it every 1.5s. The cap is AGENTOS_RATE_APPROVALS_MAX_REQUESTS (default 300 per AGENTOS_RATE_WINDOW_SECONDS, i.e. 300/min), which clears several open tabs. Raise it only if you run more consoles than that against one gateway.

Files and Media

Method Path Purpose
POST /api/v1/files/upload Upload a file; returns an opaque id for chat.send.
GET /api/v1/attachments/{sha256} Fetch an attachment by content hash.
GET /api/v1/artifacts/{artifact_id} Fetch a generated artifact.
POST /api/audio/transcribe Transcribe audio to text.

Streaming (WebSocket)

For streaming turns and live events, connect to the WebSocket route:

ws://127.0.0.1:18791/ws

The WebSocket carries the same JSON-RPC methods the HTTP endpoints dispatch to, plus server-pushed events. It is one route on the same app — the REST surface above sits alongside it. See mcp-server.md for a bridge that uses this transport.

Projects (session groups with shared knowledge) are WebSocket-only: projects.create / projects.list / projects.get / projects.update / projects.delete (params use projectId, agentId, name, knowledge; delete responds with sessionsCleared — sessions are detached, not deleted). projects.update writes only the fields you pass and accepts an optional expectedUpdatedAt (the updatedAt you last read): when the row changed in between, the call fails with code project.conflict instead of silently overwriting the other writer's edit. sessions.create accepts an optional projectId, sessions.patch moves a session with projectId (explicit null detaches), and sessions.list accepts a projectId filter and emits project_id/projectId on every row. Project CRUD broadcasts a projects.changed event to connected clients.

Environment variables (env.*)

Control-surface only. Values never appear in a listing.

Method Purpose
env.list Every known variable: name, set/unset, source, description, owner, and a masked value.
env.set Write one variable. Returns its new state without echoing the value.
env.unset Remove one variable from ~/.agentos/.env.
env.reveal Return one real value. Rate limited to 5 per 30s and written to the audit log.

Writes are refused for names that steer subprocess execution or AgentOS runtime posture; see configuration.md. env.set and env.unset report restartRequired per variable — provider clients are built at boot with the key they had then, while other variables are picked up by the next process AgentOS spawns.

Example

On the default loopback bind these work as-is, no token needed:

# Liveness
curl http://127.0.0.1:18791/health

# System status
curl http://127.0.0.1:18791/api/system/status

# Send a chat turn (message is required; sessionKey is optional)
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"sessionKey": "agent:main:webchat:default", "message": "hello"}' \
  http://127.0.0.1:18791/api/chat

When the gateway runs with auth.mode = "token" (any public bind), add the token to each /api/* call:

curl -H "Authorization: Bearer $AGENTOS_TOKEN" \
  https://gateway.example.com/api/system/status

Source

The full route table is defined in create_gateway_app: src/agentos/gateway/app.py (the routes list). File-and-media routes are registered just below it via register_upload_routes, register_attachment_routes, register_artifact_routes, and register_audio_transcription_routes.

Read next:

Docs index · Product guide · Improve this page · Report a docs issue