API Reference
Everything an AI agent needs to use Cerver.
Base URL
https://gateway.cerver.ai
Authentication
Pass your API key in the Authorization header:
Authorization: Bearer ck_your_key
Auth
POST /v2/auth/loginLogin with email → returns api_key
GET /v2/auth/accountGet account info
GET /v2/auth/keysList API keys
POST /v2/auth/keysCreate API key
DELETE /v2/auth/keys/:prefixDelete API key
Sessions
POST /v2/sessionsCreate a session
GET /v2/sessionsList your sessions
GET /v2/sessions/:idGet session details + transcript
POST /v2/sessions/:id/runRun code
POST /v2/sessions/:id/run/streamStream code execution (SSE)
POST /v2/sessions/:id/inputSend input to session transcript
GET /v2/sessions/:id/metricsGet session metrics
POST /v2/sessions/:id/pausePause — release compute, keep session
POST /v2/sessions/:id/resumeResume on same or different compute
POST /v2/sessions/:id/spawnSpawn child session on new compute
DELETE /v2/sessions/:idTerminate (soft delete)
Computes
GET /v2/computesList private + shared computes
GET /v2/computes/:idGet compute details
POST /v2/computes/registerRegister local machine
POST /v2/computes/:id/heartbeatRefresh compute liveness
DELETE /v2/computes/:idUnregister compute
Account Providers
GET /v2/account/providersList enabled providers
POST /v2/account/providersEnable a provider with credentials
DELETE /v2/account/providers/:nameDisable a provider
Device Auth (for CLI/relay)
POST /v2/auth/deviceStart device login flow
GET /v2/auth/device?device_code=...Poll device login status
POST /v2/auth/approveApprove device + issue API key
Connect (WebSocket relay)
GET /v2/connect/wsOpen WebSocket for private compute
Meta
GET /v2/docsFull API documentation (JSON)
GET /API info + all endpoints
Quick Start
Everything you need to use Cerver as an AI agent.
How Cerver Works
You ask for a session. Cerver finds compute, provisions it, and gives you a session ID. You run code through the session. When done, pause it — come back later with full context. Need more compute? Spawn a child session. You never manage infrastructure.
0. Get an API key
Login with email to get one automatically:
curl -X POST https://gateway.cerver.ai/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'
→ Returns: {"account_id": "acct_...", "api_key": "ck_...", "name": "you"}
1. Create a session
Cerver picks the best available compute. Or specify preferences:
curl -X POST https://gateway.cerver.ai/v2/sessions \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "run tests for my project",
    "session_name": "test-run",
    "requirements": {
      "runtime": "shell",
      "persistence_level": "high",
      "timeout_minutes": 30
    }
  }'
→ Returns:
{
  "session_id": "5d2db690-...",
  "status": "ready",
  "provider": "cerver_local_provider",
  "compute_id": "comp_d9b34ac..."
}
To pin to a specific compute: add "target_compute_id": "comp_...". List available computes with GET /v2/computes.
2. Run code
curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/run \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "npm test"}'
→ Returns:
{
  "session_id": "5d2db690-...",
  "duration_ms": 4523,
  "result": { "stdout": "...", "stderr": "...", "exit_code": 0 }
}
Use /run/stream for streaming output (SSE).
3. Save work — pause
Releases compute but keeps the session (transcript, metadata).
curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/pause \
  -H "Authorization: Bearer ck_YOUR_KEY"
→ Returns: {"status": "paused"}. Compute is freed. Session record stays.
4. Come back — resume
Re-provisions compute. Can resume on a different machine.
curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/resume \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
→ Creates a new session linked to the paused one. Returns new session_id.
Get the transcript from the paused session: GET /v2/sessions/OLD_SESSION_ID → transcript[] array of {role, content, at}.
5. Need more compute — spawn
Create a child session from a running parent. Inherits compute by default.
curl -X POST https://gateway.cerver.ai/v2/sessions/PARENT_ID/spawn \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "run tests in parallel", "session_name": "test-child"}'
→ Returns child session with parent_session_id linked to parent.
To spawn on different compute: add "target_compute_id": "comp_...".
6. Clean up — terminate
curl -X DELETE https://gateway.cerver.ai/v2/sessions/SESSION_ID \
  -H "Authorization: Bearer ck_YOUR_KEY"
Releases compute, keeps session record for history.
Requirements reference
runtime"shell", "node", "python"
persistence_level"low", "medium", "high" — how long to keep files
timeout_minutesMax session duration (default 20)
package_installtrue/false — need npm/pip
public_previewtrue/false — need a public URL
Skill
A drop-in instruction set for any AI agent that uses Cerver — when to use it, how, and what to avoid.
Download skill.md View raw
Save as ~/.claude/skills/cerver/SKILL.md — Claude Code auto-loads it. Or drop the markdown into any agent's system prompt. Available agent-callable at https://cerver.ai/skill.md via WebFetch. 
Loading skill…
Overview
Your Cerver account at a glance.
Loading...
Computes
Your machines and shared providers.
Loading...
Sessions
Active, paused, and past sessions.
Loading...
Providers
Enable cloud compute providers with your own credentials.
Loading...
Add Provider
API Keys
Create and manage your Cerver API keys.
Loading...
Settings
Account configuration.