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:

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 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.

Caution

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.

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:

{
  "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:

{
  "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 for credit costs and overages.

SDKs and integrations

Python SDK

pip install baponi

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:

# 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:

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

Status and cancellation:

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

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

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:

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

See the MCP Protocol reference for details.

HTTP (any language)

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

Python

import requests

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	Execute code in a sandbox (inline or streaming)
GET	/v1/executions/{trace_id}	Execution status and result
GET	/v1/executions/{trace_id}/output	Output chunks (streaming reconnection)
POST	/v1/files/list	List files in a thread or volume
POST	/v1/files/upload_url	Get a signed upload URL
POST	/v1/files/download_url	Get a signed download URL
DELETE	/v1/files	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.