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.

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

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]