# Cerver API - Quick Reference for AI Agents

## IMPORTANT: How to Get Started

To use Cerver, you need an API key. **Email verification is required** - you cannot fake an email.

### Step 1: Ask the user for their email address

### Step 2: Call the signup endpoint
```bash
curl -X POST https://api.cerver.ai/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

# Response:
{
  "success": true,
  "message": "Verification email sent! Check your inbox and click the link to get your API key.",
  "email": "user@example.com",
  "next_step": "Check your email and click the verification link to receive your API key."
}
```

### Step 3: User must verify their email
The user will receive an email with a verification link. They must click it to get their API key.

### Step 4: After verification, the API key is returned
Once verified, the API key is sent to their email AND returned in the verification response.

**IMPORTANT:** You cannot get an API key without access to the email inbox. This prevents fake signups.

---

## Quick Start (after signup)

```bash
# 1. Create sandbox
curl -X POST https://api.cerver.ai/sandbox \
  -H "Authorization: Bearer sk_trial_xxx"
# Returns: {"sandbox_id": "abc-123", ...}

# 2. Run code
curl -X POST https://api.cerver.ai/sandbox/abc-123/run \
  -H "Authorization: Bearer sk_trial_xxx" \
  -H "Content-Type: application/json" \
  -d '{"code": "print(2 ** 100)"}'
# Returns: {"output": "1267650600228229401496703205376", "exit_code": 0}
```

---

## Python SDK

```python
# pip install cerver
from cerver import Sandbox

with Sandbox(api_key="sk_trial_xxx") as sandbox:
    result = sandbox.run("print('Hello!')")
    print(result.output)
```

---

## Complete API Reference

Base URL: `https://api.cerver.ai`

### Auth (no auth required)

| Endpoint | Description |
|----------|-------------|
| `POST /auth/signup` | Sign up with email (sends verification link) |
| `GET /auth/verify-signup?token=` | Verify email and get API key |
| `POST /auth/login` | Request magic link for dashboard access |

### Sandbox Operations (require `Authorization: Bearer <key>`)

| Endpoint | Description |
|----------|-------------|
| `POST /sandbox` | Create sandbox (with envs, timeout, metadata) |
| `GET /sandbox/:id` | Get sandbox info |
| `GET /sandboxes` | List active sandboxes |
| `DELETE /sandbox/:id` | Kill sandbox |
| `POST /sandbox/:id/timeout` | Extend sandbox timeout |
| `GET /sandbox/:id/host?port=N` | Get external URL for port |
| `POST /sandbox/:id/run` | Run code (with envs override) |
| `POST /sandbox/:id/install` | Install packages |
| `POST /sandbox/:id/files` | Write file |
| `GET /sandbox/:id/files` | List files |
| `GET /sandbox/:id/files?path=x` | Read file |

---

## Request/Response Examples

### Signup (Step 1: Request Verification)
```
POST /auth/signup
Content-Type: application/json

{"email": "user@example.com"}

Response:
{
  "success": true,
  "message": "Verification email sent!",
  "email": "user@example.com",
  "next_step": "Check your email and click the verification link."
}
```

### Verify Email (Step 2: Get API Key)
User clicks the link in their email, which calls:
```
GET /auth/verify-signup?token=xxx

Response:
{
  "success": true,
  "api_key": "sk_trial_xxx",
  "email": "user@example.com",
  "plan": "trial",
  "limits": {"requests_per_day": 100, "max_sandboxes": 1}
}
```

### Create Sandbox (with options)
```
POST /sandbox
Authorization: Bearer sk_trial_xxx
Content-Type: application/json

{
  "engine": "containers",
  "envs": {"API_KEY": "secret123", "DEBUG": "true"},
  "timeout_ms": 600000,
  "metadata": {"project": "my-app", "user": "123"}
}

Response:
{
  "sandbox_id": "abc-123",
  "engine": "containers",
  "status": "ready",
  "timeout_ms": 600000,
  "expires_at": 1706000000,
  "envs": ["API_KEY", "DEBUG"],
  "metadata": {"project": "my-app", "user": "123"}
}
```

