API Reference

Authorization: Bearer <jwt-token>

Liveness probe. Returns uptime.

{ "status": "ok", "uptime": "4h32m10s" }

Readiness probe. Pings the database and returns ready status.

// 200 OK
{ "status": "ready" }

// 503 Service Unavailable
{ "status": "not_ready", "error": "db ping failed" }

Returns the configured auth provider. No authentication required.

{ "provider": "builtin" }

Authenticate with username and password. Only available when provider is 'builtin'. Rate limited to 5 req/s per IP.

Request body:

{ "username": "admin", "password": "admin" }

Response:

{ "token": "eyJhbGciOiJIUzI1NiIs..." }

Returns the authenticated user's identity.

{ "id": "user-uuid", "username": "admin", "role": "admin" }

List agent endpoints visible to the current user. When default_endpoint_access is 'none', non-admin users only see explicitly permitted endpoints.

[
  {
    "id": "ep-uuid",
    "runtime_id": "rt-uuid",
    "org_id": "default",
    "profile": "claude-code",
    "name": "Claude Code (prod)",
    "tags": "{}",
    "caps": "{"native_session_ids":false,"turn_completion":true,"resume_attach":false,"exec_model":"interactive"}",
    "security": "{"permission_mode":"strict","allowed_tools":["Bash","Read"]}",
    "online": true
  }
]

Create a new session on an endpoint. Checks endpoint permissions and max session limits.

Request body:

{ "endpoint_id": "ep-uuid" }

Response (201 Created):

{
  "id": "session-uuid",
  "endpoint_id": "ep-uuid",
  "user_id": "user-uuid",
  "state": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List all sessions owned by the current user.

[
  {
    "id": "session-uuid",
    "endpoint_id": "ep-uuid",
    "user_id": "user-uuid",
    "state": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:32:00Z"
  }
]

Fetch message history for a session. Supports pagination via query params. Verifies session ownership (owner or admin).

Query parameters:

[
  {
    "id": "msg-uuid",
    "session_id": "session-uuid",
    "seq": 1,
    "direction": "user",
    "channel": "stdin",
    "content": "Hello, agent!",
    "ts": "2024-01-15T10:30:05Z"
  },
  {
    "id": "msg-uuid-2",
    "session_id": "session-uuid",
    "seq": 2,
    "direction": "agent",
    "channel": "stdout",
    "content": "Hello! How can I help you?",
    "ts": "2024-01-15T10:30:06Z"
  }
]

Close a session. Only the session owner can close it. Broadcasts session.closed to WebSocket subscribers.

{ "status": "closed" }

Upload a file to a session. Multipart form data with a 'file' field. Max 10MB by default. The hub stores the file and forwards it to the runtime as a base64-encoded WebSocket message.

Response (201 Created):

{
  "file_id": "file-uuid",
  "name": "input.csv",
  "mime_type": "text/csv",
  "size": 1024
}

Download a file by its ID. Returns the file with appropriate Content-Type and Content-Disposition headers.

Returns the binary file content with headers:

Content-Type: text/csv
Content-Disposition: attachment; filename="output.csv"

Runtime WebSocket connection. Authentication is handled inside the connection via the runtime.hello message. See the WebSocket Protocol docs.

The runtime sends a runtime.hello message immediately after connecting, which includes the runtime token and endpoint registrations.

Client WebSocket connection. The JWT token is sent as a query parameter or in the first message. See the WebSocket Protocol docs.

Used for real-time message streaming, session subscriptions, permission prompts, and session state updates.

List all registered runtimes with their online/offline status.

[
  {
    "id": "rt-uuid",
    "org_id": "default",
    "name": "prod-runtime",
    "online": true,
    "last_seen": "2024-01-15T10:30:00Z"
  }
]

List all users in the organization. Password hashes are stripped from the response.

[
  {
    "id": "user-uuid",
    "org_id": "default",
    "username": "admin",
    "role": "admin",
    "created_at": "2024-01-15T10:00:00Z"
  }
]

Create a new user. Only available with builtin auth provider. Username: 3-64 chars, password: 8-128 chars.

Request body:

{ "username": "alice", "password": "secure-password", "role": "user" }

Grant a user access to an endpoint. Only relevant when default_endpoint_access is 'none'.

{ "user_id": "user-uuid", "endpoint_id": "ep-uuid" }

Revoke a user's access to an endpoint.

{ "user_id": "user-uuid", "endpoint_id": "ep-uuid" }

List endpoint IDs a user has been granted access to.

{ "user_id": "user-uuid", "endpoint_ids": ["ep-uuid-1", "ep-uuid-2"] }

List all sessions across all users in the organization.

Returns the same format as /api/sessions but includes sessions from all users.

Force-close any session. Logs a session.admin_close audit event.

{ "status": "closed" }

List all endpoints with runtime info, security config, and any hub-side config overrides.

[
  {
    "id": "ep-uuid",
    "org_id": "default",
    "runtime_id": "rt-uuid",
    "runtime_name": "prod-runtime",
    "runtime_online": true,
    "profile": "claude-code",
    "name": "Claude Code (prod)",
    "tags": {},
    "caps": { "turn_completion": true, "exec_model": "interactive" },
    "security": { "permission_mode": "strict" },
    "config_override": null
  }
]

Get the hub-side config override for an endpoint.

{
  "endpoint_id": "ep-uuid",
  "org_id": "default",
  "security": "{}",
  "limits": "{}",
  "updated_by": "user-uuid",
  "updated_at": "2024-01-15T12:00:00Z"
}

Set or update a hub-side config override for an endpoint. The override is pushed to the connected runtime in real-time.

Request body:

{
  "security": {
    "permission_mode": "strict",
    "allowed_tools": ["Bash", "Read", "Write"],
    "allowed_paths": ["/home/user/project"],
    "denied_paths": ["/etc", "/root"]
  },
  "limits": {
    "max_sessions": 5,
    "session_timeout": "1h",
    "idle_timeout": "10m"
  }
}

Response:

{ "status": "saved", "pushed_to_runtime": true }

Query audit events with optional filtering. Supports pagination and prefix-match on action.

Query parameters:

Response:

[
  {
    "id": "audit-uuid",
    "org_id": "default",
    "action": "permission.granted",
    "user_id": "user-uuid",
    "session_id": "session-uuid",
    "endpoint_id": "ep-uuid",
    "detail": { "request_id": "req-uuid", "tool": "Bash" },
    "created_at": "2024-01-15T10:31:05Z"
  }
]

Event types:

# Login
TOKEN=$(curl -s -X POST http://localhost:8090/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r .token)

# List endpoints
curl -s http://localhost:8090/api/endpoints \
  -H "Authorization: Bearer $TOKEN" | jq .

# Create session
SESSION=$(curl -s -X POST http://localhost:8090/api/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"endpoint_id":"my-endpoint-id"}' | jq -r .id)

# Get messages
curl -s "http://localhost:8090/api/sessions/$SESSION/messages?limit=50" \
  -H "Authorization: Bearer $TOKEN" | jq .

curl -X POST "http://localhost:8090/api/sessions/$SESSION/files" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/input.csv"

curl -s "http://localhost:8090/api/admin/audit?action=permission.&limit=20" \
  -H "Authorization: Bearer $TOKEN" | jq .

{ "error": "invalid credentials" }