Skip to main content
The Podflare REST API is the underlying contract that both the Python and TypeScript SDKs speak. You can call it directly with any HTTP client — all request bodies are JSON and all responses are either JSON or newline-delimited JSON (NDJSON) for streaming endpoints.

​
Base URL

Use the local address during development and the hosted URL for production:
EnvironmentBase URL
Local devhttp://127.0.0.1:7070
Hostedhttps://api.podflare.dev

​
Content types

  • Requests: application/json
  • Non-streaming responses: application/json
  • Streaming responses (/exec): application/x-ndjson — one JSON object per line, flushed as the sandbox produces it

​
Streaming event schema

The /exec endpoint streams events as NDJSON. Each line is one of the following event objects: 
{"type": "stdout", "data": "string of one line", "seq": 0, "ts": 1776510028036}
{"type": "stderr", "data": "string of one line", "seq": 1, "ts": 1776510028037}
{"type": "exit",   "data": 0,                    "seq": 2, "ts": 1776510028038}
​
type
string
required
The event type. One of stdout, stderr, or exit.
​
data
string | int
required
For stdout and stderr: one line of output text. For exit: the integer exit code of the process.
​
seq
int
required
Monotonically increasing counter scoped to the exec call. Use this to reassemble events in order if they arrive out of sequence across transports.
​
ts
int
required
Host wall-clock timestamp in milliseconds since the Unix epoch.

​
Authentication

Local dev has no auth by default. Hosted deployments require an Authorization: Bearer <token> header on every request to /v1/* (except /v1/healthz). The SDKs read this token from the PODFLARE_API_KEY environment variable.
Pass your API key as a bearer token: 
curl -X POST https://api.podflare.dev/v1/sandboxes \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "content-type: application/json" \
  -d '{}'
Set the key as an environment variable so the SDK picks it up automatically: 
export PODFLARE_API_KEY=pk_your_key_here
Local development mode (connecting to http://127.0.0.1:7070) does not require an API key. All hosted requests to https://api.podflare.dev require a valid key.

​
Errors

All non-2xx responses return a JSON body with a single error field: 
{"error": "human-readable message"}
Common status codes:
StatusMeaning
400Invalid request body — for example, fork called with n > 32
401Missing or invalid API key
404Sandbox id not found
500Executor error — Firecracker API failed, agent did not respond, etc.

​
Endpoints

POST /v1/sandboxes

Create a new sandbox and return its id.

POST /v1/sandboxes/:id/exec

Execute code in a sandbox and stream output events.

POST /v1/sandboxes/:id/fork

Snapshot a sandbox and spawn N copy-on-write children.

POST /v1/sandboxes/:id/merge_into/:winner

Commit a fork child’s state as the parent’s new state.

DELETE /v1/sandboxes/:id

Destroy a sandbox and free its resources.