API Reference

Create and manage AI agents programmatically using the GoPilot API.

Base URL: https://api.gopilot.dev/v1

Authentication

Include your API key in the X-API-Key header:

X-API-Key: gopt_live_your_key_here

For OpenAI SDK compatibility, you can also use Authorization: Bearer gopt_live_...

Getting an API Key

Sign in to gopilot.dev
Go to Account → API Keys
Click Create New Key and choose your scopes
Copy the key immediately — it starts with gopt_live_ and won't be shown again

Scopes

Field	Type	Description
agents:read	scope	List and read agent details, logs
agents:write	scope	Create, update, start, stop, restart agents
agents:delete	scope	Delete agents
usage:read	scope	Read usage and cost metrics

Quickstart

Create your first agent with a single API call:

curl -X POST https://api.gopilot.dev/v1/agents \
  -H "X-API-Key: gopt_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "model": "anthropic/claude-sonnet-4-6",
    "description": "Handles customer support",
    "llm_keys": [
      { "provider": "anthropic", "api_key": "sk-ant-..." }
    ]
  }'

The agent starts provisioning immediately and returns once running (~10s). Poll GET /v1/agents/:id to check status.

Endpoints

Click any endpoint to expand its documentation.

Agent Runtimes

GoPilot supports two agent runtimes, selectable via runtime_kind on create. Both runtimes share the same v1 API surface; differences are mostly in what runs inside the VM.

Aspect	openclaw (default)	hermes
Runtime	Node.js (OpenClaw)	Python (Hermes by Nous Research)
Config format	JSON (/root/.openclaw/openclaw.json)	YAML (/workspace/config.yaml)
Secrets file	auth-profiles.json per agent	/workspace/.env
Workspace root	/root/.openclaw/workspace-main	/workspace
Multi-agent	Yes — separate workspace dirs per agent	No — single primary agent per VM
Dashboard	Not applicable	Optional in-VM dashboard on :9119
Model field shape	Provider-prefixed (e.g. anthropic/claude-sonnet-4-6)	Bare model name (e.g. claude-sonnet-4-6)
URL prefix	openclaw-<id>.agents.gopilot.dev	hermes-<id>.agents.gopilot.dev

If you don't specify runtime_kind, the agent will be created as openclaw. Workspace file names, channel configs, LLM keys, and chat protocol are the same across both runtimes.

Machine Sizes

Size	vCPUs	Memory	Use Case
small	1	2 GB	Simple chatbots, lightweight tasks
medium	2	4 GB	General purpose (default)
large	2	8 GB	Multi-channel agents, heavier workloads
xlarge	4	16 GB	Complex multi-agent systems

Supported Channels

Channel	Required Credentials
slack	`appToken` (Socket Mode), `botToken` (OAuth)
discord	`botToken`
telegram	`botToken` (from @BotFather)
whatsapp	None — paired via QR code after agent is running
email (gmail)	OAuth pairing — start with `POST /v1/agents/:id/channels/gmail/oauth/start`

Error Responses

All errors return a consistent JSON structure:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "name is required"
  }
}

Status	Type	Meaning
400	invalid_request_error	Missing or invalid field
401	authentication_error	Missing or invalid API key
403	authorization_error	API key lacks required scope
404	not_found_error	Agent not found
409	invalid_request_error	Agent is not running (start it first)
429	rate_limit_error	Too many requests
500	server_error	Internal server error

Agent Lifecycle

provisioning → running → paused (idle) → stopped (snapshot)

provisioning — VM is booting and gateway is starting (~8-10s)
running — Agent is live and accepting requests
paused — Idle agent with vCPUs frozen. Instant resume.
stopped — VM deallocated but snapshot preserved. Fast resume (~8s).
error — Something went wrong. Check logs.

Need help? [email protected]