> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberun.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> REST endpoints exposed by the Cyberun platform. Auto-generated from the OpenAPI spec.

The Cyberun API is the HTTP surface of the platform. Every client —
Cloud, Studio, [the CLI](/cloud/guides/cli), partner
integrations, the MCP server — calls these endpoints.

The endpoint pages under **Endpoints** are auto-generated from the
platform's OpenAPI spec — only the public, user-facing surface.

## Base URL

```
https://core.cyberun.cloud/api/v1
```

Self-hosted deployments use their own domain. Everything below this
prefix follows the same auth rules.

## Authentication

Three credential families:

| Type                | Header                         | Team scoping                                                                                  |
| ------------------- | ------------------------------ | --------------------------------------------------------------------------------------------- |
| User JWT            | `Authorization: Bearer eyJ...` | Send `X-Team-ID: team_01HX...` on team-scoped endpoints — a user may belong to several teams. |
| Integration (`sk-`) | `Authorization: Bearer sk-...` | Team is **bound to the credential** at issue time. Do not send `X-Team-ID` — it's ignored.    |
| Device (`dk-`)      | `Authorization: Bearer dk-...` | Team is bound to the credential. Do not send `X-Team-ID`.                                     |

The single rule: `X-Team-ID` is **only** for JWTs. Sending it with a
`sk-` or `dk-` credential has no effect — the team is read from the
credential row.

See [Generate an API key](/cloud/guides/api-key) for the `sk-`
issuance flow; [Credentials](/cloud/concepts/credentials) for the
full family reference.

## Surfaces

The endpoint listing is grouped by OpenAPI tag (Auth, Team, Workflow,
Task, Webhook, Container, etc.). Three logical surfaces span those
tags:

* **Management** — list and modify team resources. Requires either a
  user JWT (with `X-Team-ID`) or a device credential `dk-`. Most of
  the endpoints under tags like Team, Member, Workflow, Webhook fall
  here.
* **Runtime** (`/r/...`) — submit and observe tasks. Accepts JWT,
  `sk-`, or `dk-`. The path you'll hit most from scripts and CI.
* **MCP** (`/api/v1/mcp`) — Streamable HTTP MCP endpoint that wraps
  runtime operations as MCP tools. Accepts `sk-` only. Full reference:
  [Cloud MCP](/mcp/cloud).

## Pagination

List endpoints take `current_page` (default `1`) and `per_page`
(default `20`, max `100`) query parameters. Responses include a
`page_meta` block with `current_page`, `per_page`, and
`total_count`.

## Task lifecycle

Every task moves through these states:

| State          | Meaning                                                                 |
| -------------- | ----------------------------------------------------------------------- |
| `pending`      | Accepted by the platform. Scheduler hasn't picked it up yet.            |
| `waiting`      | Scheduler has it but no eligible agent is available.                    |
| `provisioning` | An agent is being prepared to take the task.                            |
| `queued`       | An agent has been chosen. Waiting for the agent to acknowledge.         |
| `running`      | The agent is executing the workflow.                                    |
| `completed`    | Finished cleanly. Outputs available via `GET /r/tasks/{taskId}/result`. |
| `failed`       | Errored, timed out, or the agent disconnected.                          |
| `cancelled`    | Cancelled before reaching a terminal state.                             |

`completed`, `failed`, and `cancelled` are terminal — the task won't
move past them. See [Stream task events (SSE)](/api-reference/streaming-events)
for following state transitions in real time.

## Status codes

Submitting a task returns `202 Accepted` with the task ID — the work
runs asynchronously, so poll or stream for the outcome. Other reads
and writes return `200 OK` on success.

Errors are JSON with a single `error_message` field:

```json theme={null}
{
	"error_message": "resource not found"
}
```

| Code          | When you'll see it                                                                    |
| ------------- | ------------------------------------------------------------------------------------- |
| `400`         | Bad request — malformed JSON, missing or invalid parameter values.                    |
| `401`         | Credential is invalid, revoked, or expired. Don't retry.                              |
| `403`         | Credential is valid but lacks permission (or wrong team for the resource).            |
| `404`         | Resource not found in this team.                                                      |
| `409`         | Conflict — e.g. slug already taken, resource in a state that disallows the operation. |
| `429`         | Rate-limited. Back off and retry.                                                     |
| `500`         | Unexpected server error. Safe to retry idempotent requests.                           |
| `502` / `503` | Container service gateway errors (only on `/r/containers/*` and `/r/invoke/*`).       |

## What to read next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/api-reference/quickstart">
    Submit a task, stream events, fetch the output — three calls,
    three languages.
  </Card>

  <Card title="Generate an API key" icon="key" href="/cloud/guides/api-key">
    Issue an `sk-` credential and call your first endpoint.
  </Card>

  <Card title="Stream task events (SSE)" icon="radio" href="/api-reference/streaming-events">
    Event-type reference, fields, and polling fallback.
  </Card>

  <Card title="Upload input files" icon="upload" href="/api-reference/file-upload">
    Three-step presigned upload flow for workflows that take files.
  </Card>

  <Card title="Call a container service" icon="container" href="/api-reference/containers">
    Reach long-running services hosted on your team's agents.
  </Card>

  <Card title="Cloud MCP" icon="plug" href="/mcp/cloud">
    Streamable HTTP endpoint with 15 tools that wrap the
    runtime API.
  </Card>

  <Card title="Use the CLI" icon="terminal" href="/cloud/guides/cli">
    These endpoints are wrapped by the `cyberun` CLI — drive the
    runtime API from your shell instead of raw HTTP.
  </Card>
</CardGroup>