Agent Gateway API Reference

GET /health No Auth

Returns server status, version, uptime, and active session count.

Response

{
  "status": "ok",
  "version": "0.1.0",
  "uptime": 3600,
  "sessions": 2
}

Example

curl http://localhost:3001/health

POST /v1/query Auth Required

Runs a Claude agent query. Returns an NDJSON stream (application/x-ndjson) of events as the agent works. The connection stays open until the query completes or the client disconnects.

Request Body

Response (NDJSON stream)

Each line is a JSON object with a seq (sequence number) and type. See NDJSON Event Reference for all event types.

{"seq":0,"type":"text","content":"Let me check the disk usage..."}
{"seq":1,"type":"tool_use","toolName":"Bash","toolUseId":"tu_abc","input":"df -h","startedAt":1711461600000}
{"seq":2,"type":"tool_result","toolName":"Bash","toolUseId":"tu_abc","output":"/dev/sda1  50G  35G  15G  70% /","durationMs":245}
{"seq":3,"type":"text","content":"The disk is at 70% usage."}
{"seq":4,"type":"done","inputTokens":1250,"outputTokens":340,"costUsd":0.0087,"sessionId":"abc-123","context":{"usedTokens":1590,"contextWindow":200000,"percentUsed":0.8,"cacheReadTokens":0,"cacheCreationTokens":0}}

Example

curl -N -X POST http://localhost:3001/v1/query \
  -H "Authorization: Bearer sk-gw-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "queryId": "q-001",
    "prompt": "What files are in the current directory?",
    "sessionId": "session-1",
    "systemPrompt": "You are a helpful assistant."
  }'

GET /v1/query/:queryId/events Auth Required

Replays cached events for a query. If the query is still running, the connection stays open and streams new events in real time. Supports resuming from a specific sequence number.

Query Parameters

Response

NDJSON stream identical to POST /v1/query. Returns 404 if the queryId is not found or has expired from the cache.

Example

# Replay all events
curl -N http://localhost:3001/v1/query/q-001/events \
  -H "Authorization: Bearer sk-gw-abc123"

# Resume from sequence 5
curl -N "http://localhost:3001/v1/query/q-001/events?after=5" \
  -H "Authorization: Bearer sk-gw-abc123"

GET /v1/sessions Auth Required

Lists all active sessions with their model and last-used timestamp.

Response

{
  "sessions": [
    {
      "id": "session-1",
      "model": "claude-sonnet-4-20250514",
      "lastUsed": 1711461600000
    }
  ],
  "count": 1
}

Example

curl http://localhost:3001/v1/sessions \
  -H "Authorization: Bearer sk-gw-abc123"

DELETE /v1/sessions/:id Auth Required

Deletes a session by ID. Returns 404 if the session does not exist.

Response

{"deleted": true}

Example

curl -X DELETE http://localhost:3001/v1/sessions/session-1 \
  -H "Authorization: Bearer sk-gw-abc123"

GET /v1/settings Auth Required

Returns current session settings.

Response

{"sessionIdleTimeoutMs": 0}

Example

curl http://localhost:3001/v1/settings \
  -H "Authorization: Bearer sk-gw-abc123"

PUT /v1/settings Auth Required

Updates session settings. Currently supports sessionIdleTimeoutMs.

Sessions

A session is a mapping from a client-provided sessionId to a Claude Agent SDK conversation session. Sessions maintain conversation context — follow-up queries sent with the same sessionId have access to all previous messages in that conversation. Sessions are persisted to SESSION_PERSIST_PATH and survive server restarts.

sessionIdleTimeoutMs

When set to 0 (the default), no cleanup runs and every unique sessionId stays in memory and on disk forever. This is convenient for long-lived conversational agents but means memory usage grows unboundedly if many distinct session IDs are used.

When set to a value greater than 0, the cleanup timer is activated. Any session that has not received a query within the configured duration is removed from memory and from disk. The next query that arrives with that sessionId starts a fresh session — all previous conversation context is lost.

Request Body

{"sessionIdleTimeoutMs": 3600000}

Response

{"sessionIdleTimeoutMs": 3600000}

Example

# Set 1-hour idle timeout (sessions idle for >1 h are evicted; check runs every 5 min)
curl -X PUT http://localhost:3001/v1/settings \
  -H "Authorization: Bearer sk-gw-abc123" \
  -H "Content-Type: application/json" \
  -d '{"sessionIdleTimeoutMs": 3600000}'

