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

# API Reference

> HTTP endpoints on the hostd. Same contract Python + TypeScript SDKs speak.

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

```json theme={null}
{"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}
```

<ResponseField name="type" type="string">
  One of `stdout`, `stderr`, `exit`.
</ResponseField>

<ResponseField name="data" type="string | int">
  For `stdout`/`stderr`: one line of output. For `exit`: the integer exit
  code of the program.
</ResponseField>

<ResponseField name="seq" type="int">
  Monotonic per `exec` call. Lets consumers reassemble if events arrive
  out of order across transports.
</ResponseField>

<ResponseField name="ts" type="int">
  Host wall-clock time in milliseconds since epoch.
</ResponseField>

## Endpoints

<CardGroup cols={2}>
  <Card title="POST /v1/sandboxes" icon="plus" href="/api-reference/create-sandbox">
    Create a new sandbox, return its id.
  </Card>

  <Card title="POST /v1/sandboxes/:id/exec" icon="terminal" href="/api-reference/exec">
    Execute code, stream events.
  </Card>

  <Card title="POST /v1/sandboxes/:id/fork" icon="code-branch" href="/api-reference/fork">
    N-way CoW fork.
  </Card>

  <Card title="POST /v1/sandboxes/:id/merge_into/:winner" icon="code-merge" href="/api-reference/merge-into">
    Commit a winner into a parent.
  </Card>

  <Card title="DELETE /v1/sandboxes/:id" icon="trash" href="/api-reference/destroy">
    Destroy a sandbox.
  </Card>

  <Card title="GET /v1/healthz" icon="heart-pulse" href="/api-reference/introduction">
    Liveness probe; returns `ok`.
  </Card>
</CardGroup>

## Authentication

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

## Errors

Non-2xx responses return:

```json theme={null}
{"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.)