goclaw/docs/18-http-api.md

18 — HTTP REST API

GoClaw exposes a comprehensive HTTP REST API alongside the WebSocket RPC protocol. All endpoints are served from the same gateway server and share authentication, rate limiting, and i18n infrastructure.

Interactive documentation is available at /docs (Swagger UI) and the raw OpenAPI 3.0 spec at /v1/openapi.json.

---

1. Authentication

All HTTP endpoints (except /health) require authentication via Bearer token in the Authorization header:

Authorization: Bearer <token>

Two token types are accepted:

Type	Format	Scope
Gateway token	Configured in config.json	Full admin access
API key	goclaw_ + 32 hex chars	Scoped by key permissions

API keys are hashed with SHA-256 before lookup — the raw key is never stored. See 20 — API Keys & Auth for details.

Some endpoints accept the token as a query parameter ?token=<token> for use in <img> and <audio> tags (e.g., /v1/files/, /v1/media/).

Common Headers

Header	Purpose
Authorization	Bearer token for authentication
X-GoClaw-User-Id	External user ID for multi-tenant context
X-GoClaw-Agent-Id	Agent identifier for scoped operations
Accept-Language	Locale (en, vi, zh) for i18n error messages
Content-Type	application/json for request bodies

---

2. Chat Completions

OpenAI-compatible chat API for programmatic access to agents.

POST /v1/chat/completions

{
  "model": "goclaw:agent-id-or-key",
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "stream": false,
  "user": "optional-user-id"
}

Response (non-streaming):

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 10, "completion_tokens": 20, "total_tokens": 30}
}

Streaming: Set "stream": true to receive Server-Sent Events (SSE) with data: {...} chunks, terminated by data: [DONE].

Rate limiting: Per-IP when rate_limit_rpm is configured.

---

3. OpenResponses Protocol

POST /v1/responses

Alternative response-based protocol (compatible with OpenAI Responses API). Accepts the same auth and returns structured response objects.

---

4. Agents

CRUD operations for agent management. Requires X-GoClaw-User-Id header for multi-tenant context.

Method	Path	Description	Auth
GET	/v1/agents	List agents accessible by user	Bearer
POST	/v1/agents	Create new agent	Bearer
GET	/v1/agents/{id}	Get agent by ID or key	Bearer
PUT	/v1/agents/{id}	Update agent (owner only)	Bearer
DELETE	/v1/agents/{id}	Delete agent (owner only)	Bearer

Shares

Method	Path	Description
GET	/v1/agents/{id}/shares	List agent shares
POST	/v1/agents/{id}/shares	Share agent with user
DELETE	/v1/agents/{id}/shares/{userID}	Revoke share

Agent Actions

Method	Path	Description
POST	/v1/agents/{id}/regenerate	Regenerate agent config with custom prompt
POST	/v1/agents/{id}/resummon	Retry initial LLM summoning

Predefined Agent Instances

Method	Path	Description
GET	/v1/agents/{id}/instances	List user instances
GET	/v1/agents/{id}/instances/{userID}/files	List user context files
GET	/v1/agents/{id}/instances/{userID}/files/{fileName}	Get specific user context file
PUT	/v1/agents/{id}/instances/{userID}/files/{fileName}	Update user file (USER.md only)
PATCH	/v1/agents/{id}/instances/{userID}/metadata	Update instance metadata

Wake (External Trigger)

POST /v1/agents/{id}/wake

{
  "message": "Process new data",
  "session_key": "optional-session",
  "user_id": "optional-user",
  "metadata": {}
}

Response: {content, run_id, usage?}. Used by orchestrators (n8n, Paperclip) to trigger agent runs.

---

5. Skills

Method	Path	Description
GET	/v1/skills	List all skills
POST	/v1/skills/upload	Upload ZIP with SKILL.md (20 MB limit)
GET	/v1/skills/{id}	Get skill details
PUT	/v1/skills/{id}	Update skill metadata
DELETE	/v1/skills/{id}	Delete skill (not system skills)
POST	/v1/skills/{id}/toggle	Toggle skill enabled/disabled state

Skill Grants

