---
title: "API Overview"
description: "Baponi API reference: authentication with API keys, base URLs, Stripe-style error responses, rate limiting, and available SDKs. Everything you need to integrate sandboxed code execution into your AI agent."
url: https://baponi.ai/docs/api/overview
lastUpdated: 2026-03-16
---
# API Overview
Baponi is a sandboxed code execution platform for AI agents. Authenticate with an API key, send code, get results.

## Base URL

| Surface | Base URL | Auth |
|---------|----------|------|
| Execution API | `https://api.baponi.ai` | API key (Bearer token) |
| MCP Protocol | `https://api.baponi.ai/mcp` | API key (Bearer token) |

All requests must use HTTPS. HTTP requests are rejected.

## Authentication

### API key authentication

Every request to the Execution API requires an API key in the `Authorization` header:

```bash
curl -X POST https://api.baponi.ai/v1/sandbox/execute \
  -H "Authorization: Bearer sk-us-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "print(1+1)", "language": "python"}'
```

API keys start with `sk-` followed by a region code and a base64-encoded token. Create keys in the [admin console](https://console.baponi.ai) under **API Keys**.

Each API key is bound to:
- A **sandbox** (runtime image, CPU, RAM, network policy)
- Optional **storage connections** (S3, GCS, Azure buckets mounted as local directories)
- Optional **volumes** (managed persistent storage)
- Optional **connectors** (database and service credentials injected at runtime)
This means the API key determines the entire execution environment. You configure everything once in the admin console, then every request with that key runs in the same environment.

API keys are shown only once at creation time. Store them securely. If lost, revoke the key and create a new one.

## Request format

All request bodies are JSON. Set `Content-Type: application/json`.

```bash
curl -X POST https://api.baponi.ai/v1/sandbox/execute \
  -H "Authorization: Bearer $BAPONI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "print(\"hello\")", "language": "python"}'
```

## Error responses

Baponi returns structured JSON errors with a machine-readable `error` code and a human-readable `message`:

```json
{
  "error": "validation_error",
  "message": "code must be between 1 byte and 1 MB"
}
```

### HTTP status codes

| Status | Error Code | Description |
|--------|------------|-------------|
| `400` | `validation_error` | Request body failed validation. Check the `message` for details. |
| `401` | `unauthorized` | Missing, invalid, or revoked API key. |
| `403` | `forbidden` | Valid key but insufficient permissions. |
| `404` | `not_found` | Resource does not exist. |
| `409` | `conflict` | Resource conflict. Thread is busy, or duplicate name. |
| `429` | `rate_limited` | Too many requests or plan limit exceeded. |
| `500` | `internal_error` | Server error. Retry with backoff. |
| `503` | `service_unavailable` | Execution infrastructure temporarily unavailable. |
| `504` | `gateway_timeout` | Execution exceeded the timeout. |

### Thread conflict (409)

If two requests use the same `thread_id` simultaneously, the second request returns `409 Conflict`. Only one execution can use a given thread at a time. Use different `thread_id` values for parallel work.

### Rate limiting (429)

Rate limiting applies in two cases:

1. **Failed authentication.** 3 failed API key attempts per IP within 60 seconds triggers a temporary block.
2. **Plan limits.** Exceeding your plan's concurrent execution limit or other quotas returns `429` with an upgrade message.

Rate-limited responses include the standard error format:

```json
{
  "error": "rate_limited",
  "message": "concurrent execution limit reached (5/5). Upgrade to Pro for 100 concurrent executions."
}
```

## Plan limits

Resource limits depend on your plan tier:

| Limit | Free | Pro | Enterprise |
|-------|------|-----|------------|
| Max CPU per sandbox | 1 core | 4 cores | Unlimited |
| Max RAM per sandbox | 1 GiB | 4 GiB | Unlimited |
| Concurrent executions | 5 | 100 | Unlimited |
| Max timeout | 60 seconds | 1 hour | Unlimited |
| API keys | 10 | Unlimited | Unlimited |
| Audit log retention | 1 day | 30 days | Unlimited |
| Custom OCI images | 1 | Unlimited | Unlimited |
| Streaming / async delivery | No | Yes | Yes |

All tiers include: unlimited team seats, storage connections, volumes, and connectors. See [Pricing](/pricing) for credit costs and overages.

## SDKs and integrations

### Python SDK

```bash
pip install baponi
```

```python
from baponi import Baponi

client = Baponi(api_key="sk-us-...")  # or set BAPONI_API_KEY env var
result = client.execute("print('hello')")
print(result.stdout)  # hello
```

The SDK supports all three delivery modes:

```python
# Inline (default)
result = client.execute("print('hello')")

# Streaming - real-time stdout/stderr via NDJSON
with client.execute_stream("print('hello')") as stream:
    result = stream.until_done()

# Webhook - fire-and-forget, result POSTed to your URL
handle = client.execute_webhook("print('hello')", webhook_url="https://...")
result = handle.wait()
```

All methods accept `env_vars` for per-request environment variables:

```python
result = client.execute(
    "import os; print(os.environ['API_TOKEN'])",
    env_vars={"API_TOKEN": "sk-test-123"},
)
```

Status and cancellation:

```python
status = client.get_execution("trc_abc12345")
cancel = client.cancel_execution("trc_abc12345")
```

The Python SDK includes ready-made integrations for LLM frameworks:

```python
from baponi.anthropic import code_sandbox  # Anthropic Claude
from baponi.openai import code_sandbox     # OpenAI Agents SDK
from baponi.google import code_sandbox     # Google Gemini
from baponi.langchain import code_sandbox  # LangChain
from baponi.crewai import code_sandbox     # CrewAI
```

### MCP (Model Context Protocol)

Baponi is a native MCP server. Connect from any MCP client with a URL and API key, no SDK required:

```json
{
  "mcpServers": {
    "baponi": {
      "url": "https://api.baponi.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk-us-YOUR_API_KEY"
      }
    }
  }
}
```

See the [MCP Protocol](/docs/api/mcp.md) reference for details.

### HTTP (any language)

The API is a standard REST interface. Any HTTP client works:

```python

response = requests.post(
    "https://api.baponi.ai/v1/sandbox/execute",
    headers={"Authorization": "Bearer sk-us-YOUR_API_KEY"},
    json={"code": "print('hello')", "language": "python"},
).json()
```

```javascript
const response = await fetch("https://api.baponi.ai/v1/sandbox/execute", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-us-YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ code: "console.log('hello')", language: "node" }),
});
const result = await response.json();
```

```go
payload := `{"code": "print('hello')", "language": "python"}`
req, _ := http.NewRequest("POST", "https://api.baponi.ai/v1/sandbox/execute",
    strings.NewReader(payload))
req.Header.Set("Authorization", "Bearer sk-us-YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
```

## API endpoints at a glance

### Execution API (`https://api.baponi.ai`)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | [`/v1/sandbox/execute`](/docs/api/execute.md) | Execute code in a sandbox (inline or streaming) |
| `GET` | [`/v1/executions/{trace_id}`](/docs/api/executions.md#get-execution-status) | Execution status and result |
| `GET` | [`/v1/executions/{trace_id}/output`](/docs/api/executions.md#reconnect-to-output-stream) | Output chunks (streaming reconnection) |
| `POST` | [`/v1/files/list`](/docs/api/files.md#list-files) | List files in a thread or volume |
| `POST` | [`/v1/files/upload_url`](/docs/api/files.md#generate-upload-url) | Get a signed upload URL |
| `POST` | [`/v1/files/download_url`](/docs/api/files.md#generate-download-url) | Get a signed download URL |
| `DELETE` | [`/v1/files`](/docs/api/files.md#delete-a-file) | Delete a file |
| `GET` | `/health` | Health check |
| `GET` | `/ready` | Readiness probe |

### MCP Protocol (`https://api.baponi.ai/mcp`)

| Method | Description |
|--------|-------------|
| `POST` | JSON-RPC 2.0 endpoint (initialize, tools/list, tools/call) |

Tools exposed: `sandbox_execute`, `files_download`. See [MCP Protocol](/docs/api/mcp.md).