Cloud Agents API Reference

Base URL: https://api.runta.com. Authenticate every request with Authorization: Bearer <Runta API key>. Send JSON request bodies with Content-Type: application/json.

The links below open the generated reference for exact parameters, request bodies, response schemas, and error responses. It is built directly from Runta core’s public OpenAPI contract. Download the OpenAPI document for client generation or use the full REST reference.

Agents and computers

Method and path	Reference	Success
GET /v2/agents	List agents	200 — {agents, next_cursor}
POST /v2/agents	Create agent	201 — agent
GET /v2/agents/{agent_id}	Get agent	200 — agent
PATCH /v2/agents/{agent_id}	Rename agent	200 — agent
DELETE /v2/agents/{agent_id}	Delete agent	202 — runtime deletion requested; 204 — additional harness deleted
POST /v2/agents/{agent_id}/computer-sessions	Create computer session	201 — VNC connection and expiry

Guides: Lifecycle, Computer sessions.

Runs and events

Method and path	Reference	Success
GET /v2/agents/{agent_id}/runs	List runs	200 — run array
POST /v2/agents/{agent_id}/runs	Create run	202 — run
GET /v2/agents/{agent_id}/runs/{run_id}	Get run	200 — run
DELETE /v2/agents/{agent_id}/runs/{run_id}	Cancel run	200 — run
POST /v2/agents/{agent_id}/runs/{run_id}/resume	Resume run	202 — new run
POST /v2/agents/{agent_id}/runs/{run_id}/follow-ups	Follow up	202 — active or new run
GET /v2/agents/{agent_id}/runs/{run_id}/events	Stream run events	200 — text/event-stream
GET /v2/agents/{agent_id}/events	List session events	200 — {agent_id, session_id, events}

Guide: Runs and events. Cancellation uses DELETE on the run; there is no /cancel subresource.

Artifacts and workspace

Method and path	Reference	Success
GET /v2/agents/{agent_id}/artifacts	List artifacts	200 — artifact array
POST /v2/agents/{agent_id}/artifacts	Create artifact	201 — metadata
GET /v2/agents/{agent_id}/artifacts/{artifact_id}	Get artifact	200 — metadata and optional base64 content
DELETE /v2/agents/{agent_id}/artifacts/{artifact_id}	Delete artifact	204
POST /v2/agents/{agent_id}/workspace	Query workspace	200 — operation result
PUT /v2/agents/{agent_id}/workspace/files	Write file	200 — {path, size}
DELETE /v2/agents/{agent_id}/workspace/files	Delete file	204

Guide: Workspace and artifacts. Workspace DELETE takes a JSON body. A 204 has no body to parse.

Model providers

Method and path	Reference	Success
GET /v2/model-providers	List providers	200 — {organization_id, model_providers}
PATCH /v2/model-providers/{provider_id}	Update provider	200 — provider metadata

Guide: Model providers. The provider PATCH requires all configuration fields. The public API does not expose provider creation or deletion endpoints.

Limits

These are the limits in the current implementation. Deployment HTTP settings and installed runtime bundles can impose tighter limits.

Input or output	Limit / behavior
Agent name	1–255 bytes after trimming.
Run prompt	Up to 65,536 UTF-8 bytes after trimming; empty only with images.
Prompt images	Up to eight; PNG, JPEG, GIF, WebP; raw base64 in data.
Encoded image data	Up to 35,000,000 bytes per image and 70,000,000 bytes total.
Harness, run, session identifiers	1–160 ASCII letters, digits, _, or -; agent runtime prefix must be a UUID.
Agent list limit	Public OpenAPI range 1–100.
Run list limit	1–500, default 100.
Event cursor	Integer after >= -1; exclusive, run-local sequence.
Artifact filename	1–255 ASCII characters, starting with a letter/digit, then letters/digits, ., _, -.
Artifact/workspace write helper	Up to 32 MiB decoded content; transport limits can be lower.
Workspace query path / search query	Up to 4,096 / 256 bytes.
Run/artifact helper output	2 MiB JSON output cap, including encoded content.

Base64 expands file sizes by roughly one third. Ordinary requests use the deployment’s configured body limit (1 MiB by default). New-run and follow-up POST routes have a separate 72 MiB limit; the /resume route uses the ordinary limit. Reduce payloads if you receive 413. Do not treat the 32 MiB storage-helper limit as a guaranteed upload or download size over this API.

Artifact retrieval with content must fit inside the helper output cap; there is no artifact download cursor. Large run/session histories can also exceed that cap. Stream run events incrementally and store required history in your application. Workspace media supports its own chunked reads.

Errors and retries

Ordinary API errors use this envelope:

{
  "error": {
    "code": "invalid_argument",
    "message": "invalid Cloud Agent ID"
  },
  "request_id": "request-identifier"
}

Keep request_id when investigating a failure. The generated operation pages list the supported error responses.

HTTP status	Client action
401	Supply a valid Runta Bearer API key.
403	Check organization access and the key’s permissions.
404	Check the resource ID and harness ownership; after deletion it can confirm control-plane absence.
409	Re-read state. A run may be active or runtime initialization may still be pending.
413	Reduce the encoded request size.
422	Correct the fields or runtime/provider combination using the error message.
429	Back off; honor Retry-After when supplied.
501	Check whether the operation is supported by the deployment.
503, 504	Check runtime readiness, then retry eligible reads with bounded backoff.

Use bounded exponential backoff for polling and transient failures. The public creation endpoints do not declare idempotency keys. After an ambiguous timeout, list/get resources before retrying a mutation that could create another agent, run, or artifact. Preserve IDs from successful responses.

SSE failures after headers have been sent arrive as an error event or a closed connection, rather than this JSON HTTP envelope.

Troubleshooting

The agent exists but the first run is missing. Fresh creation returns before initialization finishes. Poll agent/runtime state, then list runs. Check provider credentials and GitHub access if setup fails. If no initial_message was sent, submit a run explicitly after the runtime is ready.

Adding an agent to an existing runtime fails. Check that it is a Cloud Agent runtime with a compatible bundle, the selected provider and credential match, and repositories is empty. Create a fresh runtime to change providers.

A new task conflicts with an active run. Use a follow-up to steer the active run, or cancel it and wait for terminal state before creating another.

Resume says there is no resumable session. A failed setup or synthetic reply may have no Pi session. Submit a new run; a follow-up also handles the synthetic bootstrap case.

Events are duplicated or history is incomplete. Track numeric cursors per run, not per agent. Session replay does not aggregate multiple runs. Use per-run SSE and the public run response to recover final state.

The computer session times out. Inspect runtime/VNC readiness before requesting another ticket. Use the returned URL and both WebSocket protocols.

Deleting an agent leaves a computer visible. Removing an additional harness without delete_runtime=true intentionally keeps the runtime. Runtime deletion returns 202; poll its UUID until 404 to confirm removal.