Method	Path	Description
POST	/v1/skills/{id}/grants/agent	Grant skill to agent
DELETE	/v1/skills/{id}/grants/agent/{agentID}	Revoke from agent
POST	/v1/skills/{id}/grants/user	Grant skill to user
DELETE	/v1/skills/{id}/grants/user/{userID}	Revoke from user

Agent Skills

Method	Path	Description
GET	/v1/agents/{agentID}/skills	List skills with grant status for agent

Skill Files & Dependencies

Method	Path	Description
GET	/v1/skills/{id}/versions	List available versions
GET	/v1/skills/{id}/files	List files in skill
GET	/v1/skills/{id}/files/{path...}	Read file content
POST	/v1/skills/rescan-deps	Rescan runtime dependencies
POST	/v1/skills/install-deps	Install all missing deps
POST	/v1/skills/install-dep	Install single dependency
GET	/v1/skills/runtimes	Check runtime availability

---

6. Providers

LLM provider management. API keys are encrypted with AES-256-GCM in the database and masked in responses.

Method	Path	Description
GET	/v1/providers	List providers (keys masked)
POST	/v1/providers	Create provider
GET	/v1/providers/{id}	Get provider
PUT	/v1/providers/{id}	Update provider
DELETE	/v1/providers/{id}	Delete provider

Provider Verification & Models

Method	Path	Description
POST	/v1/providers/{id}/verify	Test provider+model with minimal LLM call
GET	/v1/providers/{id}/models	Proxy to upstream provider model list
GET	/v1/providers/claude-cli/auth-status	Check Claude CLI login status

Supported types: anthropic_native, openai_compat, chatgpt_oauth, gemini_native, dashscope, bailian, minimax, claude_cli, acp

---

7. Sessions

Method	Path	Description
GET	/v1/sessions	List sessions (paginated)
GET	/v1/sessions/{key}	Get session with messages
DELETE	/v1/sessions/{key}	Delete session
POST	/v1/sessions/{key}/reset	Clear session messages
PATCH	/v1/sessions/{key}	Update label, model, metadata

---

8. MCP Servers

Model Context Protocol server management.

Server CRUD

Method	Path	Description
GET	/v1/mcp/servers	List servers with agent grant counts
POST	/v1/mcp/servers	Create MCP server
GET	/v1/mcp/servers/{id}	Get server details
PUT	/v1/mcp/servers/{id}	Update server
DELETE	/v1/mcp/servers/{id}	Delete server
POST	/v1/mcp/servers/test	Test connection (no save)
GET	/v1/mcp/servers/{id}/tools	List runtime-discovered tools

Agent Grants

Method	Path	Description
GET	/v1/mcp/servers/{id}/grants	List grants for server
POST	/v1/mcp/servers/{id}/grants/agent	Grant to agent
DELETE	/v1/mcp/servers/{id}/grants/agent/{agentID}	Revoke from agent
GET	/v1/mcp/grants/agent/{agentID}	List agent's server grants

User Grants

Method	Path	Description
POST	/v1/mcp/servers/{id}/grants/user	Grant to user
DELETE	/v1/mcp/servers/{id}/grants/user/{userID}	Revoke from user

Access Requests

Method	Path	Description
POST	/v1/mcp/requests	Create access request
GET	/v1/mcp/requests	List pending requests
POST	/v1/mcp/requests/{id}/review	Approve/deny request

Grants support tool_allow and tool_deny JSON arrays for fine-grained tool filtering.

---

9. Tools

Built-in Tools

Method	Path	Description
GET	/v1/tools/builtin	List all built-in tools
GET	/v1/tools/builtin/{name}	Get tool definition
PUT	/v1/tools/builtin/{name}	Update enabled/settings

Custom Tools

Method	Path	Description
GET	/v1/tools/custom	List custom tools (paginated)
POST	/v1/tools/custom	Create custom tool
GET	/v1/tools/custom/{id}	Get tool details
PUT	/v1/tools/custom/{id}	Update tool
DELETE	/v1/tools/custom/{id}	Delete tool

Query parameters for list: agent_id, search, limit, offset

Direct Invocation

POST /v1/tools/invoke

{
  "tool": "web_fetch",
  "action": "fetch",
  "args": {"url": "https://example.com"},
  "dryRun": false,
  "agentId": "optional",
  "channel": "optional",
  "chatId": "optional",
  "peerKind": "direct"
}