# Disable cleanup — sessions live forever (default)
curl -X PUT http://localhost:3001/v1/settings \
  -H "Authorization: Bearer sk-gw-abc123" \
  -H "Content-Type: application/json" \
  -d '{"sessionIdleTimeoutMs": 0}'

GET /v1/logging Auth Required

Returns the current log level.

Response

{"level": "info"}

Example

curl http://localhost:3001/v1/logging \
  -H "Authorization: Bearer sk-gw-abc123"

PUT /v1/logging Auth Required

Changes the log level at runtime. Valid levels: off, info, debug.

Request Body

{"level": "debug"}

Response

{"level": "debug", "previous": "info"}

Example

curl -X PUT http://localhost:3001/v1/logging \
  -H "Authorization: Bearer sk-gw-abc123" \
  -H "Content-Type: application/json" \
  -d '{"level": "debug"}'

POST /v1/ssh-keys Auth Required

Uploads an SSH key pair to the gateway container. The agent can then use SSH to connect to remote servers via Bash tool calls. Keys are written to ~/.ssh/ with proper permissions (600 for private, 644 for public). An SSH config is auto-generated with StrictHostKeyChecking accept-new.

Request Body

Response

{
  "status": "ok",
  "message": "SSH keys updated",
  "publicKey": "ssh-ed25519 AAAA... user@host"
}

Example

curl -X POST http://localhost:3001/v1/ssh-keys \
  -H "Authorization: Bearer sk-gw-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----",
    "filename": "id_ed25519"
  }'

POST /v1/workspace/git/clone

Clone a git repository into the workspace projects directory. If the target path already exists with a .git directory, performs a git pull instead.

Request Body

{
  "url": "git@github.com:org/repo.git",   // Required: repository URL
  "path": "my-project",                    // Required: relative path under projects/
  "branch": "main",                        // Optional: branch to clone
  "sshKey": "-----BEGIN OPENSSH..."        // Optional: SSH private key for auth
}

Response (200)

{
  "status": "cloned",    // or "pulled" if target already existed
  "path": "my-project",
  "branch": "main",
  "commit": "a1b2c3d"
}

Security

SSH keys are written to a temp file with 0600 permissions and deleted immediately after the git operation. Keys are never persisted on disk.

Example

curl -X POST http://localhost:3001/v1/workspace/git/clone \
  -H "Authorization: Bearer sk-gw-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "git@github.com:org/repo.git",
    "path": "my-project",
    "branch": "main"
  }'

POST /v1/workspace/git/pull

Pull latest changes for an existing repository.

Request Body

{
  "path": "my-project",                    // Required: relative path under projects/
  "sshKey": "-----BEGIN OPENSSH..."        // Optional: SSH private key for auth
}

Response (200)

{
  "status": "updated",   // or "up-to-date"
  "branch": "main",
  "commit": "a1b2c3d"
}

Example

curl -X POST http://localhost:3001/v1/workspace/git/pull \
  -H "Authorization: Bearer sk-gw-abc123" \
  -H "Content-Type: application/json" \
  -d '{"path": "my-project"}'

GET /v1/workspace/git/status?path=my-project

Get the git status of a project directory.

Query Parameters

path (required): relative path under projects/

Response (200) — repo exists

{
  "exists": true,
  "branch": "main",
  "commit": "a1b2c3d",
  "dirty": false,
  "lastCommitDate": "2026-03-29T10:00:00+02:00"
}

Response (200) — repo not found

{"exists": false}

Example

curl http://localhost:3001/v1/workspace/git/status?path=my-project \
  -H "Authorization: Bearer sk-gw-abc123"

GET /v1/auth/status Auth Required

Checks whether the Claude CLI inside the container has a valid Anthropic login. This is separate from the gateway's API key auth -- it determines whether the SDK can make API calls to Anthropic.

Response (logged in)

{"loggedIn": true, "email": "user@example.com"}

Response (not logged in)

{"loggedIn": false}

Example

curl http://localhost:3001/v1/auth/status \
  -H "Authorization: Bearer sk-gw-abc123"

POST /v1/auth/login Auth Required

Initiates the Anthropic OAuth login flow. Starts a Claude CLI session inside tmux, navigates through the login prompts, and returns the OAuth authorization URL. The user must open this URL in a browser, authorize, and copy the authorization code.

Response

{"url": "https://console.anthropic.com/oauth/authorize?..."}

Error (timeout)

{"error": "Timeout waiting for auth URL"}

Example

