REST API basics

Everything Rytiv does goes through one HTTP API. The CLI, the console and the MCP server use the same routes you can call yourself. The routes themselves are on the API reference pages, one per family, generated from the control plane’s code.

Base URL

https://api.rytiv.app/v1

Requests and answers are JSON (Content-Type: application/json), except where a route says otherwise: file contents, source uploads and the OAuth token endpoint take other bodies, and the reference says so.

Authentication

Send an API key as a bearer token on every request:

curl

curl https://api.rytiv.app/v1/apps -H "Authorization: Bearer $RYTIV_TOKEN"

TypeScript

const res = await fetch("https://api.rytiv.app/v1/apps", {
  headers: { Authorization: `Bearer ${process.env.RYTIV_TOKEN}` },
});
const apps = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.rytiv.app/v1/apps",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
)
apps = res.json()

CLI

ry apps list

Every route acts as the organization of the key. A name that belongs to another organization answers exactly like a name that does not exist, usually 404. A key with scopes reaches only the routes its scopes cover; the reference names the scope each route needs.

Acting for a managed organization

If your organization manages other organizations, a key of yours can act inside one of them with the header X-Rytiv-Org: <org id>. Naming your own organization changes nothing. Naming one your organization does not manage answers 403 with the code delegation-refused. An agent token cannot use the header at all (agent-token-delegation).

Errors

Every error is a JSON object with an English sentence and a stable code:

{ "error": "name already taken", "code": "name-taken" }

Branch on code, show error. Some routes add fields that help with the next step (issues, limit, current, heldBy). New codes can appear; a code your program does not know should fall back on the HTTP status. The error catalog lists every code.

A request that fails validation answers 400 with the code bad-request. Its error sentence names every field that was wrong, and issues carries the same problems as a list.

Status	Meaning
400	The request is malformed or a field is out of range.
401	No API key, or one that does not work.
402	The organization’s credit is at zero; only reads, stops and billing routes pass.
403	The key may not do this: a scope, an agent token’s class, an organization limit, or an organization yours does not manage.
404	Not found, or not yours.
408	A wait ran out (GET /v1/machines/:id/wait).
409	The request conflicts with the current state, for example a taken name or a deploy that is already running.
429	Too many: a limit of your organization is reached, or a rate limit. Retry-After says when to try again.
5xx	Something on our side, or no capacity right now. The error sentence says which.

Waiting for work to finish

A deploy, a machine create with ?wait=false, a branch or a fork answer 202 and continue in the background. Poll the object they name until it reaches its final state:

Started by	Poll	Until
POST /v1/apps/:name/deploy	GET /v1/deploys/:id	status is done or error
POST /v1/apps/:name/machines?wait=false	GET /v1/machines/:id/wait?state=running	the machine answers, or 408
POST /v1/resources/:name/branch or /fork	GET /v1/resources/:name	state is ready or failed
POST /v1/apps/:name/jobs	GET /v1/jobs/:id	state is done, failed or timeout

Rate limits

The product API has no general rate limit. A few entrances do, and answer 429 with Retry-After when it is reached: the MCP endpoint (120 tool calls per minute per organization), shell sessions (120 starts per minute per organization), computer viewer links (120 per minute per organization), and the login and OAuth entrances per caller address.

Routes by family

Family	Routes	Reference
Apps	/v1/apps, attach, link, labels, maintenance	Apps
Deploys and releases	detect, builds, deploy, deploys, releases, rollback, previews, Git	Deploys and releases
Machines	/v1/apps/:name/machines, /v1/machines/:id, logs, snapshots, files	Machines
Computers	viewer and control links, control audit	Computers
Sandboxes	/v1/sandboxes	Sandboxes
Postgres	/v1/resources	Postgres
Volumes	/v1/volumes	Volumes
Buckets	/v1/buckets, presign, objects, CORS	Buckets
Secrets	/v1/apps/:name/secrets	Secrets
Tokens and keys	/v1/tokens, agent actions, SSH keys, device login	Tokens and keys
Organization	/v1/org, managed organizations	Organization
Billing and usage	/v1/billing/*, /v1/usage	Billing and usage
Custom domains	/v1/apps/:name/domains, zones	Custom domains
Cron and jobs	schedules, jobs	Cron and jobs
Protection and network	protection, network policy, UDP	Protection and network
Mail	/v1/emails, /v1/mail/*	Mail
Webhooks	/v1/webhooks	Webhooks
MCP	POST /v1/mcp	MCP, MCP tools
OAuth and device login	/v1/oauth/*, /v1/device/*	OAuth and device login