Set "dryRun": true to return tool schema without execution.

---

10. Memory

Per-agent vector memory using pgvector.

Method	Path	Description
GET	/v1/memory/documents	List all documents globally
GET	/v1/agents/{agentID}/memory/documents	List documents for agent
GET	/v1/agents/{agentID}/memory/documents/{path...}	Get document details
PUT	/v1/agents/{agentID}/memory/documents/{path...}	Put/update document
DELETE	/v1/agents/{agentID}/memory/documents/{path...}	Delete document
GET	/v1/agents/{agentID}/memory/chunks	List chunks for document
POST	/v1/agents/{agentID}/memory/index	Index single document
POST	/v1/agents/{agentID}/memory/index-all	Index all documents
POST	/v1/agents/{agentID}/memory/search	Semantic search

Optional query parameter ?user_id= for per-user scoping.

---

11. Knowledge Graph

Per-agent entity-relation graph.

Method	Path	Description
GET	/v1/agents/{agentID}/kg/entities	List/search entities (BM25)
GET	/v1/agents/{agentID}/kg/entities/{entityID}	Get entity with relations
POST	/v1/agents/{agentID}/kg/entities	Upsert entity
DELETE	/v1/agents/{agentID}/kg/entities/{entityID}	Delete entity
POST	/v1/agents/{agentID}/kg/traverse	Traverse graph (max depth 3)
POST	/v1/agents/{agentID}/kg/extract	LLM-powered entity extraction
GET	/v1/agents/{agentID}/kg/stats	Knowledge graph statistics
GET	/v1/agents/{agentID}/kg/graph	Full graph for visualization

---

12. Channels

Channel Instances

Method	Path	Description
GET	/v1/channels/instances	List instances (paginated)
POST	/v1/channels/instances	Create instance
GET	/v1/channels/instances/{id}	Get instance
PUT	/v1/channels/instances/{id}	Update instance
DELETE	/v1/channels/instances/{id}	Delete instance (not default)

Contacts

Method	Path	Description
GET	/v1/contacts	List contacts (paginated)
GET	/v1/contacts/resolve?ids=...	Resolve contacts by IDs (max 100)

Group Writers

Method	Path	Description
GET	/v1/channels/instances/{id}/writers/groups	List group file writers
GET	/v1/channels/instances/{id}/writers	List writers for group
POST	/v1/channels/instances/{id}/writers	Add writer to group
DELETE	/v1/channels/instances/{id}/writers/{userId}	Remove writer

Supported channels: telegram, discord, slack, whatsapp, zalo_oa, zalo_personal, feishu

Credentials are masked in HTTP responses.

---

13. Pending Messages

Method	Path	Description
GET	/v1/pending-messages	List all groups with titles
GET	/v1/pending-messages/messages	List messages by channel+key
DELETE	/v1/pending-messages	Delete message group
POST	/v1/pending-messages/compact	LLM-based summarization (async, 202)

Compaction runs in the background. Falls back to hard delete if no LLM provider is available.

---

14. Delegations

Agent task delegation and authorization history.

Method	Path	Description
GET	/v1/delegations	List delegations (paginated, filterable)
GET	/v1/delegations/{id}	Get delegation record

Filters: source_agent_id, target_agent_id, team_id, user_id, status, limit, offset

---

15. Team Events

Team activity and audit trail.

Method	Path	Description
GET	/v1/teams/{id}/events	List team events (paginated)

---

16. Secure CLI Credentials

CLI authentication credentials for secure command execution. Requires admin role (full gateway token or empty gateway token in dev/single-user mode).

Method	Path	Description
GET	/v1/cli-credentials	List all credentials
POST	/v1/cli-credentials	Create new credential
GET	/v1/cli-credentials/{id}	Get credential details
PUT	/v1/cli-credentials/{id}	Update credential
DELETE	/v1/cli-credentials/{id}	Delete credential
GET	/v1/cli-credentials/presets	Get preset credential templates
POST	/v1/cli-credentials/{id}/test	Test credential connection (dry-run)

---

17. Runtime & Packages Management