curl -X POST http://localhost:3001/v1/auth/login \
  -H "Authorization: Bearer sk-gw-abc123"

POST /v1/auth/submit-code Auth Required

Submits the OAuth authorization code obtained from the browser. The gateway sends it to the running Claude CLI tmux session and polls for login success. Requires a prior call to POST /v1/auth/login.

Request Body

Response (success)

{"success": true, "loggedIn": true, "email": "user@example.com"}

Error

{"error": "No auth login session running. Call POST /v1/auth/login first."}

Example

curl -X POST http://localhost:3001/v1/auth/submit-code \
  -H "Authorization: Bearer sk-gw-abc123" \
  -H "Content-Type: application/json" \
  -d '{"code": "ey..."}'

GET /v1/{section} Auth Required

Lists all files in the section. Returns a recursive file listing with path, size, and modification time.

Response

{
  "files": [
    {
      "path": "MEMORY.md",
      "size": 1234,
      "modified": "2026-03-26T10:00:00.000Z"
    },
    {
      "path": "project/notes.md",
      "size": 567,
      "modified": "2026-03-25T15:30:00.000Z"
    }
  ]
}

Example

curl http://localhost:3001/v1/memory \
  -H "Authorization: Bearer sk-gw-abc123"

GET /v1/{section}/{path} Auth Required

Reads a file. Returns application/json for .json files, text/plain for all others.

Example

curl http://localhost:3001/v1/memory/MEMORY.md \
  -H "Authorization: Bearer sk-gw-abc123"

PUT /v1/{section}/{path} Auth Required

Creates or overwrites a file. Parent directories are created automatically. Send the file content as the request body (JSON or plain text).

Response

{"status": "ok", "path": "memory/MEMORY.md"}

Example

# Write plain text
curl -X PUT http://localhost:3001/v1/memory/MEMORY.md \
  -H "Authorization: Bearer sk-gw-abc123" \
  -H "Content-Type: text/plain" \
  -d '# Agent Memory

This server manages web infrastructure.'

# Write JSON
curl -X PUT http://localhost:3001/v1/agents/config.json \
  -H "Authorization: Bearer sk-gw-abc123" \
  -H "Content-Type: application/json" \
  -d '{"name": "server-admin", "model": "claude-sonnet-4-20250514"}'

DELETE /v1/{section}/{path} Auth Required

Deletes a file. Returns 404 if the file does not exist.

Response

{"status": "ok"}

Example

curl -X DELETE http://localhost:3001/v1/memory/old-notes.md \
  -H "Authorization: Bearer sk-gw-abc123"

PUT /v1/tools/:name Auth Required

Registers a new tool or updates an existing one. Returns 201 for new tools, 200 for updates.

Request Body

Response (201 Created / 200 OK)

{
  "name": "lookup-customer",
  "description": "Look up a customer by email address",
  "input_schema": {
    "type": "object",
    "properties": {
      "email": { "type": "string", "description": "Customer email" }
    },
    "required": ["email"]
  },
  "webhook_url": "https://api.example.com/tools/lookup-customer",
  "timeout_ms": 30000
}

Example

curl -X PUT http://localhost:3001/v1/tools/lookup-customer \
  -H "Authorization: Bearer sk-gw-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Look up a customer by email address",
    "input_schema": {
      "type": "object",
      "properties": {
        "email": { "type": "string", "description": "Customer email" }
      },
      "required": ["email"]
    },
    "webhook_url": "https://api.example.com/tools/lookup-customer",
    "timeout_ms": 10000
  }'

GET /v1/tools Auth Required

Lists all registered tools.

Response

{
  "tools": [
    {
      "name": "lookup-customer",
      "description": "Look up a customer by email address",
      "input_schema": { "type": "object", "properties": { "email": { "type": "string" } } },
      "webhook_url": "https://api.example.com/tools/lookup-customer",
      "timeout_ms": 10000
    }
  ]
}

Example

curl http://localhost:3001/v1/tools \
  -H "Authorization: Bearer sk-gw-abc123"

GET /v1/tools/:name Auth Required

Returns a single tool definition. Returns 404 if the tool does not exist.

Example

curl http://localhost:3001/v1/tools/lookup-customer \
  -H "Authorization: Bearer sk-gw-abc123"

DELETE /v1/tools/:name Auth Required

Deletes a tool. Returns 204 on success, 404 if the tool does not exist.

Example

curl -X DELETE http://localhost:3001/v1/tools/lookup-customer \
  -H "Authorization: Bearer sk-gw-abc123"