Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.podflare.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

  • Local dev (self-hosted): http://127.0.0.1:7070
  • Hosted: https://api.podflare.ai

​
Content types

  • Requests: application/json.
  • Responses (non-streaming): application/json.
  • Responses (streaming, /exec): application/x-ndjson — one JSON object per line, flushed as it’s produced.

​
Event schema

Streaming endpoints emit these events: 
{"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
One of stdout, stderr, exit.
​
data
string | int
For stdout/stderr: one line of output. For exit: the integer exit code of the program.
​
seq
int
Monotonic per exec call. Lets consumers reassemble if events arrive out of order across transports.
​
ts
int
Host wall-clock time in milliseconds since epoch.

​
Endpoints

POST /v1/sandboxes

Create a new sandbox, return its id.

POST /v1/sandboxes/:id/exec

Execute code, stream events.

POST /v1/sandboxes/:id/fork

N-way CoW fork.

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

Commit a winner into a parent.

DELETE /v1/sandboxes/:id

Destroy a sandbox.

GET /v1/healthz

Liveness probe; returns ok.

​
Authentication

Local dev has no auth. Hosted deployments require Authorization: Bearer <token> — the SDKs pick this up from PODFLARE_API_KEY.

​
Errors

Non-2xx responses return: 
{"error": "human-readable message"}
Common statuses:
  • 404 — sandbox id not found
  • 400 — invalid body (e.g., fork with n > 32)
  • 500 — executor error (VMM failed, agent didn’t respond, etc.)