Manage system (apk), Python (pip), and Node (npm) package installation in the runtime container. Requires authentication. When GOCLAW_GATEWAY_TOKEN is empty (dev/single-user mode), all users get admin role and can manage packages.

List Installed Packages

GET /v1/packages

Returns all installed packages grouped by category.

Response:

{
  "system": [
    {"name": "github-cli", "version": "2.72.0-r6"},
    {"name": "curl", "version": "8.9.1-r1"}
  ],
  "pip": [
    {"name": "pandas", "version": "2.0.0"},
    {"name": "requests", "version": "2.31.0"}
  ],
  "npm": [
    {"name": "typescript", "version": "5.1.0"},
    {"name": "docx", "version": "8.12.0"}
  ]
}

Install Package

POST /v1/packages/install

Request:

{
  "package": "github-cli"
}

Package name can optionally include prefix: "pip:pandas" or "npm:typescript". Without prefix, defaults to system (apk).

Validation: Package names must match ^[a-zA-Z0-9@][a-zA-Z0-9._+\-/@]*$ (max 4096 bytes). Names starting with - are rejected to prevent argument injection.

Response:

{
  "ok": true,
  "error": ""
}

Category	Manager	Behavior
System (apk)	root-privileged pkg-helper	Sent to /tmp/pkg.sock, persisted to /app/data/.runtime/apk-packages for container recreates
Python (pip)	direct install	Installs to $PIP_TARGET (writable runtime dir) with PIP_BREAK_SYSTEM_PACKAGES=1
Node (npm)	direct install	Installs globally to $NPM_CONFIG_PREFIX (writable runtime dir)

Uninstall Package

POST /v1/packages/uninstall

Same format as install. System packages are removed from persist file and container state.

Response:

{
  "ok": true,
  "error": ""
}

Check Runtime Availability

GET /v1/packages/runtimes

Check if Python and Node runtimes are available in the container.

Response:

{
  "python": true,
  "node": true
}

---

18. Traces & Costs

LLM call tracing and cost analysis.

Traces

Method	Path	Description
GET	/v1/traces	List traces (paginated, filterable)
GET	/v1/traces/{traceID}	Get trace with spans
GET	/v1/traces/{traceID}/export	Export trace tree (gzipped JSON)

Filters: agent_id, user_id, session_key, status, channel

Costs

Method	Path	Description
GET	/v1/costs/summary	Cost summary by agent/time range

---

19. Usage & Analytics

Method	Path	Description
GET	/v1/usage/timeseries	Time-series usage points
GET	/v1/usage/breakdown	Breakdown by provider/model/channel
GET	/v1/usage/summary	Summary with period comparison

Query params: from, to (RFC 3339), agent_id, provider, model, channel, group_by

Periods: 24h, today, 7d, 30d

---

20. Activity & Audit

Method	Path	Description
GET	/v1/activity	List activity audit logs (filterable)

---

21. Storage

Workspace file management.

Method	Path	Description
GET	/v1/storage/files	List files with depth limiting
GET	/v1/storage/files/{path...}	Read file (JSON or raw)
DELETE	/v1/storage/files/{path...}	Delete file/directory
GET	/v1/storage/size	Stream storage size (Server-Sent Events, cached 60 min)

Query parameters:

• ?raw=true — Serve native MIME type instead of JSON
• ?depth=N — Limit directory traversal depth

Security: Protected directories skills/ and skills-store/ cannot be deleted. Path traversal and symlink attacks are blocked.

---

22. Media

Method	Path	Description
POST	/v1/media/upload	Upload file (multipart, 50 MB limit)
GET	/v1/media/{id}	Serve media by ID with caching

---

23. Files

Method	Path	Description
GET	/v1/files/{path...}	Serve workspace file by path

Auth via Bearer token or ?token= query param (for <img> tags). MIME type auto-detected. Path traversal blocked.

---

24. API Keys

Admin-only endpoints for managing gateway API keys. See 20 — API Keys & Auth for the full authentication and authorization model.

Method	Path	Description
GET	/v1/api-keys	List all API keys (masked)
POST	/v1/api-keys	Create API key (returns raw key once)
POST	/v1/api-keys/{id}/revoke	Revoke API key

Create Request

{
  "name": "ci-deploy",
  "scopes": ["operator.read", "operator.write"],
  "expires_in": 2592000
}

