REST API

Requests and errors

The conventions every endpoint shares: the base URL, headers, request IDs and how failures are reported.

Base URL

https://dev-api.renderops.com

Request bodies are JSON; send Content-Type: application/json with them. Responses are JSON unless noted (destroying a sandbox returns 204 with no body).

Request IDs

Every response carries an X-Request-ID header, and most JSON bodies repeat it as request_id. Send your own X-Request-ID to correlate calls with your logs, and include the ID when you contact support about a request.

Error responses

Errors come back with an HTTP status and, on most endpoints, a JSON body:

503 Service Unavailable

{
  "status": "error",
  "code": "no_capacity",
  "message": "no healthy worker has sufficient capacity",
  "request_id": "4e245aae-1694-4dd5-b944-7180bf480fe8"
}

Status codes

Status	Meaning
`200`	Success.
`201`	Created a sandbox, terminal, IDE session or preview link.
`204`	Sandbox destroyed.
`400`	The request is malformed or a field is invalid.
`401`	Missing, unknown, inactive or expired API key.
`402`	The account has no balance left.
`403`	Your account’s policy doesn’t allow this operation (`sessions_not_allowed`).
`404`	No such sandbox — or it belongs to someone else. The API doesn’t tell the two apart.
`500`	Something failed on our side, e.g. `provision_failed`.
`503`	No capacity right now (`no_capacity`, `scheduler_busy`) or a dependency is unavailable. Safe to retry with backoff.

Failed runs aren’t failed requests

When code you run exits with a non-zero code, the request itself still succeeds with 200. The body has status: "error", an error.code of execution_failed (or exec_failed for shell commands), and the full stdout, stderr and exit code. See Run code and commands.

Health check

GET /health needs no key and reports that the API process is responding:

GET /health

{
  "status": "ok",
  "message": "control plane is healthy",
  "role": "control-plane"
}