Skip to main content

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.

The Cyberun API is the HTTP surface of the platform. Every client — Cloud, Studio, the 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:
TypeHeaderTeam scoping
User JWTAuthorization: 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 for the sk- issuance flow; 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.

​
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:
StateMeaning
pendingAccepted by the platform. Scheduler hasn’t picked it up yet.
waitingScheduler has it but no eligible agent is available.
provisioningAn agent is being prepared to take the task.
queuedAn agent has been chosen. Waiting for the agent to acknowledge.
runningThe agent is executing the workflow.
completedFinished cleanly. Outputs available via GET /r/tasks/{taskId}/result.
failedErrored, timed out, or the agent disconnected.
cancelledCancelled before reaching a terminal state.
completed, failed, and cancelled are terminal — the task won’t move past them. See Stream task events (SSE) 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: 
{
	"error_message": "resource not found"
}
CodeWhen you’ll see it
400Bad request — malformed JSON, missing or invalid parameter values.
401Credential is invalid, revoked, or expired. Don’t retry.
403Credential is valid but lacks permission (or wrong team for the resource).
404Resource not found in this team.
409Conflict — e.g. slug already taken, resource in a state that disallows the operation.
429Rate-limited. Back off and retry.
500Unexpected server error. Safe to retry idempotent requests.
502 / 503Container service gateway errors (only on /r/containers/* and /r/invoke/*).

Quickstart

Submit a task, stream events, fetch the output — three calls, three languages.

Generate an API key

Issue an sk- credential and call your first endpoint.

Stream task events (SSE)

Event-type reference, fields, and polling fallback.

Upload input files

Three-step presigned upload flow for workflows that take files.

Call a container service

Reach long-running services hosted on your team’s agents.

Cloud MCP

Streamable HTTP endpoint with 15 tools that wrap the runtime API.

Use the CLI

These endpoints are wrapped by the cyberun CLI — drive the runtime API from your shell instead of raw HTTP.