Create Response

{
  "id": "01961234-...",
  "name": "ci-deploy",
  "prefix": "goclaw_a1b2c3d4",
  "key": "goclaw_a1b2c3d4e5f6...full-key",
  "scopes": ["operator.read", "operator.write"],
  "expires_at": "2026-04-14T12:00:00Z",
  "created_at": "2026-03-15T12:00:00Z"
}

The key field is only returned in the create response. Subsequent list/get calls show only the prefix.

---

25. OAuth

Method	Path	Description
GET	/v1/auth/openai/status	Check OpenAI auth status
POST	/v1/auth/openai/start	Start OAuth flow
POST	/v1/auth/openai/callback	Manual callback handler
POST	/v1/auth/openai/logout	Revoke token

---

26. System

Method	Path	Description
GET	/health	Health check (no auth)
GET	/v1/openapi.json	OpenAPI 3.0 spec
GET	/docs	Swagger UI

Health Response

{
  "status": "ok",
  "protocol": 3
}

---

27. MCP Bridge

Exposes GoClaw tools to Claude CLI via streamable HTTP at /mcp/bridge. Only listens on localhost. Protected by gateway token with HMAC-signed context headers.

Header	Purpose
X-Agent-ID	Agent context for tool execution
X-User-ID	User context
X-Channel	Channel routing
X-Chat-ID	Chat routing
X-Peer-Kind	direct or group
X-Bridge-Sig	HMAC signature over all context fields

---

Error Responses

All endpoints return errors in a consistent JSON format:

{
  "error": "human-readable error message"
}

Error messages are localized based on the Accept-Language header. HTTP status codes follow standard conventions:

Code	Meaning
400	Bad request (invalid JSON, missing fields)
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions)
404	Not found
409	Conflict (duplicate name, version mismatch)
429	Rate limited
500	Internal server error

---

Notes on WebSocket-Only Endpoints

The following operations are only available via WebSocket RPC, not HTTP:

• Sessions: List, preview, patch, delete, reset (use WebSocket method sessions.*)
• Cron jobs: List, create, update, delete, logs (use WebSocket method cron.*)
• Send messages: Send to channels (use WebSocket method send.*)
• Config management: Get, apply, patch (use WebSocket method config.*)

These endpoints require an active WebSocket connection to the /ws endpoint with proper authentication and agent context.

---

File Reference

File	Purpose
internal/http/chat_completions.go	OpenAI-compatible chat API
internal/http/responses.go	OpenResponses protocol
internal/http/agents.go	Agent CRUD + shares + instances + files
internal/http/skills.go	Skill management + grants + versions
internal/http/providers.go	Provider CRUD + verification + models
internal/http/mcp.go	MCP server management + grants + requests
internal/http/custom_tools.go	Custom tool CRUD
internal/http/builtin_tools.go	Built-in tool management
internal/http/tools_invoke.go	Direct tool invocation
internal/http/channel_instances.go	Channel instance management + contacts
internal/http/memory_handlers.go	Memory document management + search + indexing
internal/http/knowledge_graph.go	Knowledge graph API (entities, relations, traversal)
internal/http/traces.go	LLM trace listing + export
internal/http/usage.go	Usage analytics + costs
internal/http/activity.go	Activity audit log
internal/http/storage.go	Workspace file management + size calculation
internal/http/media_upload.go	Media file upload
internal/http/media_serve.go	Media file serving
internal/http/files.go	Workspace file serving
internal/http/api_keys.go	API key management + revoke
internal/http/delegations.go	Delegation history API
internal/http/team_events.go	Team event history API
internal/http/secure_cli.go	CLI credential management
internal/http/packages.go	Runtime package management (apk/pip/npm)
internal/http/pending_messages.go	Pending message groups + compaction
internal/http/oauth.go	OAuth authentication flows
internal/http/openapi.go	OpenAPI spec + Swagger UI
internal/http/auth.go	Authentication helpers
internal/gateway/server.go	HTTP mux and route wiring
cmd/gateway.go	Handler instantiation and wiring
cmd/pkg-helper/main.go	Root-privileged system package helper (apk add/del)
internal/skills/package_lister.go	Query installed packages from apk/pip3/npm