### Run Code (with env override)
```
POST /sandbox/abc-123/run
Authorization: Bearer sk_trial_xxx
Content-Type: application/json

{
  "code": "import os\nprint(os.environ.get('API_KEY'))",
  "envs": {"API_KEY": "override_value"}
}

Response:
{"output": "override_value", "error": "", "exit_code": 0, "duration": 2}
```

### Extend Timeout
```
POST /sandbox/abc-123/timeout
Authorization: Bearer sk_trial_xxx
Content-Type: application/json

{"timeout_ms": 300000}

Response:
{"success": true, "expires_at": 1706000300, "time_remaining_ms": 299500}
```

### Get Port URL (for web servers)
```
GET /sandbox/abc-123/host?port=8080
Authorization: Bearer sk_trial_xxx

Response:
{
  "sandbox_id": "abc-123",
  "port": 8080,
  "url": "https://abc12345-8080.sandbox.cerver.ai",
  "host": "abc12345-8080.sandbox.cerver.ai"
}
```

### Install Packages (auto-upgrades to containers)
```
POST /sandbox/abc-123/install
Authorization: Bearer sk_trial_xxx
Content-Type: application/json

{"packages": "pandas numpy"}

Response:
{"success": true, "upgraded": true}
```

### File Operations
```
# Write
POST /sandbox/abc-123/files
{"path": "data.txt", "content": "hello"}

# Read
GET /sandbox/abc-123/files?path=data.txt
Response: {"content": "hello"}

# List
GET /sandbox/abc-123/files
Response: {"files": [{"path": "data.txt", "size": 5}]}
```

---

## Engines

| Engine | Speed | Packages | Use Case |
|--------|-------|----------|----------|
| `workers` | ~50ms | stdlib only | Fast scripts |
| `containers` | ~500ms | full pip | pandas, numpy, ML, web servers |

Auto-upgrade: Installing non-stdlib packages upgrades to containers automatically.

---

## Environment Variables

Set at sandbox creation, override per execution:

```python
# Global envs set at creation
sandbox = create_sandbox(envs={"DB_URL": "postgres://..."})

# Override for specific execution
sandbox.run(code, envs={"DB_URL": "sqlite://test.db"})
```

Default vars injected automatically:
- `CERVER_SANDBOX=true`
- `CERVER_SANDBOX_ID=<sandbox_id>`

---

## Timeout Limits

| Plan | Max Timeout | Default |
|------|-------------|---------|
| Trial | 5 min | 5 min |
| Free | 1 hour | 5 min |
| Pro | 24 hours | 5 min |

---

## Plan Limits

| | Trial | Free | Pro |
|-|-------|------|-----|
| Key prefix | `sk_trial_` | `sk_live_` | `sk_live_` |
| Requests/day | 100 | 1,000 | 100,000 |
| Sandboxes | 1 | 5 | 100 |
| Port exposure | No | Yes | Yes |

Signup gives you a trial key. Upgrade at https://cerver.ai/dashboard for higher limits.

---

## Tool Definition (for function calling)

```json
{
  "name": "execute_python",
  "description": "Execute Python code in a secure sandbox",
  "parameters": {
    "type": "object",
    "properties": {
      "code": {"type": "string", "description": "Python code to execute"},
      "envs": {"type": "object", "description": "Environment variables"}
    },
    "required": ["code"]
  }
}
```

---

## Tips

1. **Email verification required** - User must click the link in their email to get an API key. You cannot bypass this.
2. **State persists** - Variables survive between `run()` calls in same sandbox
3. **Reuse sandboxes** - Create once, run many times
4. **Use env vars** - Pass secrets via envs, not hardcoded in code
5. **Extend timeout** - Call `/timeout` before expiry to keep sandbox alive
6. **Port exposure** - Run web servers and get external URLs (containers only)

---

## Error: "Email already registered"

If the user already has an account, they can:
1. Use their existing API key (check email)
2. Login at https://cerver.ai/login to access dashboard and create new keys

---

## Security & Architecture

- **Database**: Cloudflare D1 (SQLite) - not publicly accessible
- **API**: Cloudflare Workers (Python) - validates all requests with API keys
- **Sandboxes**: Isolated execution environments (Workers or containers)

Data flow:
```
User → API (validates API key) → D1 Database
                ↓
           Sandbox (isolated code execution)
```

No one can access the database directly. All requests go through the API which validates your API key first.

---

More: https://cerver.ai/docs