<!-- Get started: https://docs.rytiv.com/ -->

# Rytiv documentation

> Rytiv is where your coding agent builds and ships. Connect it once, and it gets computers and sandboxes to work in, and apps and Postgres to ship to, in the EU.

Rytiv gives a coding agent such as Claude Code a place of its own: computers it can work in, databases it can branch, and apps it can deploy. Your agent talks to Rytiv over MCP; you use the same platform from the `ry` CLI, the REST API or the console. Your apps, databases and files stay in the EU.

- [Connect your coding agent](https://docs.rytiv.com/quickstart.md): One command adds Rytiv to Claude Code. Then ask it to build.
- [Deploy a Next.js app](https://docs.rytiv.com/guides/deploy-nextjs.md): From a directory to a URL with ry deploy, in a few minutes.
- [Create a computer](https://docs.rytiv.com/computers.md): A machine of its own for an agent: files that stay, a desktop you can watch.
- [Branch a database](https://docs.rytiv.com/postgres.md): A Postgres copy in seconds, where your agent tries the migration first.

## Find your way

- [Get started](https://docs.rytiv.com/quickstart.md): Quickstart, API keys and the CLI login, and how these docs serve agents.
- [Guides](https://docs.rytiv.com/guides/deploy-nextjs.md): Task by task: deploy, Postgres, computers, agents and tokens, credit, domains, buckets, cron and jobs.
- [Concepts](https://docs.rytiv.com/concepts/how-it-works.md): How Rytiv works, limits and quotas, the error catalog, regions, security and data.
- [API reference](https://docs.rytiv.com/reference/api.md): Every endpoint with its fields, an example request, the shape of the answer and its error codes. Generated from the code.
- [CLI reference](https://docs.rytiv.com/reference/cli.md): Every ry command with its flags and an example, generated from the CLI.
- [SDK & MCP](https://docs.rytiv.com/reference/mcp-tools.md): The tools your agent sees over MCP, and the TypeScript SDK.

## Three ways in

| Way | For | Where |
| --- | --- | --- |
| MCP server | Your coding agent | `https://api.rytiv.app/v1/mcp`, see the [quickstart](https://docs.rytiv.com/quickstart.md) |
| CLI `ry` | You, in a terminal or in CI | [CLI reference](https://docs.rytiv.com/reference/cli.md) |
| REST API | Your own code | [API reference](https://docs.rytiv.com/reference/api.md) |

All three use the same API and the same keys, and they see the same apps, databases and machines. The console at `https://console.rytiv.com` is where you sign in, create keys, watch a computer's desktop and top up credit.

## What you get

- **Computers**: a machine for an agent with a home disk that stays, in three sizes, with a desktop you can watch or take over. See [Computers](https://docs.rytiv.com/computers.md).
- **Apps**: deploy from source or from an image; every app answers on `https://<app>.rytiv.app` with TLS, rolls one machine at a time and can be rolled back. See [Apps](https://docs.rytiv.com/apps.md).
- **Postgres**: databases with copy-on-write branches and point-in-time forks, reachable only from the apps you attach. See [Postgres](https://docs.rytiv.com/postgres.md).
- **Sandboxes**: short-lived machines for one task each, removed at their deadline. See [Sandboxes](https://docs.rytiv.com/sandboxes.md).
- **Buckets, cron, jobs, custom domains, mail**: the rest of what an app needs, in the [guides](https://docs.rytiv.com/guides/buckets.md).

---

<!-- Get started: https://docs.rytiv.com/quickstart/ -->

# Quickstart: connect your coding agent

> Add Rytiv to Claude Code with one command. Your agent can then deploy apps, create databases and work in computers on Rytiv.

Rytiv runs an MCP server at `https://api.rytiv.app/v1/mcp`. Connect your agent to it once, and the agent sees Rytiv's [tools](https://docs.rytiv.com/reference/mcp-tools.md): it can list and deploy apps, read their logs, set secrets, create Postgres databases and branches, run read-only SQL, and create, use and snapshot computers.

## Before you start

You need a Rytiv account and an API key. Accounts come from the waitlist on rytiv.com, and every admitted account starts with 100 EUR of [credit](https://docs.rytiv.com/billing.md). A key acts for your whole organization unless you narrow it, so treat it like a password.

## 1. Create an API key

Create a key in the Rytiv console (Team, then Tokens), or with the CLI if you have it installed. The value is shown exactly once.

**CLI**

```bash
ry tokens create claude-code --agent sandbox
```

**curl**

```bash
curl -X POST https://api.rytiv.app/v1/tokens \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-code", "agent": {"class": "sandbox"}}'
```

`--agent sandbox` makes it an [agent key](https://docs.rytiv.com/authentication.md#agent-keys): it can do what a key of your organization can do, except create, reveal or revoke credentials. Add `--app <name>` to limit it to the apps you name. Creating a key over the API needs a key already, so your first one comes from the console or from `ry login`. See [Authentication](https://docs.rytiv.com/authentication.md).

## 2. Add Rytiv to Claude Code

Run this in a terminal, with your key in place of `<your key>`:

```bash
claude mcp add --transport http rytiv https://api.rytiv.app/v1/mcp --header "Authorization: Bearer <your key>"
```

This adds a server named `rytiv` in the default scope, for you in the current project. Add `--scope user` to use it in all your projects.

> **Keep the key out of shared files:** To share the setup with your team through a project's `.mcp.json`, reference an environment variable instead of the key. Claude Code expands `${VAR}` in the `url` and `headers` of an HTTP server:
>
> ```json
> {
>   "mcpServers": {
>     "rytiv": {
>       "type": "http",
>       "url": "https://api.rytiv.app/v1/mcp",
>       "headers": { "Authorization": "Bearer ${RYTIV_TOKEN}" }
>     }
>   }
> }
> ```
>
> Each person then sets `RYTIV_TOKEN` in their own environment.

## 3. Check the connection

```bash
claude mcp list
```

The list shows `rytiv` with its status. Inside Claude Code, `/mcp` shows the same.

## 4. Ask your agent to build

Start Claude Code in your project and ask in plain words. A few first prompts:

- "List my apps on Rytiv."
- "Deploy `nginx:alpine` on Rytiv as an app called `hello` (it listens on port 80) and give me its URL."
- "Show me the logs of `hello`."
- "Create a Postgres database called `appdb` on Rytiv, branch it, and try the migration on the branch."
- "Create a computer on Rytiv, clone my repository into it and run the tests there."

The agent picks the tools itself. Every tool carries annotations that your client can use to decide which calls to confirm with you: `readOnlyHint` on all of them, and `destructiveHint` and `idempotentHint` on the tools that write. `execute_sql` only reads unless you name a branch, so a write goes to a copy and never to the database itself.

## Let read-only tools run without asking

In Claude Code, the tools of a server named `rytiv` are called `mcp__rytiv__<tool>`. To stop Claude Code from asking before the tools that only read, allow them in your project's `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": ["mcp__rytiv__search_docs", "mcp__rytiv__list_apps", "mcp__rytiv__get_logs"]
  }
}
```

Leave the tools that change something on asking until you trust the setup.

## Other agents and clients

The Codex plugin and the Cursor install link follow; both connect to the same endpoint with the same key. Until then, any MCP client that speaks Streamable HTTP with a bearer header can use the address above. For Codex that is `codex mcp add rytiv --url https://api.rytiv.app/v1/mcp --bearer-token-env-var RYTIV_TOKEN`, with `RYTIV_TOKEN` set in the environment Codex starts from.

**Hosted connectors** that sign in with OAuth, for example a custom connector in claude.ai, need nothing but the address `https://api.rytiv.app/v1/mcp`: they register themselves, you approve the connection once in the Rytiv console, and no key is pasted anywhere. See [Connect without a key](https://docs.rytiv.com/authentication.md#connect-without-a-key).

Passkey confirmations for irreversible steps are not yet available, see [Confirmations](https://docs.rytiv.com/concepts/confirmations.md).

## What the key can do

A key without an agent class acts as your organization: everything the tools allow, in every app of your organization, and nothing outside it. An agent key is held to its class by the platform, not by the prompt: `sandbox` and `twin` may do what your organization's keys do, except create, reveal or revoke credentials; `production` may only read. With `--app`, the key reaches the named apps and nothing else. The details and the error codes are under [Agent keys](https://docs.rytiv.com/authentication.md#agent-keys).

## Next steps

- [MCP tools](https://docs.rytiv.com/reference/mcp-tools.md): every tool with its parameters.
- [How Rytiv works](https://docs.rytiv.com/concepts/how-it-works.md): what your agent is creating.
- [Computers](https://docs.rytiv.com/computers.md): a machine of its own for your agent, with Codex, OpenCode, Node.js, git and gh preinstalled, and how to run Claude Code inside it.
- [Agents and tokens](https://docs.rytiv.com/guides/agents-and-tokens.md): a key per agent, narrowed by class, apps and scopes, and the audit of what it did.
- [CLI reference](https://docs.rytiv.com/reference/cli.md) and [API reference](https://docs.rytiv.com/reference/api.md): the same platform from your terminal and your code.

---

<!-- Get started: https://docs.rytiv.com/authentication/ -->

# Authentication

> Every request to Rytiv carries an API key as a bearer token. Create keys in the console, with the CLI or over the API, narrow them with scopes or an agent class, and revoke them at any time.

Rytiv has one kind of credential for programs: an **API key**. It belongs to your organization, it is sent as a bearer token, and the same key works for the REST API, the MCP server and the CLI.

```http
Authorization: Bearer ryt_...
```

Keys start with `ryt_`. Rytiv stores only a hash of a key, so a key is shown exactly once, when it is created. After that, only its first characters (the `prefix`) are visible.

## Create a key

**CLI**

```bash
ry tokens create ci-deploy
```

**curl**

```bash
curl -X POST https://api.rytiv.app/v1/tokens \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-deploy"}'
```

**TypeScript**

```ts
const res = await fetch("https://api.rytiv.app/v1/tokens", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RYTIV_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "ci-deploy" }),
});
const { id, prefix, token } = await res.json(); // token is shown only in this answer
```

`POST /v1/tokens` takes a `name` (1 to 120 characters) and answers `201` with `id`, `name`, `prefix` and `token`. Store `token` right away: neither the API nor the CLI can show it again.

You can also create a key in the Rytiv console. Every way creates the same kind of key. Creating a key needs a full key: a key narrowed by [scopes](#narrow-a-key-scopes) or an [agent class](#agent-keys) cannot create, reveal or revoke keys.

### Request fields

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | 1 to 120 characters |
| `scopes` | string[] | Up to 20 [scopes](#narrow-a-key-scopes). Without it, the key is the whole organization. |
| `ttlSeconds` | integer | The key stops working after this long: 60 seconds to 365 days |
| `expiresAt` | string | Or: the moment it stops working (ISO 8601). Not together with `ttlSeconds`. |
| `agent` | object | Makes it an [agent key](#agent-keys): `{class, apps, prodDataRead}` |

## Narrow a key: scopes

A key without scopes may do everything your organization may do. A scope list makes it do less, never more:

| Scope | What it allows |
| --- | --- |
| `read` | Every read of the product API, except credentials and billing |
| `deploy` | The deploy routes of every app: build, deploy, rollback, releases, logs, secrets. Never create or delete an app, never a key. |
| `deploy:<app>` | The same for exactly that app |
| `mail:send` | Sending mail from any of your sending domains |
| `mail:send:<domain>` | Sending mail from exactly that domain |

```bash
ry tokens create ci --deploy web --expires-in 30d
```

A scope the platform does not know is refused with `400` when the key is created, never stored as a key that silently does less than its name says.

## Agent keys

A coding agent works with a key a person handed over without watching every request. So the platform, not the agent's prompt, holds the key to what it is meant for. `agent` on `POST /v1/tokens` takes:

| Field | Type | Notes |
| --- | --- | --- |
| `class` | string | `sandbox`, `twin` or `production` |
| `apps` | string[] | Optional, 1 to 50 app names. Without it, the whole organization. |
| `prodDataRead` | boolean | `production` only: may the agent read what production holds (the database, files, a shell), not only what it says about itself |

```bash
ry tokens create claude-code --agent sandbox --app web --app worker
ry tokens create claude-code-prod --agent production --read-prod-data
```

What every request with an agent key is judged by, in this order:

1. **Credentials are never reachable.** Creating, revealing or revoking keys, SSH keys, webhooks and Git installations, approving a device login, administering the organization: refused for every class with `403` and the code `agent-token-credential`.
2. **The app list, when there is one.** A request that names an app outside the list, or a change that names no app at all, is refused with `403` and `agent-token-app-scope`.
3. **The class.** `sandbox` and `twin` may do what a key of your organization may do. `production` may read what the platform says about a resource (status, releases, logs); a change answers `403` with `agent-token-production-readonly`, and reading what production holds answers `403` with `agent-token-production-data` unless the key has `prodDataRead`.
4. **Its own organization only.** The header `X-Rytiv-Org` is refused with `agent-token-delegation`.

`scopes` and `agent` combine: the platform holds both, and the narrower one wins.

Every action of an agent key is written to an audit before it runs; if the audit cannot be written, the action does not run (`503`, `agent-audit-unavailable`). `GET /v1/agent-actions` lists the audit of your organization, newest first, with `?token=<id>` for one key and `?limit=` up to 500.

A key's class is what the person who created it says it is for. The platform does not know yet which app is production; the app list is what keeps a sandbox key away from production apps today. With [projects](https://docs.rytiv.com/concepts/projects.md) the class picks the environment of the project, and the list goes.

## List and revoke keys

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/v1/tokens` | Your keys, without their values: `id`, `name`, `prefix`, `createdAt`, `lastUsedAt`, and `scopes`, `agent`, `expiresAt` where set |
| `DELETE` | `/v1/tokens/:id` | Revokes a key. Requests already using it are rejected right away. Answers `204`. |

```bash
ry tokens list
ry tokens revoke tok-1a2b3c4d
```

## Connect without a key

A hosted connector has no place to paste a key, so `/v1/mcp` also accepts OAuth 2.1. A client that supports it needs nothing but the address `https://api.rytiv.app/v1/mcp`:

1. A request without a token answers `401` with `WWW-Authenticate: Bearer resource_metadata=...`. The client reads `/.well-known/oauth-protected-resource/v1/mcp` and `/.well-known/oauth-authorization-server` from there.
2. It registers itself at `POST /v1/oauth/register` (RFC 7591) and gets a client id. There are no client secrets: every client is a public client, and the exchange is bound to PKCE with `S256`.
3. `GET /v1/oauth/authorize` sends you to the Rytiv console, where you see which client wants to connect to which organization and approve or deny it once.
4. The client exchanges the code at `POST /v1/oauth/token` for an access token, valid for one hour, and a refresh token, valid for 30 days and rotated on every use.

The scopes are `mcp` and `offline_access`, nothing finer. The access token is an API key of the organization that approved, named after the client; it appears in `GET /v1/tokens` and is revoked like any other key, which ends the connection. Redirect addresses must be `https`, a loopback `http` address, or a native app's own scheme.

## Sign in with the CLI

On your own machine, `ry login` is the easier way. It shows a code, you confirm it in the console, and the CLI stores a key for itself.

```bash
ry login
```

Where nobody can open a browser (CI, a container, a coding agent), give the CLI a key instead:

```bash
ry login --token <token>
```

Or set it in the environment, which the CLI never writes to disk:

| Variable | Meaning |
| --- | --- |
| `RYTIV_TOKEN` | The API key for this shell. Takes precedence over a saved login. |
| `RYTIV_ENDPOINT` | The API endpoint to talk to. Without it, the CLI uses `https://api.rytiv.app`. |
| `RYTIV_PROFILE` | Which saved login to use, if you keep several (`ry profile`). |

The CLI keeps saved logins in `~/.rytiv/config.json`, readable only by you.

## Errors

A request without a key answers `401` with `missing api token (Authorization: Bearer <token>)`, a request with an unknown, expired or revoked key answers `401` with `invalid api token`. A key that may not do what the request asks answers `403` with one of the codes above. All of them follow the [error format](https://docs.rytiv.com/reference/api-basics.md#errors).

## What a key can do

A key acts as your organization: it reaches every app, database, computer and sandbox the organization has, and nothing of any other organization. A name that belongs to another organization is answered exactly like a name that does not exist. Scopes and an agent class narrow that, and the platform enforces both. The guide [Agents and tokens](https://docs.rytiv.com/guides/agents-and-tokens.md) walks through a key per agent, OAuth for hosted clients and the audit of what an agent did.

> **Not yet available:** **Passkey confirmations** for irreversible steps, so that a `production` key can change what can be undone and a person confirms the rest. See [Confirmations](https://docs.rytiv.com/concepts/confirmations.md).

---

<!-- Get started: https://docs.rytiv.com/agents/ -->

# Docs for agents

> These docs are written for people and for coding agents. Every page is available as Markdown, and the whole set as one file.

Your agent does not need to scrape this site. Everything here is also served as plain Markdown, generated from the same source as the pages you read.

## llms.txt

[`/llms.txt`](https://docs.rytiv.com/llms.txt) lists every page with a one-line description and a link to its Markdown form, grouped like the sidebar. It follows the format proposed at llmstxt.org.

[`/llms-full.txt`](https://docs.rytiv.com/llms-full.txt) is the whole documentation in one file, in sidebar order, each page introduced by its address.

## Every page as Markdown

Add `.md` to the path of any page:

```bash
curl https://docs.rytiv.com/quickstart.md
curl https://docs.rytiv.com/reference/mcp-tools.md
```

The start page is at `/index.md`. Links inside the Markdown point at the Markdown form of the linked page.

## Copy page

Every page has a **Copy page** button next to its title. It copies the page's Markdown, so you can paste it into a conversation with your agent.

## Inside the agent

Once your agent is [connected](https://docs.rytiv.com/quickstart.md), it has the tool `search_docs`. It answers questions about how Rytiv works from a knowledge base inside the platform, without a request to this site.

## Generated, not written twice

The [MCP tools](https://docs.rytiv.com/reference/mcp-tools.md) page is generated from the table the MCP server answers `tools/list` with, and the [CLI reference](https://docs.rytiv.com/reference/cli.md) from the CLI's own command definitions. If a parameter is listed there, the server or the CLI accepts it.

---

<!-- Guides: https://docs.rytiv.com/guides/deploy-nextjs/ -->

# Deploy a Next.js app

> From a Next.js directory to a URL with one command, then secrets, logs, releases and rollbacks. The same path works for every framework Rytiv detects.

`ry deploy` reads your project, uploads it, builds it on Rytiv's build machines and deploys the result behind `https://<app>.rytiv.app`. Next.js is detected from `next` in your dependencies; nothing in the project has to change.

## Before you start

- A Rytiv account and the CLI: `curl -fsSL https://get.rytiv.com/install.sh | sh`, then `ry login`. See [Authentication](https://docs.rytiv.com/authentication.md).
- A Next.js project with a `package-lock.json` (the builder runs `npm install --include=dev`; a pnpm, yarn or bun lockfile without a `package-lock.json` is ignored, with a note).

## 1. Deploy

1. From the project directory, deploy to an app named `web`:

   ```bash
   ry deploy web --source .
   ```

   The app is created if it does not exist. The CLI prints what it detected (framework, build and start command, port), uploads the directory, shows the build's place in line and its progress, then rolls the deploy.

2. Open the URL the last line prints: `https://web.rytiv.app`.

3. Save the settings so the next deploy needs no flags:

   ```bash
   ry config init web
   ```

   This writes a `rytiv.json` next to your code. `ry deploy` reads it from the current directory or any directory above it; a flag on the command line always wins over the file.

Or run `ry` on its own in the directory: it signs you in if needed, shows what it detected, asks for an app name and deploys. `ry new next my-site` scaffolds a new Next.js project with a `rytiv.json`.

## What is detected

| What | Value for Next.js |
| --- | --- |
| Build command | `npm run build` |
| Start command | `npx next start -H 0.0.0.0 -p $PORT` |
| Port | `3000`, unless `.env.example` sets `PORT` or the start script passes `-p` |
| Build machine | 8192 MB, 4 vCPU (the larger of the two build sizes; Next.js and Dockerfile builds get it) |
| Suggested machine | 1024 MB, 1 vCPU for a new app |
| Served at the edge | `.next/static` at `/_next/static`, and `public/` at `/` |

A `Dockerfile` or `Containerfile` at the root of the directory wins over the detection. `next.config.js` (also `.mjs`, `.cjs`, `.ts`) is read as text, never executed; `output: "export"` makes the app a static site served from `out/` without a machine.

What is uploaded: the directory without `node_modules`, `.git`, `.next`, `.svelte-kit`, `.nuxt`, `.output`, `.astro`, `.env.local` and `.env.*.local`. Your `.gitignore` is not applied; a `.env` file is uploaded, and the CLI warns about `.env*` files that git ignores.

> **The port:** The platform exports `PORT=3000` (with `HOST=0.0.0.0` and `NODE_ENV=production`) into the machine; `--port` tells Rytiv where to route and probe, it does not change `PORT`. If your app must listen on another port, set `PORT` yourself with `ry deploy -e PORT=8080 --port 8080`, or keep 3000.

## 2. Environment and secrets

**CLI**

```bash
ry secrets set web DATABASE_PASSWORD=example-value
ry secrets set web NEXT_PUBLIC_SITE_URL=https://www.example.com --build
ry deploy web -e LOG_LEVEL=info
```

**curl**

```bash
curl -X PUT "https://api.rytiv.app/v1/apps/web/secrets" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secrets": {"DATABASE_PASSWORD": "example-value"}, "build": {"DATABASE_PASSWORD": false}}'
```

**TypeScript**

```ts
await fetch("https://api.rytiv.app/v1/apps/web/secrets", {
  method: "PUT",
  headers: { Authorization: `Bearer ${process.env.RYTIV_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ secrets: { DATABASE_PASSWORD: "example-value" } }),
});
```

**Python**

```python
import os, requests

requests.put(
    "https://api.rytiv.app/v1/apps/web/secrets",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
    json={"secrets": {"DATABASE_PASSWORD": "example-value"}},
)
```

- **Secrets** are stored encrypted and never readable back. They reach the app at its next deploy; `ry secrets set --now` rolls the app right away.
- **Runtime or build.** Every secret is available to the running app. Only secrets marked for the build are visible to `next build`: a new secret whose name starts with `NEXT_PUBLIC_` (or `VITE_`, `PUBLIC_`, `NUXT_PUBLIC_`, `GATSBY_`, `REACT_APP_`) is marked by default, anything else needs `--build`. `--no-build` takes the mark away. In the API this is the `build` map of `PUT /v1/apps/:name/secrets`.
- **Plain variables** (`-e KEY=VALUE`) are stored in the clear and shown in `ry machines`; use them for settings, not credentials.

A [Postgres database](https://docs.rytiv.com/postgres.md) attached with `ry attach appdb --to web` gives the app its `DATABASE_URL` as a managed secret.

## 3. Watch it run

```bash
ry logs web -f
ry status
ry machines web
```

`ry logs` shows what the app's machines write to their console; `-f` follows. A machine is `running` when it answers on its port.

## 4. Health checks and sizes

```bash
ry deploy web --health-path /api/health --health-timeout 90
ry deploy web --memory 2048 --vcpus 2
```

With `--health-path`, a new machine gets traffic only after that path answered `2xx` or `3xx`; without it, the port alone decides. A size you do not name keeps the app's current one. See [`ry deploy`](https://docs.rytiv.com/reference/cli/deploy.md) for every flag.

## 5. Releases and rollback

```bash
ry deploys web
ry releases web
ry rollback web
```

Every deploy that goes live is a release. `ry rollback web` deploys the previous release's image again, without a rebuild and with the app's current settings; `ry rollback web 3` names a version. Secrets, volumes and databases stay as they are.

After a deploy switches traffic, Rytiv watches the app's error rate for five minutes against the rate before the switch. If at least 20 requests came in and the share of `5xx` answers is clearly worse than before (at least 5 percent, and more than three times the old rate plus two points), the deploy is rolled back on its own. The verdict is in the deploy's `watch` field (`GET /v1/deploys/:id`): `healthy`, `unproven` (not enough traffic to judge), `rolled-back`, and a few more. Databases are never rolled back automatically.

## 6. Deploy on push

```bash
ry git connect web --repo acme/web --branch main
```

This installs Rytiv's GitHub app through the browser and links the app to the repository. Every push to the branch builds and deploys through the same path as `ry deploy`; `ry git status web` shows the last push. Previews (`ry preview create web --branch feature/login`) are apps of their own per branch, protected by a link, closed when the branch or pull request closes or after 14 idle days, at most 10 per app.

## Next

- [Custom domains and TLS](https://docs.rytiv.com/guides/custom-domains.md): put `www.example.com` on the app.
- [Cron and jobs](https://docs.rytiv.com/guides/cron-and-jobs.md): call a path on a schedule, run a migration as a job.
- [Apps](https://docs.rytiv.com/apps.md): everything an app can do, and the deploy request field by field.

---

<!-- Guides: https://docs.rytiv.com/apps/ -->

# Apps

> Deploy from a source directory or a prebuilt image. Rolling deploys, secrets, logs, releases and rollbacks.

An app is a name with an address. It runs one or more machines from an image you deploy, or, for a static site, no machine at all. Machines, deploys, secrets, logs and releases all belong to an app.

## Names and addresses

App names are unique across all of Rytiv: 2 to 63 characters, lowercase letters, digits and hyphens, starting with a letter. A few names are reserved for the platform (for example `api`, `console`, `docs` and `www`, and every name that is `rytiv` or starts with `rytiv-`).

An app answers on `https://<app>.rytiv.app`. Extra ports of a machine answer on `https://<port>-<app>.rytiv.app`.

## Deploy from source

Point the CLI at a directory. Rytiv reads the project, builds it on its own machines and deploys the result:

```bash
ry deploy web --source .
```

Or run `ry` alone in the directory: it signs you in if needed, shows what it detected, asks for an app name and deploys.

```bash
ry
```

**What is detected.** Node.js projects with these frameworks: Next.js, SvelteKit, Nuxt, Remix, TanStack Start, SolidStart, Analog, Astro, Vite, Gatsby, Docusaurus, Create React App, VitePress, Eleventy and Angular, plus plain Node.js. A `Dockerfile` or `Containerfile` at the root of the directory wins over the detection; anything that is not Node.js needs one. `ry detect` shows the finding without changing anything.

**Static sites** (for example Astro without an adapter, Next.js with `output: "export"`, Vite, or a folder with an `index.html`) need no machine: the built files are served directly.

### rytiv.json

`ry deploy` reads a `rytiv.json` in the current directory or above it, so a deploy needs no flags. `ry config init <app>` writes one. A flag on the command line always wins over the file.

```json
{
  "app": "web",
  "source": ".",
  "port": 3000,
  "memoryMb": 512,
  "vcpus": 1
}
```

Other keys: `image` (instead of `source`), `diskMb`, `buildMemoryMb`, `count`, `start`, `healthPath`, `healthTimeoutS`, `restart`, `killSignal`, `killTimeoutS`, `sleep` and `env`. An unknown key is an error.

## Deploy an image

**CLI**

```bash
ry deploy web --image nginx:alpine --port 80
```

**curl**

```bash
curl -X POST https://api.rytiv.app/v1/apps \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "web"}'

curl -X POST https://api.rytiv.app/v1/apps/web/deploy \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image": "nginx:alpine", "internalPort": 80}'
```

**TypeScript**

```ts
const api = "https://api.rytiv.app/v1";
const headers = {
  Authorization: `Bearer ${process.env.RYTIV_TOKEN}`,
  "Content-Type": "application/json",
};

await fetch(`${api}/apps`, { method: "POST", headers, body: JSON.stringify({ name: "web" }) });
const res = await fetch(`${api}/apps/web/deploy`, {
  method: "POST",
  headers,
  body: JSON.stringify({ image: "nginx:alpine", internalPort: 80 }),
});
const deploy = await res.json(); // { id, status: "running", ... }
```

`POST /v1/apps` answers `201`, or `409` with `name-taken` if the name is used anywhere on Rytiv. `POST /v1/apps/:name/deploy` answers `202` with the deploy. Poll `GET /v1/deploys/:id` until `status` is `done` or `error`. On `error`, the answer names the reason in `error` and carries the last lines of the machine's console in `bootLog`.

### Deploy request

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `image` | string | required | An OCI reference such as `nginx:alpine`, or `build:<id>` for a build of yours |
| `internalPort` | integer | `3000` | The port your app listens on |
| `memoryMb` | integer | kept, `512` for a new app | 128 to 16384 |
| `vcpus` | integer | kept, `1` for a new app | 1 to 16 |
| `diskMb` | integer | kept | 512 to 131072 |
| `count` | integer | kept, `1` for a new app | Machines, 1 to 20 |
| `env` | object | `{}` | Plain environment variables. Use [secrets](#secrets) for credentials. |
| `start` | string | | Start command, run through `/bin/sh -c` |
| `healthCheck` | object | | `path` for an HTTP check (empty: the port only), `timeoutMs`, `intervalMs`, `healthyThreshold`, `maxWaitMs` |
| `restart` | object | | `policy`: `never` or `on-failure`, with `retries` 1 to 10. Without it, a crashed machine is restarted. |
| `killSignal` | string | the image's, else `SIGTERM` | Sent before a machine is stopped or replaced |
| `killTimeoutS` | integer | `30` | Seconds between that signal and `SIGKILL`, 1 to 300 |

"Kept" means: a deploy that does not name the field keeps what the app's machines have. Every other field comes from the request or its default, so send `internalPort`, `env` and `start` with every deploy.

### How a deploy rolls

A deploy starts a new machine, waits until it runs and answers on its port (and passes the health check, if you set one), then takes one old machine out of traffic and removes it, one at a time. If a new machine fails, the deploy stops, the new machine is discarded and the old version keeps serving.

An app with a volume works differently: its single machine stops before the new one starts, so there is a short gap.

### Sleep when idle

An app sleeps only if you give it a sleep rule. Without one, its machines run until you stop them. Name the idle time on a deploy:

```bash
ry deploy web --sleep 5m
```

A machine that has had no requests and no CPU load for that long goes to sleep, and the next request wakes it. Up to 2 GB of memory it sleeps with its memory and resumes in about a quarter of a second; a larger machine stops instead and boots cold, and its files stay. `--sleep off` takes the rule away again, for a worker or a cron app that has to stay awake. In a [deploy request](#deploy-request) the same rule is `suspendPolicy`, for example `{"mode": "suspend", "idleSeconds": 300}`.

## Secrets

Secrets are environment variables stored encrypted. Nobody can read them back, not even you: the API lists names, never values.

**CLI**

```bash
ry secrets set web API_KEY=example-value OTHER_KEY=other-value
```

**curl**

```bash
curl -X PUT https://api.rytiv.app/v1/apps/web/secrets \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secrets": {"API_KEY": "example-value"}, "staged": true}'
```

| Method | Path | What it does |
| --- | --- | --- |
| `PUT` | `/v1/apps/:name/secrets` | `{secrets, staged}`. With `staged: true` (the default) the values apply at the next deploy. With `staged: false` Rytiv rolls the app now if a machine lacks the new value. |
| `GET` | `/v1/apps/:name/secrets` | `name`, `updatedAt` and `managed` for every secret. Never a value. |
| `DELETE` | `/v1/apps/:name/secrets/:key` | Removes one secret. `204`. |

Secrets that Rytiv manages for you, such as the `DATABASE_URL` of an [attached database](https://docs.rytiv.com/postgres.md#2-connect-from-an-app), cannot be changed or removed this way. Each secret carries a `build` choice: whether the next source build sees it. A new secret is marked for the build only when its name starts with a public prefix such as `NEXT_PUBLIC_` or `VITE_`; `ry secrets set <app> KEY --build` marks one, `--no-build` takes the mark away.

## Logs

```bash
ry logs web -f
```

`GET /v1/apps/:name/logs` answers `{app, machines}`, one entry per machine with the console output of that machine in `text` and a `cursor`. Pass `cursor.<machineId>=<cursor>` on the next call to get only what is new, and `machine=<id>` for one machine.

Logs are what your app's machines write to their console.

## Machines

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/v1/apps/:name/machines` | The app's machines |
| `GET` | `/v1/machines/:id` | One machine |
| `POST` | `/v1/machines/:id/start` | Start a stopped or suspended machine |
| `POST` | `/v1/machines/:id/stop` | Stop it |
| `POST` | `/v1/machines/:id/suspend` | Suspend it |
| `POST` | `/v1/machines/:id/destroy` | Remove it |

A machine is `requested`, `scheduled`, `starting`, `running`, `suspending`, `suspended`, `stopping`, `stopped`, `deleted` or `failed`.

```bash
ry machines web
ry exec web -- ls -la /app
```

## Releases and rollback

Every deploy is a release. A rollback deploys an earlier release's image again, without a rebuild, with the app's current settings. Secrets, volumes and databases stay as they are.

```bash
ry releases web
ry rollback web
```

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/v1/apps/:name/releases` | The releases, which one runs, and which one a rollback would bring back |
| `POST` | `/v1/apps/:name/rollback` | `{}` for the previous release that went live, or `{version}` or `{releaseId}`. Answers `202` with the deploy. |

## Delete an app

```bash
ry apps destroy web
```

`DELETE /v1/apps/:name` removes the app and all its machines and answers `204`. It cannot be undone. The CLI asks before it does this; pass `--yes` in scripts. An app that runs a [database](https://docs.rytiv.com/postgres.md) is removed with the database, not on its own.

## Errors you will meet

| Status | Code | When |
| --- | --- | --- |
| `400` | `name-reserved` | The name is reserved for the platform |
| `409` | `name-taken` | The name is used somewhere on Rytiv |
| `403` | `org-limit-apps` | An account on the starting credit can have 10 apps, computers included. See [Credit and pricing](https://docs.rytiv.com/billing.md#limits-on-the-starting-credit). |
| `402` | `credit-blocked` | The credit is used up: nothing new starts until a top-up. See [Credit and pricing](https://docs.rytiv.com/billing.md#when-the-credit-is-used-up). |
| `404` | `build-not-found` | `build:<id>` is not a build of your organization |
| `409` | `deploy-in-flight` | Another deploy of this app is running |
| `409` | `volume-needs-single-machine` | An app with a volume runs exactly one machine |

See the [CLI reference](https://docs.rytiv.com/reference/cli/deploy.md) for every flag of `ry deploy`, and [Apps](https://docs.rytiv.com/reference/api/apps.md) and [Deploys and releases](https://docs.rytiv.com/reference/api/deploys.md) in the API reference for every route with its fields. The guide [Deploy a Next.js app](https://docs.rytiv.com/guides/deploy-nextjs.md) walks the path from a directory to a URL.

---

<!-- Guides: https://docs.rytiv.com/computers/ -->

# Computers

> A computer is a machine of its own for a coding agent. Create one, connect Claude Code to it, work in it over a shell or its desktop, and let it shut down when idle; the home disk stays.

Some work needs a place whose files are still there tomorrow: a checkout, a half-finished migration, the notes of a long task. A computer is that place. It is an app with one machine that runs the computer image, a home disk mounted at `/data` that outlives the machine, and a desktop you can watch or take over from the console.

## Sizes

| Size | vCPU | Memory | Home disk |
| --- | --- | --- | --- |
| `small` | 1 | 2304 MB | 50 GB |
| `base` (default) | 2 | 4096 MB | 100 GB |
| `large` | 4 | 8192 MB | 128 GB |

An organization on starting credit may run 2 computers at a time; see [Limits and quotas](https://docs.rytiv.com/concepts/limits.md).

## 1. Create a computer

**Console**

Open **Computers**, choose **New computer**, give it a name and a size. The console creates the app, the home disk and the key, and deploys the computer image.

**CLI**

```bash
ry computer create dev-1 --image rytiv/computer:0.1.0
ry computer create dev-2 --size large --image rytiv/computer:0.1.0
```

`--image` names the computer image: Rytiv's released image `rytiv/computer:<version>`, or a `build:<id>` of your own. Without `--image`, the CLI reads `RYTIV_COMPUTER_IMAGE` from the environment and refuses when neither is set.

**curl**

A computer is an app created with `computer: true`, a home volume attached to it, a secret `COMPUTER_VIEW_KEY` the desktop needs, and a deploy of the computer image with the size and a sleep rule. The CLI runs these calls in that order:

```bash
curl -X POST "https://api.rytiv.app/v1/apps" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "dev-1", "computer": true}'
```

Then `POST /v1/volumes` (`dev-1-home`), `POST /v1/apps/dev-1/attach` with the volume, `PUT /v1/apps/dev-1/secrets` with `COMPUTER_VIEW_KEY`, and `POST /v1/apps/dev-1/deploy` with `{"image": "rytiv/computer:0.1.0", "memoryMb": 4096, "vcpus": 2, "internalPort": 8080, "suspendPolicy": {"mode": "suspend", "idleSeconds": 600, "stopAfterSeconds": 86400}}`. See the [API reference](https://docs.rytiv.com/reference/api/computers.md).

Names are 2 to 31 characters of lowercase letters, digits and hyphens. The home disk is a volume named `<computer>-home`; it is kept while the computer is shut down and when its machine is replaced.

What the image brings: Node.js with npm, Codex, OpenCode, git, the GitHub CLI, Python 3 with pip, a browser and a desktop. Claude Code is not pre-installed; inside the computer, `rytiv-setup claude` installs it with its own official installer under its own terms (`--stable`, `--version <v>` and `--print` are accepted), and `rytiv-setup` alone shows what the image has and has not.

## 2. Connect Claude Code

Two ways, for two kinds of work.

1. **Claude Code on your laptop, Rytiv as its tool.** Add the MCP server once; the agent then creates computers, runs commands in them and snapshots them with the tools `computer_create`, `computer_exec` and `computer_snapshot`:

   ```bash
   claude mcp add --transport http rytiv https://api.rytiv.app/v1/mcp --header "Authorization: Bearer <your key>"
   ```

   Then ask in plain words: "Create a computer on Rytiv, clone the repository into it and run the tests."

2. **Claude Code inside the computer.** Open a shell in it and install Claude Code there; the session keeps running when your laptop is closed:

   ```bash
   ry ssh dev-1
   ```

   Inside: `rytiv-setup claude`, then `claude`. Sign in with your own Claude account; nothing of it touches Rytiv.

A computer the MCP tool `computer_create` makes is an agent machine: it does not sleep on its own, and it can take [snapshots](#snapshots). A computer from the console or `ry computer create` shuts down when idle and keeps its home; it takes no snapshots.

## 3. Work in it

```bash
ry exec dev-1 -- git status
ry exec dev-1 --dir /data -- npm test
ry ssh dev-1
ry forward dev-1 3000:3000
```

`ry exec` runs one command and exits with its exit code; `ry ssh` opens an interactive shell over the Rytiv API, no SSH keys needed; `ry forward` brings a port of the computer to your machine without a public port. Each of them wakes a shut-down computer. Through MCP, `computer_exec` does what `ry exec` does, as an argument list without a shell.

Files you want to keep go under `/data`, the home. The root disk is the image's and starts fresh at every boot.

## 4. Watch or take over the desktop

```bash
ry computer view dev-1
ry computer control dev-1
ry computer release dev-1
ry computer audit dev-1
```

`view` gives a link to watch, for any number of viewers, valid 60 to 3600 seconds (default 900). `control` gives a link to take keyboard and mouse: there is one holder per machine, the agent inside pauses while you have control, and `--force` takes control from the current holder. `audit` shows who got which link and how control ended. The console shows the same desktop on the computer's page.

## 5. Idle shutdown

After 10 minutes without activity the computer shuts down; your files stay. Every size is above the 2048 MB up to which a machine sleeps with its memory, so a computer stops instead: open programs end, and the next `ry exec`, `ry ssh`, request or console visit boots it fresh with the home disk as it was. CPU load, a held control lease and an open viewer with frames flowing count as activity.

While it is shut down it costs nothing for memory and CPU; the home disk is billed as a volume. See [Credit and prices](https://docs.rytiv.com/billing.md).

## Snapshots

A machine created with `durableCheckpoint: true` (what the MCP tool `computer_create` does, and `POST /v1/apps/:name/machines` with that field) can be snapshotted and restored:

| Method | Path | What it does |
| --- | --- | --- |
| `POST` | `/v1/machines/:id/checkpoints` | `{label, memory, comment}`. Takes a snapshot now. |
| `GET` | `/v1/machines/:id/checkpoints` | The machine's named snapshots |
| `POST` | `/v1/machines/:id/checkpoints/:label/restore` | Brings the machine back to that snapshot. With `keepCurrent: true` (the default) the current state is saved first. |
| `DELETE` | `/v1/machines/:id/checkpoints/:label` | Forgets a snapshot |

Disk only (`memory: false`, the default) is a short pause, and a restore boots fresh with the files as they were. With memory (`memory: true`) a restore resumes the very processes; the pause grows with the machine's memory. Labels use letters, digits, `.`, `-` and `_`, start with a letter or digit, and are at most 63 characters; `auto-` is reserved. Through MCP, `computer_snapshot` takes one. Such a machine also survives a host failure with its last automatic checkpoint.

## Delete

```bash
ry apps destroy dev-1
ry volume destroy vol-1a2b3c4d
```

Deleting the app removes the machine; the home volume stays until you delete it too (`ry volume list` shows it). Both cannot be undone; the CLI asks you to type the name, automation passes `--yes`.

---

<!-- Guides: https://docs.rytiv.com/postgres/ -->

# Postgres

> Create a Postgres database, connect an app or your laptop to it, branch it for an experiment, fork it from a point in time, restore it in place, and set when it sleeps.

A Rytiv database is PostgreSQL 16 on a machine of its own, with its data on a volume and a continuous archive of its write-ahead log. Only apps you attach can reach it, always over TLS. Every database can be **branched** (a copy-on-write copy of its disk, ready in seconds) and **forked** (a full copy from its archive, from now or from a moment in the past), so an agent can change a schema without touching the original.

## 1. Create a database

**CLI**

```bash
ry postgres create appdb
ry postgres create appdb --size 20 --locale en-US
```

**curl**

```bash
curl -X POST "https://api.rytiv.app/v1/resources" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "appdb", "kind": "postgres"}'
```

**TypeScript**

```ts
const res = await fetch("https://api.rytiv.app/v1/resources", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RYTIV_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "appdb", kind: "postgres" }),
});
const db = await res.json(); // db.url is shown in this answer only
```

**Python**

```python
import os, requests

db = requests.post(
    "https://api.rytiv.app/v1/resources",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
    json={"name": "appdb", "kind": "postgres"},
).json()  # db["url"] is shown in this answer only
```

Your agent uses the tool [`create_postgres`](https://docs.rytiv.com/reference/mcp-tools.md#create_postgres), which never returns the password.

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | string | required | Like an [app name](https://docs.rytiv.com/apps.md#names-and-addresses), unique across Rytiv |
| `kind` | string | required | `postgres` |
| `memoryMb` | integer | `1024` | 128 to 16384 |
| `sizeGb` | integer | `10` | Size of the data volume, 4 to 500 |
| `locale` | string | `de-DE` | ICU locale for sorting and comparing text, such as `en-US`. Fixed once the database exists. |
| `durability` | string | `standard` | `standard`: one machine. `host-redundant`: a standby on a second host (API only; a redundant database cannot be branched or forked). |
| `suspendPolicy` | object | suspend after 300 s | When the database sleeps, see [Sleep](#5-sleep). `{"mode": "off"}` keeps it always on. |

`POST /v1/resources` answers `201` with `name`, `kind`, `port`, `secretKey` (`DATABASE_URL`) and `url`. **The `url` contains the password and is returned only here**; the CLI shows it only with `--json`. You do not need to store it if you attach the database to an app: the app gets it as a secret.

## 2. Connect from an app

```bash
ry attach appdb --to web
ry deploy web
```

`POST /v1/apps/:name/attach` with `{"resource": "appdb"}` gives the app a managed secret `DATABASE_URL`. A running machine keeps the environment it started with, so deploy the app again (or stop and start its machine) after attaching. The URL looks like this:

```text
postgres://postgres:<password>@appdb.internal:5432/appdb?sslmode=verify-full&sslrootcert=/etc/rytiv/ca/postgres.crt
```

- `appdb.internal` resolves only inside apps that are attached to the database. Everyone else cannot reach it.
- The database accepts TLS connections only. The certificate authority is at `/etc/rytiv/ca/postgres.crt` in every machine, so `verify-full` works without setup.
- The database name is the resource name with `-` replaced by `_`.

## 3. Connect from your computer

A database has no public address. Open a tunnel with the CLI and connect to the local end:

```bash
ry proxy appdb 15432:5432
psql -h 127.0.0.1 -p 15432 -U postgres appdb
```

The first connection wakes a sleeping database.

## 4. Branch, fork, restore

### Branch a database

A branch is a copy-on-write copy of the database **as it is now**, taken on its host. It is ready in seconds, takes almost no space at first, and is a database of its own with its own password: writes to the branch never reach the source.

**CLI**

```bash
ry postgres branch appdb appdb-try --expires-in 1d
```

**curl**

```bash
curl -X POST "https://api.rytiv.app/v1/resources/appdb/branch" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "appdb-try", "ttlSeconds": 86400}'
```

**TypeScript**

```ts
await fetch("https://api.rytiv.app/v1/resources/appdb/branch", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RYTIV_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "appdb-try", ttlSeconds: 86400 }),
});
```

**Python**

```python
import os, requests

requests.post(
    "https://api.rytiv.app/v1/resources/appdb/branch",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
    json={"name": "appdb-try", "ttlSeconds": 86400},
)
```

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | Name of the new database |
| `ttlSeconds` | integer | Delete the branch after this long, 60 to 2592000 (30 days) |
| `expiresAt` | string | Or: delete it at this moment (ISO 8601). Not together with `ttlSeconds`. |
| `ephemeral` | boolean | Ready faster, without an archive of its own, and lost if its host fails |

The answer is `202` with `state: "restoring"`. Poll `GET /v1/resources/:name` until `state` is `ready`; the CLI waits for you. A database can have up to 15 branches.

This is where an agent changes a schema or tries a migration. Through MCP, [`create_branch`](https://docs.rytiv.com/reference/mcp-tools.md#create_branch) makes one, and [`execute_sql`](https://docs.rytiv.com/reference/mcp-tools.md#execute_sql) only writes when you name a branch of the database; on the database itself it runs read-only.

### Fork from a point in time

A fork is a full copy made from the database's archive, on any host. It takes longer than a branch, minutes for a large database, and can start from any moment the archive covers (7 days):

```bash
ry postgres fork appdb appdb-yesterday --at 2026-10-19T09:00:00Z
```

`POST /v1/resources/:name/fork` takes `name`, an optional `asOf` (ISO 8601) and the same `ttlSeconds` or `expiresAt` as a branch.

### Connection URL of a copy

A branch or fork has its own password. Attach it to an app like any database, or fetch its URL **once**:

```bash
curl -X POST "https://api.rytiv.app/v1/resources/appdb-try/url" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

The answer is `{name, url}`. A second call answers `409` with `url-handed-out`: the URL is handed out exactly once. For the original database, the URL came with the create answer and this route answers `409` with `not-a-copy`. The CLI asks for it right after a branch or fork is ready and prints it with `--json`.

### Restore in place

```bash
ry postgres restore appdb --at 2026-10-19T09:00:00Z
```

`POST /v1/resources/:name/restore` with `{asOf}` puts a database back to that moment. Name, URL and password stay the same; open connections end once, at the switch. The state before the restore is kept as a branch named `<name>-old-<timestamp>`, or the name you pass as `backupName`. The CLI asks before it does this; pass `--yes` in scripts.

### Expiry

`PATCH /v1/resources/:name` with `ttlSeconds` or `expiresAt` sets when a branch or fork is deleted; `"expiresAt": null` keeps it. Only copies can expire.

```bash
ry postgres expire appdb-try --in 12h
ry postgres expire appdb-try --never
```

## 5. Sleep

A standalone database carries a sleep policy: by default it is suspended after 300 seconds without a running query, an open transaction or traffic, and stopped a day after that; the next connection wakes it. A redundant database never sleeps.

```bash
ry postgres sleep appdb --after 10m
ry postgres sleep appdb --off
ry postgres create reports --always-on
```

`PATCH /v1/resources/:name` with `suspendPolicy` changes the rule; `{"mode": "off"}` keeps the database always on. The policy is stored with the database and shown by `ry postgres list`; whether a region's hosts act on it is part of the region's configuration, so do not build on a database being asleep.

## List and delete

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/v1/resources` | Your databases, with `state` (`restoring`, `ready`, `failed`), `sourceName` and `expiresAt` for copies. Never a URL. |
| `GET` | `/v1/resources/:name` | One database |
| `DELETE` | `/v1/resources/:name` | Deletes the database, its machine and its volume, and detaches it from every app. It cannot be undone. |

```bash
ry postgres list
ry postgres destroy appdb-try
```

## Errors you will meet

| Status | Code | When |
| --- | --- | --- |
| `409` | `name-taken` | The name is used somewhere on Rytiv |
| `400` | `name-reserved` | The name is reserved for the platform |
| `503` | `no-capacity` | No room right now, try again |
| `409` | `url-handed-out` | The URL of this copy was handed out already |
| `409` | `not-ready` | The copy is still restoring, or failed |
| `409` | `conflict` | The database already has 15 branches: delete one, or fork |

See [Postgres](https://docs.rytiv.com/reference/api/postgres.md) in the API reference for every field, and the [CLI reference](https://docs.rytiv.com/reference/cli/postgres.md) for every flag of `ry postgres`.

---

<!-- Guides: https://docs.rytiv.com/sandboxes/ -->

# Sandboxes

> Short-lived machines for one task each. A sandbox starts from a template, runs commands and holds files, and is removed at its deadline.

A sandbox is a machine with a deadline. Create it from a template, run commands in it, read and write its files, and let it go: at its deadline Rytiv removes the machine and everything on its disk. Each sandbox has an id like `sbx-1a2b3c4d5e6f` and its own address.

## Create a sandbox

**CLI**

```bash
ry sandbox create app:web --ttl 30m
```

**curl**

```bash
curl -X POST https://api.rytiv.app/v1/sandboxes \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "app:web", "ttlSeconds": 1800}'
```

**TypeScript**

```ts
const res = await fetch("https://api.rytiv.app/v1/sandboxes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RYTIV_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ template: "app:web", ttlSeconds: 1800 }),
});
const sandbox = await res.json();
console.log(sandbox.id, sandbox.state, sandbox.url);
```

`POST /v1/sandboxes` answers when the machine runs, with `201` and the sandbox. The answer also carries `createMs`, the time from your request to the running machine, and, for a sandbox with signed access, an `accessToken`.

### Templates

A sandbox boots the image of a template you already have:

| Template | Boots |
| --- | --- |
| `app:<name>` | The image an app of your organization runs right now. The app must run a machine. |
| `build:<id>` | A build of your organization that produced a machine image (not a static site). |

Nothing else is inherited from the template: no environment variables and no secrets of the app. Pass what the sandbox needs in `env`.

### Request

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `template` | string | required | `app:<name>` or `build:<id>` |
| `ttlSeconds` | integer | `300` | Lifetime from now, 10 to 86400 |
| `vcpus` | integer | `1` | 1 to 16 |
| `memoryMb` | integer | `512` | 128 to 16384 |
| `diskMb` | integer | | 512 to 131072 |
| `env` | object | `{}` | Up to 128 variables, names like `MY_VAR`. A few `RYTIV_` names are reserved. |
| `ports` | integer[] | `[]` | Up to 8 more ports to reach from outside |
| `internalPort` | integer | the template app's port, else `3000` | The port `url` points at |
| `readiness` | `boot` or `port` | `boot` | Ready when the machine boots, or when `internalPort` answers |
| `access` | `signed` or `public` | `signed` | Who can open the sandbox's URLs, see [Access](#access) |
| `idleSeconds` | integer | `300` | 10 to 86400, see the note below |
| `metadata` | object | `{}` | Up to 16 key/value pairs for your own bookkeeping |
| `egress` | object | allow all | Outbound network, see [Network](#network) |

Unknown fields are refused with `400`.

> **Idle sleep:** `idleSeconds` is accepted and stored with the sandbox. Whether a region's hosts put an idle sandbox to sleep is part of the region's configuration; do not build on a sandbox being asleep. Its deadline (`ttlSeconds`) is what ends it.

### The sandbox object

| Field | Meaning |
| --- | --- |
| `id` | `sbx-` and 12 hex digits |
| `template` | The template it was created from |
| `state` | `starting`, `running`, `sleeping` or `ended` |
| `createdAt`, `expiresAt` | When it was created, and its deadline |
| `endedAt`, `endReason` | When and why it ended: `expired`, `killed`, `failed` or `app-deleted` |
| `machineId` | The machine behind the sandbox |
| `vcpus`, `memoryMb`, `readiness`, `access`, `metadata`, `egress` | As requested |
| `url` | `https://<id>.rytiv.app` |
| `ports` | One `{port, url}` per extra port, with `url` like `https://<port>-<id>.rytiv.app` |

## Access

With `access: "signed"` (the default), the sandbox's URLs only answer requests that carry a token. The create answer contains one:

```json
"accessToken": { "token": "...", "expiresAt": "...", "header": "x-rytiv-access" }
```

Send it in the header named by `header`. It is valid for the lifetime the sandbox was created with, at most 24 hours. With `access: "public"`, anyone with the URL can open it.

## Run a command

**CLI**

```bash
ry sandbox exec sbx-1a2b3c4d5e6f -- uname -a
```

**curl**

```bash
curl -X POST https://api.rytiv.app/v1/sandboxes/sbx-1a2b3c4d5e6f/exec \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cmd": ["uname", "-a"]}'
```

**TypeScript**

```ts
const res = await fetch(`https://api.rytiv.app/v1/sandboxes/${id}/exec`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RYTIV_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ cmd: ["uname", "-a"] }),
});
const { exitCode, stdout, stderr } = await res.json();
```

`POST /v1/sandboxes/:id/exec` waits for the command and answers with its result.

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `cmd` | string or string[] | required | A string runs through `/bin/sh -c`, an array is the argument list (no shell) |
| `cwd` | string | | An absolute path |
| `env` | object | | More environment for this command |
| `timeoutMs` | integer | `60000` | 1000 to 600000, and never past the sandbox's deadline |
| `stdin` | string | | Up to 1 MiB |

The answer has `exitCode`, `signal`, `timedOut`, `durationMs`, `stdout` and `stderr`. Each output stream is cut at 1 MiB, and `stdoutTruncated` or `stderrTruncated` say so.

`ry sandbox exec` exits with the command's own exit code, `124` on a timeout, `128 + n` when signal `n` ended it, and `255` for an error of its own.

## Files

| Method | Path | Body and answer |
| --- | --- | --- |
| `GET` | `/v1/sandboxes/:id/files?path=/abs/path` | The file's bytes |
| `PUT` | `/v1/sandboxes/:id/files?path=/abs/path` | Send the bytes. Optional `mode` (default `0644`) and `mkdirs=1`. Answers `{path, bytes, sha256}`. |
| `GET` | `/v1/sandboxes/:id/files/list?path=/abs/dir` | `{path, entries}`, each entry `{name, type, size, mode, mtimeMs}` |

Paths are absolute and may not contain `..`. One file is at most 64 MiB.

```bash
curl -X PUT "https://api.rytiv.app/v1/sandboxes/sbx-1a2b3c4d5e6f/files?path=/tmp/hello.txt" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  --data-binary "hello"
```

## Network

`egress` decides what the sandbox may reach:

| `mode` | Meaning |
| --- | --- |
| `allow-all` | The default |
| `deny-all` | Nothing, not even DNS |
| `allowlist` | Only the listed `domains` (up to 100, a leading `*.` allowed) and IPv4 `cidrs` (up to 10), on ports 80 and 443 |

The policy is fixed for the sandbox's lifetime.

```json
{ "template": "app:web", "egress": { "mode": "allowlist", "domains": ["api.github.com", "*.npmjs.org"] } }
```

## Extend, list, end

| Method | Path | What it does |
| --- | --- | --- |
| `POST` | `/v1/sandboxes/:id/timeout` | `{ttlSeconds}`: the new deadline is now plus `ttlSeconds` (10 to 86400). Calling it twice does not add up. |
| `GET` | `/v1/sandboxes` | Running sandboxes, newest first. `?state=all` adds the ones that ended in the last 14 days. |
| `GET` | `/v1/sandboxes/:id` | One sandbox |
| `DELETE` | `/v1/sandboxes/:id` | Ends it now. `204`, or `202` if it is already ending. Its machine and disk are gone. |

```bash
ry sandbox timeout sbx-1a2b3c4d5e6f 1h
ry sandbox list --all
ry sandbox kill sbx-1a2b3c4d5e6f
```

## Limits and errors

An organization can run 100 sandboxes at a time by default; the next create answers `429` with `too-many-sandboxes`.

| Status | Code | When |
| --- | --- | --- |
| `404` | `template-not-found` | No such app or build in your organization |
| `409` | `template-not-runnable` | The build is a static site, or the app runs no machine |
| `404` | `sandbox-not-found` | No such sandbox in your organization |
| `409` | `sandbox-ended`, `sandbox-starting` | The sandbox has ended, or is not running yet |
| `429` | `too-many-sandboxes` | The organization's limit is reached |
| `503` | `no-capacity` | No room right now, try again |

See the [CLI reference](https://docs.rytiv.com/reference/cli/sandbox.md) for every flag of `ry sandbox`.

---

<!-- Guides: https://docs.rytiv.com/guides/agents-and-tokens/ -->

# Agents and tokens

> Give a coding agent a key of its own, narrow it with scopes or an agent class, connect a hosted client through OAuth, and read the audit of what the agent did.

A coding agent works on Rytiv with an API key like any other client. What sets its key apart is that you hand it over without watching every request, so the platform, not the agent, has to know what the key is meant for. Rytiv gives you three tools for that: scopes, agent tokens with a class, and an audit of every judged request.

## One key per agent

Create a key for each agent and name it after the agent. A key is shown once; store it where the agent reads it (`RYTIV_TOKEN`, a `.mcp.json` with `${RYTIV_TOKEN}`, your CI's secret store).

**CLI**

```bash
ry tokens create claude-code --agent sandbox --app web --app web-try
```

**curl**

```bash
curl -X POST "https://api.rytiv.app/v1/tokens" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-code", "agent": {"class": "sandbox", "apps": ["web", "web-try"]}}'
```

**TypeScript**

```ts
const res = await fetch("https://api.rytiv.app/v1/tokens", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RYTIV_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "claude-code", agent: { class: "sandbox", apps: ["web", "web-try"] } }),
});
const { token } = await res.json(); // shown in this answer only
```

**Python**

```python
import os, requests

res = requests.post(
    "https://api.rytiv.app/v1/tokens",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
    json={"name": "claude-code", "agent": {"class": "sandbox", "apps": ["web", "web-try"]}},
)
token = res.json()["token"]  # shown in this answer only
```

Creating a key needs a key with full access; your first one comes from the console or from `ry login`.

## Agent tokens: a class and a list of apps

An `agent` block makes the key an agent token. The platform enforces two facts about it on every request:

| Class | What the agent may do |
| --- | --- |
| `sandbox` | Everything an API key may do, inside the apps on its list. For trying things out. |
| `twin` | The same, for a per-task copy of production: a preview app, a database branch, a computer. |
| `production` | Read only. Status, releases and logs are open; what production holds (files, a shell, query results) needs `prodDataRead: true` on the token. Any change is refused with `agent-token-production-readonly`. |

`apps` names the apps the token may touch; a request about another app, or about something that is not an app (a bucket, a volume), is refused with `agent-token-app-scope`. Without the list, the token reaches the whole organization.

Whatever the class, an agent token can never mint, reveal or revoke a credential, administer the organization, or act for another organization (`agent-token-credential`, `agent-token-delegation`). An agent that is told "this is production, only read" by its prompt is one injected sentence away from forgetting it; the token does not forget.

With `ry tokens create`: `--agent <class>`, `--app <name>` (repeatable) and `--read-prod-data`.

## Scopes: less than full access

Scopes narrow a key the way a CI job or a partner needs it. A key without scopes is the whole organization; a key with scopes can only do less.

| Scope | Allows |
| --- | --- |
| `read` | Every read of the product API that is a status: apps, machines, deploys, databases, buckets, domains, schedules, webhooks. Not credentials, not billing, not the files of a machine. |
| `deploy` | The deploy routes of every app: build, deploy, releases, rollback, logs, machines, secrets. Never creating or deleting an app, never a key. |
| `deploy:<app>` | The same for exactly that app. The app list shows only the apps the key may deploy. |
| `mail:send` | Sending mail from any proven domain of the organization. |
| `mail:send:<domain>` | Sending from exactly that domain. |

```bash
ry tokens create ci-web --deploy web --expires-in 30d
ry tokens create status-page --scope read
```

A scoped key cannot open a shell, a tunnel or the console of a machine; those need full access. A route the scope does not cover answers `403` with `token-scope` and names the scope needed. Scopes and an agent class combine; the narrower rule wins.

## Expiry

A key may stop working at a moment (`expiresAt`) or after a duration (`ttlSeconds`, in the CLI `--expires-in 12h` or `--expires-at 2027-01-31T00:00:00Z`): at least 60 seconds and at most 365 days ahead. A key with an expiry cannot create a key that outlives it; without an explicit expiry, the new key inherits the creator's.

```bash
ry tokens list
ry tokens revoke tok-1a2b3c4d
```

Revoking a key rejects requests already using it right away.

## Connect a hosted client with OAuth

A client that has no place for a pasted key (a hosted connector) connects to the MCP server through OAuth 2.1:

1. `POST https://api.rytiv.app/v1/mcp` without a key answers `401` with a `WWW-Authenticate` header that names the discovery document `/.well-known/oauth-protected-resource/v1/mcp`.
2. The client reads `/.well-known/oauth-authorization-server`, registers itself at `POST /v1/oauth/register` (no client secret; every client is a public client bound to PKCE), and sends you to `GET /v1/oauth/authorize`.
3. You land on `https://console.rytiv.com/connect`, signed in, and approve the client for the active team.
4. The client exchanges its code at `POST /v1/oauth/token` and receives an access token (valid 1 hour) and a refresh token (30 days, renewed on use).

The access token is an ordinary key of the organization, named after the client, and appears under **Team, Tokens & keys** in the console, where you revoke it. Scopes of the OAuth server: `mcp` and `offline_access`.

In Claude Code, Codex and Cursor you do not need OAuth: add the server with your key as a bearer header, see the [quickstart](https://docs.rytiv.com/quickstart.md).

## Read what the agent did

Every request judged for an agent token is recorded: the route, the verdict, the token.

```bash
curl "https://api.rytiv.app/v1/agent-actions?limit=100" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

`?token=<id>` narrows the list to one key. Reading the audit needs a key with full access.

## Confirmations

A change in production by an agent waits for a person. The console carries the page for it (`/confirm/<id>`), and the platform refuses the change until the confirmation exists; in this release the refusal stands, and the person makes the change with their own key or in the console. See [Confirmations](https://docs.rytiv.com/concepts/confirmations.md).

---

<!-- Guides: https://docs.rytiv.com/billing/ -->

# Credit and pricing

> Rytiv is paid from prepaid credit in euros. Every account admitted from the waitlist starts with 100 EUR; usage is drawn from the credit as it runs. Prices, top-ups, auto-recharge, and what happens at zero.

Rytiv is pay as you go from **prepaid credit in euros**. Every account admitted from the waitlist starts with **100 EUR of credit**. There are no plans and no seats: a machine pays for memory while it is awake and for CPU only while it is computing, storage is priced per gigabyte and month. Nothing is invoiced later.

## Prices

Introductory prices until 31 January 2027. Any change is announced at least 30 days in advance. All prices in EUR, excluding VAT. The pricing page on rytiv.com is the reference; this page repeats it.

| What | Price | How it is counted |
| --- | --- | --- |
| Memory | 0.0076 EUR per GB-hour | Only while the machine is awake. A sleeping machine keeps its memory as a snapshot, billed at the snapshot rate. |
| CPU | 0.035 EUR per vCPU-hour | Active CPU time only. Idle time is not charged. |
| Disk (volumes) | 0.10 EUR per GB-month | The volumes your machines, computers and databases keep their data on |
| Object storage | 0.022 EUR per GB-month | S3-compatible buckets |
| Snapshots and templates | 0.08 EUR per GB-month | Saved machine snapshots, and the templates new machines and sandboxes start from |

A Postgres database, a computer and a sandbox each run as a machine and are billed like one, by memory, CPU and disk. There is no separate price for any of them.

**Included at no charge:** builds on Rytiv's builders, TLS certificates and custom domains, outbound data transfer, and team members. Fair use applies.

## Limits on the starting credit

An account on the starting credit can have **2 computers** and **10 apps** at a time, computers included. The limit is checked when something is created, never when it wakes or starts: what you have keeps running. The next create answers `403` with `org-limit-computers` or `org-limit-apps`, the body carries `limit` and `current`, and the sentence says what to delete or that you can contact us for more. Every other bound is on [Limits and quotas](https://docs.rytiv.com/concepts/limits.md).

The starting credit is granted once per person. An organization without it begins with a balance of zero and is blocked until its first top-up.

## When the credit is used up

The balance reaching zero **stops** your machines; nothing is deleted, disks and volumes stay. Reads keep working, so logs, lists and the console still answer, and nothing new starts: a request that would start or create something answers `402` with the code `credit-blocked`. A top-up or an automatic recharge lifts the block, and the machines the block stopped are started again.

Before that, the account carries `warned` once the balance falls to 20 percent of the reference top-up (the auto-recharge amount if you set one, otherwise your last top-up), and the console shows it.

## Top up

Credit is topped up in the Rytiv console by an admin of the team, under **Credits & usage**: a one-time top-up by card payment (10 EUR to 1,000 EUR), or auto-recharge with a threshold, an amount (10 to 500 EUR) and a monthly ceiling (at least the amount, at most 2,000 EUR). Card details are entered on the payment provider's page and never reach Rytiv. A failed automatic charge is retried after 15 minutes.

Top-ups cannot be made over the API or with the CLI: the routes behind the console page (`POST /v1/billing/topups`, `PUT /v1/billing/auto-recharge`, `POST /v1/billing/portal`) take only the console's signed proof of an admin, and a plain API key answers `403` with `billing-console-only`.

## Read your balance

**curl**

```bash
curl "https://api.rytiv.app/v1/billing/credits" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

**TypeScript**

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

**Python**

```python
import os, requests

account = requests.get(
    "https://api.rytiv.app/v1/billing/credits",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
).json()
print(account["balanceCents"], account["blocked"])
```

**CLI**

```bash
ry billing preview
ry usage --from 2026-10-01T00:00:00Z --to 2026-11-01T00:00:00Z
```

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/v1/billing/credits` | `balanceCents` (and the exact `balanceMicros` as a string), `blocked`, `blockedAt`, `warned`, the auto-recharge settings and `prepaid` (whether the organization is on prepaid credit at all) |
| `GET` | `/v1/billing/ledger` | The ledger, newest first: top-ups, usage bookings, grants, refunds and adjustments. `?limit=` up to 500. |
| `GET` | `/v1/billing/preview` | What a period cost, line by line, from the metered usage; `ry billing preview` prints it |

All three only read. A key narrowed by [scopes](https://docs.rytiv.com/authentication.md#narrow-a-key-scopes) cannot reach them (money stays with full keys); an [agent key](https://docs.rytiv.com/authentication.md#agent-keys) can read them. Every field is in the [API reference](https://docs.rytiv.com/reference/api/billing.md).

## Region

At launch Rytiv has one region, in the EU. Your apps, databases and files stay there; see [Regions](https://docs.rytiv.com/concepts/regions.md).

---

<!-- Guides: https://docs.rytiv.com/guides/custom-domains/ -->

# Custom domains and TLS

> Put your own domain on an app. Add it, set the DNS records the answer names, and Rytiv proves it, issues the certificate and renews it.

Every app answers on `https://<app>.rytiv.app` with a certificate from the start. A custom domain is added to an app, proven by a DNS record, pointed at Rytiv, and gets its own certificate. Wildcards are not accepted for a single domain; a whole zone can be proven once instead.

## 1. Add the domain

**CLI**

```bash
ry domains add web www.example.com
```

**curl**

```bash
curl -X POST "https://api.rytiv.app/v1/apps/web/domains" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "www.example.com"}'
```

**TypeScript**

```ts
const res = await fetch("https://api.rytiv.app/v1/apps/web/domains", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RYTIV_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ domain: "www.example.com" }),
});
const { status, dns } = await res.json(); // dns.txt and dns.point: the records to set
```

**Python**

```python
import os, requests

domain = requests.post(
    "https://api.rytiv.app/v1/apps/web/domains",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
    json={"domain": "www.example.com"},
).json()
print(domain["status"], domain["dns"])
```

The answer is the domain in state `pending_dns` with the records to set.

## 2. Set the DNS records

Two things have to be true: you own the domain, and it points at Rytiv.

| Record | Name | Value | Proves |
| --- | --- | --- | --- |
| `TXT` | `_rytiv.www.example.com` | `rytiv-verify-<token>` from the answer | ownership |
| `CNAME` | `www.example.com` | `<slug>.rytivdns.com` (or `web.rytiv.app`) | ownership and traffic |
| `A` | `example.com` | the ingress addresses from the answer | ownership and traffic, for an apex |

A subdomain needs the CNAME (the TXT record is offered as well); an apex such as `example.com` cannot carry a CNAME and gets A records instead. The exact names and values are in the answer of `ry domains add` and of `GET /v1/apps/:name/domains`; copy them from there.

## 3. Wait, or check now

Rytiv checks the records every 30 seconds at first, then with a growing gap up to an hour. `ry domains check web www.example.com` asks for a check right away.

| Status | Meaning |
| --- | --- |
| `pending_dns` | Waiting for the records. |
| `verified` | Ownership is proven; the certificate is being ordered. |
| `cert_issued` | The certificate exists. |
| `active` | The certificate exists and a machine of the app is ready to answer. |
| `error` | The certificate could not be issued; `error` says why. A missing DNS record never leads here, it keeps the domain `pending_dns`. |

```bash
ry domains list web
```

The list shows the status, the days left on the certificate and the records still missing.

## Certificates

Rytiv orders the certificate over ACME with an HTTP challenge that the edge answers, as soon as ownership is proven. It is renewed when fewer than 30 days remain. The default address `https://<app>.rytiv.app` is covered by the platform's own certificate. Port 80 answers a redirect to HTTPS.

## Redirect one domain to another

```bash
ry domains redirect web example.com www.example.com
ry domains redirect web example.com --off
```

The first domain then answers `308` to the second, keeping path and query. The target must be another domain of the same app or its default address; a target cannot itself redirect, and a domain others point at cannot start redirecting, so there are no chains and no loops.

## Prove a whole zone once

```bash
ry domains zones add example.com
```

The answer names two CNAME records: `_acme-challenge.example.com` to a challenge name Rytiv gives you, and `*.example.com` to Rytiv's ingress. Once they resolve, every name directly below the zone (`app.example.com`, `api.example.com`) is yours without a record of its own and is covered by one wildcard certificate; `ry domains add web app.example.com` then needs no DNS change. Only one level below the zone is covered.

## Remove

```bash
ry domains remove web www.example.com
```

The CLI asks you to type the name; pass `--yes` in scripts. The certificate is not revoked, the domain simply stops routing.

## Errors you will meet

| Status | Code | When |
| --- | --- | --- |
| `400` | `bad-request` | The name is not a domain: a wildcard, an IP, a single label, a platform domain. The sentence says which. |
| `409` | `shadows-default-address` | The domain is the default address of an app. |
| `409` | `mail-domain` | The name is a sending domain of a zone and cannot become an app domain. |
| `409` | `conflict` | The domain is already claimed by someone. |

---

<!-- Guides: https://docs.rytiv.com/guides/buckets/ -->

# Buckets

> S3-compatible object storage. Create a bucket, upload and download with presigned URLs, attach it to an app for direct access, set CORS for browser uploads.

A bucket holds objects and speaks the S3 protocol. Your app reaches it in two ways: ask the Rytiv API for a presigned URL per object, or attach the bucket to the app, which gives it a key scoped to that bucket and the `S3_*` environment variables to use any S3 client directly.

## 1. Create a bucket

**CLI**

```bash
ry bucket check my-uploads
ry bucket create my-uploads
```

**curl**

```bash
curl -X POST "https://api.rytiv.app/v1/buckets" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-uploads"}'
```

**TypeScript**

```ts
await fetch("https://api.rytiv.app/v1/buckets", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RYTIV_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "my-uploads" }),
});
```

**Python**

```python
import os, requests

requests.post(
    "https://api.rytiv.app/v1/buckets",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
    json={"name": "my-uploads"},
)
```

Bucket names are 3 to 63 characters of lowercase letters, digits and hyphens, unique across Rytiv; names starting with `rytiv` are reserved. `GET /v1/bucket-names/:name` (`ry bucket check`) tells you whether a name is free and, if not, why.

## 2. Upload and download with presigned URLs

A presigned URL is valid for one object and one method, for a limited time (default 15 minutes, at most 7 days). Nobody who holds it needs a key.

**CLI**

```bash
ry bucket presign my-uploads reports/2026-10.pdf --put --content-type application/pdf
ry bucket presign my-uploads reports/2026-10.pdf
```

**curl**

```bash
curl -X POST "https://api.rytiv.app/v1/buckets/my-uploads/presign" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"op": "put", "key": "reports/2026-10.pdf", "contentType": "application/pdf", "expiresInS": 900}'
```

**TypeScript**

```ts
const res = await fetch("https://api.rytiv.app/v1/buckets/my-uploads/presign", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RYTIV_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ op: "put", key: "reports/2026-10.pdf", contentType: "application/pdf" }),
});
const { url, method, requiredHeaders } = await res.json();
await fetch(url, { method, headers: requiredHeaders, body: fileBytes });
```

**Python**

```python
import os, requests

signed = requests.post(
    "https://api.rytiv.app/v1/buckets/my-uploads/presign",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
    json={"op": "put", "key": "reports/2026-10.pdf", "contentType": "application/pdf"},
).json()
with open("2026-10.pdf", "rb") as f:
    requests.put(signed["url"], headers=signed["requiredHeaders"], data=f)
```

The answer carries `url`, `method`, `expiresAt` and `requiredHeaders`: headers the call must send exactly as given, because they are part of the signature. For a `put` with `contentType`, that is the `Content-Type` the upload must use.

Keys are at most 1024 bytes, with no leading or trailing `/`, no empty, `.` or `..` segments.

## 3. Attach the bucket to an app

```bash
ry bucket attach my-uploads --to web
ry bucket attach my-uploads --to web --as uploads
```

Attaching gives the app a key that opens exactly this bucket (read and write, no owner rights) and injects it as managed secrets. From its next start the app sees:

| Variable | Meaning |
| --- | --- |
| `S3_BUCKET` | The bucket's name |
| `S3_ENDPOINT` | The S3 endpoint to talk to, `https://s3.<region>.<domain>` |
| `S3_REGION` | The region name to sign with |
| `S3_ACCESS_MODE` | `key`: the app holds a key and speaks S3 directly |
| `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | The key scoped to this bucket |

With `--as uploads` every variable gets the prefix `UPLOADS_` (`UPLOADS_S3_BUCKET`, ...); from the second bucket on an app the prefix is required. The key is shown once, in the attach answer; attaching again rotates it. `ry bucket detach my-uploads --from web` removes the variables and revokes the key; the objects stay.

The endpoint supports virtual-host addressing (`<bucket>.s3.<region>.<domain>`). With the AWS SDK for JavaScript 3.729 or newer, set `requestChecksumCalculation: "WHEN_REQUIRED"`, or presigned uploads fail with `InvalidDigest`.

## 4. Allow uploads from the browser

A browser that uploads straight to a presigned URL sends a preflight first; without a CORS rule the storage refuses it, and nothing of it reaches your server.

```bash
ry bucket cors-set my-uploads --allow-origin https://www.example.com
ry bucket cors my-uploads
```

`ry bucket cors-set` writes one rule with the given origins, methods `GET,PUT,HEAD`, headers `*,authorization`, and `ETag` exposed, so an upload client can read the answer of its own `PUT`. `PUT /v1/buckets/:name/cors` takes the whole list of rules and replaces what was there; an empty list removes them. CORS is not authentication: the presigned URL's signature is what protects the object.

## 5. List and delete objects

```bash
ry bucket ls my-uploads --prefix reports/
ry bucket rm my-uploads reports/2026-10.pdf
```

`GET /v1/buckets/:name/objects?prefix=&limit=&cursor=` lists up to 1000 objects per page (default 100) with a `nextCursor` for the next page. `DELETE /v1/buckets/:name/objects?key=<url-encoded key>` deletes one object; the key goes in the query string.

## 6. Delete the bucket

```bash
ry bucket destroy my-uploads
ry bucket destroy my-uploads --force
```

A bucket that still holds objects is refused with `409`; `--force` (`?force=1` on `DELETE /v1/buckets/:name`) deletes the objects first, then the attachments' variables, then the bucket. The CLI asks you to type the name; pass `--yes` in scripts.

---

<!-- Guides: https://docs.rytiv.com/guides/cron-and-jobs/ -->

# Cron and jobs

> Run something of an app on a schedule, by calling a path or by running a command on a machine of its own, and run one-off commands as jobs with their exit code and output kept.

A schedule runs on a cron expression. It either wakes the app and calls a path of it, signed so the app can verify the call, or it runs a command on a machine of its own, built from the app's image and environment. A job is that same machine without a schedule: one command, run once.

## A path on a schedule

For frequent, light work the app does itself, down to every minute.

**CLI**

```bash
ry cron add web "*/15 * * * *" --path /api/tick
```

**curl**

```bash
curl -X POST "https://api.rytiv.app/v1/apps/web/schedules" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"schedule": "*/15 * * * *", "path": "/api/tick", "method": "POST"}'
```

**TypeScript**

```ts
await fetch("https://api.rytiv.app/v1/apps/web/schedules", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RYTIV_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ schedule: "*/15 * * * *", path: "/api/tick", method: "POST" }),
});
```

**Python**

```python
import os, requests

requests.post(
    "https://api.rytiv.app/v1/apps/web/schedules",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
    json={"schedule": "*/15 * * * *", "path": "/api/tick", "method": "POST"},
)
```

The expression has five fields (minute, hour, day of month, month, day of week) or is `@hourly`, `@daily` and the like, read in the `timezone` you name (default `UTC`, for example `Europe/Berlin`). `method` is `GET` (default) or `POST`. Each attempt has `timeoutSec` (default 60, at most 240).

### Verify the call

A path is called through the app's address with these headers:

| Header | Value |
| --- | --- |
| `Rytiv-Cron-Signature` | `v1=<hex>`: HMAC-SHA256 of `<timestamp>.<path>` under the app's secret `RYTIV_CRON_SECRET` |
| `Rytiv-Cron-Timestamp` | Unix seconds when the call was signed |
| `Rytiv-Cron-Run` | The run's id, the same across retries |
| `Rytiv-Cron-Schedule` | The schedule's id |
| `Rytiv-Cron-Scheduled-For` | The slot the run is for |

`<path>` is the path with its query, exactly as sent. The secret `RYTIV_CRON_SECRET` is created as a managed secret with the app's first path schedule; **the app sees it from its next deploy**, and a run before that fails rather than being sent unsigned.

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function cronCallIsGenuine(req: Request, path: string): boolean {
  const ts = req.headers.get("rytiv-cron-timestamp") ?? "";
  const sig = req.headers.get("rytiv-cron-signature") ?? "";
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = `v1=${createHmac("sha256", process.env.RYTIV_CRON_SECRET!).update(`${ts}.${path}`).digest("hex")}`;
  return expected.length === sig.length && timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}
```

A call is retried up to three times (after 5 s, then 10 s) on a network error or a `5xx`; a `4xx` or a redirect is not retried. A slot that comes while the previous run of the same schedule still runs is skipped, not queued; a slot more than 10 minutes late counts as missed.

## A command on a schedule

For heavy, rare work: at most hourly, and every run gets a machine of its own, sized as you say.

```bash
ry cron add web "0 3 * * *" --timezone Europe/Berlin --command "npm run cleanup" --memory 8192
ry cron add web "@daily" -- node scripts/report.js --full
```

`--command` runs through `/bin/sh -c`; the form after `--` is the argument list without a shell. The machine runs the app's image with its secrets and environment, and the app's size unless `--memory` or `--vcpus` say otherwise. A run has `timeoutSec` (default 900, at most 3600). The minute field of the expression must name one minute.

## Manage schedules

```bash
ry cron list web
ry cron runs web sch-1a2b3c4d
ry cron run web sch-1a2b3c4d
ry cron pause web sch-1a2b3c4d
ry cron resume web sch-1a2b3c4d
ry cron rm web sch-1a2b3c4d
```

An app has at most 20 schedules; the last 100 runs of each are kept. `ry cron run` starts a run now, outside the expression (also on a paused schedule); resuming continues from the next slot, nothing missed is caught up. A run is `running`, `succeeded`, `failed`, `skipped` or `missed`. Removing a schedule takes its history with it.

## Jobs: one command, once

**CLI**

```bash
ry job run web -- npm run migrate
ry job run web --memory 4096 --timeout 1800 -- node scripts/report.js
```

**curl**

```bash
curl -X POST "https://api.rytiv.app/v1/apps/web/jobs" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": ["npm", "run", "migrate"], "timeoutSec": 900}'
```

**TypeScript**

```ts
const res = await fetch("https://api.rytiv.app/v1/apps/web/jobs", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RYTIV_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ command: ["npm", "run", "migrate"] }),
});
const job = await res.json(); // { id, state: "queued", ... }
```

**Python**

```python
import os, requests

job = requests.post(
    "https://api.rytiv.app/v1/apps/web/jobs",
    headers={"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"},
    json={"command": ["npm", "run", "migrate"]},
).json()
```

A job runs the command on a machine of its own with the app's image, secrets and environment, and answers `202` with the job. `ry job run` streams the output and exits with the command's own exit code (1 for `failed` or `timeout`); Ctrl-C leaves the job running. Poll `GET /v1/jobs/:id` until `state` is `done`, `failed` or `timeout`:

| State | Meaning |
| --- | --- |
| `queued` | The machine is being placed. |
| `running` | The command runs; `startedAt` is set. |
| `done` | The command ran to its end; `exitCode` holds its verdict (a failing command is `done` with a non-zero code). |
| `failed` | It did not run to the end: placement failed, the machine died, or the job was cancelled. `exitCode` is `null`, the reason is the last line of `output`. |
| `timeout` | `timeoutSec` ended it. |

"Green" means `state === "done" && exitCode === 0`. `output` keeps the first 1 MiB. In the API, `env` adds environment for this job, `links` names apps the job's machine may reach, `build` runs a specific build of the app; the CLI offers `-e`, `-t`, `-m` and `-c`.

```bash
ry job list web
ry job get job-1a2b3c4d
ry job cancel job-1a2b3c4d
```

Cancelling (`DELETE /v1/jobs/:id`) ends a running job; its machine is gone after `finishedAt`, the job record stays.

---

<!-- Concepts: https://docs.rytiv.com/concepts/how-it-works/ -->

# How Rytiv works

> The building blocks your agent works with, how a request becomes a running machine, what sleeps and what stays, and the project model that comes next.

Everything on Rytiv belongs to an **organization** (a team in the console). An API key acts as one organization, and every name it uses is looked up inside that organization only.

## The building blocks

**Apps** are the unit everything else hangs off. An app has a name that is unique across Rytiv and answers on `https://<app>.rytiv.app`. It runs one or more **machines** from an image you deploy, or it is a static site served at the edge without a machine. Secrets, deploys, releases, logs, domains, schedules and jobs belong to an app. See [Apps](https://docs.rytiv.com/apps.md).

**Computers** are apps of a special kind: one machine from the computer image, a home disk at `/data` that outlives the machine, and a desktop you can watch or take over. They are the place an agent works in. See [Computers](https://docs.rytiv.com/computers.md).

**Sandboxes** are machines with a deadline. They start from a template (the image an app of yours runs, or a build), run commands, hold files, and are removed at their deadline. See [Sandboxes](https://docs.rytiv.com/sandboxes.md).

**Postgres** databases run on machines of their own with their data on a volume. Every database can be branched (a copy-on-write copy, ready in seconds) and forked (a full copy from its archive, from any moment in the last 7 days). See [Postgres](https://docs.rytiv.com/postgres.md).

**Volumes** are disks that outlive machines; **buckets** are S3-compatible object storage; **custom domains** put your names on an app. See the [guides](https://docs.rytiv.com/guides/buckets.md).

## Machines

A machine is one virtual machine with its own kernel. It is `requested`, `scheduled`, `starting`, `running`, `suspending`, `suspended`, `stopping`, `stopped`, `deleted` or `failed`. A deploy creates machines for an app one at a time: the new machine must boot and answer on its port (and pass the health check, if set) before an old one is taken out of traffic; if it fails, the old version keeps serving.

A machine that **declares a port** gets no traffic until that port answers. This is a promise, not only behaviour: a migration that runs before the app starts listening never sees traffic against a schema it does not expect.

## What sleeps and what stays

An app sleeps only if you give it a sleep rule (`--sleep 5m`); a new app never sleeps on its own. A machine up to 2048 MB sleeps with its memory and resumes in well under a second on the next request; a larger machine stops instead and boots cold, its disk kept. A computer shuts down after 10 minutes without activity; its home disk stays. A database is suspended after 5 minutes without a query and woken by the next connection, where the region's hosts act on the policy.

What stays through a stop, a replacement or a host failure: a volume, a computer's home, a database's data and archive, a bucket's objects, an agent machine's checkpoints. What does not: a machine's root disk (it is the image's), open programs, and anything on a sandbox at its deadline.

## Three ways in

| Way | For | Where |
| --- | --- | --- |
| MCP server | Your coding agent | `https://api.rytiv.app/v1/mcp`, see the [quickstart](https://docs.rytiv.com/quickstart.md) |
| CLI `ry` | You, in a terminal or in CI | [CLI reference](https://docs.rytiv.com/reference/cli.md) |
| REST API | Your own code | [API reference](https://docs.rytiv.com/reference/api.md) |

All three use the same API and the same keys, and they see the same apps, databases and machines. The console is where you sign in, create keys, watch a computer and top up credit.

## Where it runs

Your apps, databases and files stay in the region of your workspace, in the EU at launch, and a machine never leaves its region. See [Regions](https://docs.rytiv.com/concepts/regions.md) and [Security and data](https://docs.rytiv.com/concepts/security.md). Every bound the platform enforces is on [Limits and quotas](https://docs.rytiv.com/concepts/limits.md); every error code on the [error catalog](https://docs.rytiv.com/concepts/errors.md).

## The project model

Rytiv is becoming the place where your agent builds a whole project: you connect it once and say "build project XY on Rytiv". Each project has three parts with three levels of risk:

- a [sandbox](https://docs.rytiv.com/concepts/sandbox.md) where the agent works freely,
- a [twin](https://docs.rytiv.com/concepts/twins.md) for every task, a disposable copy of production,
- [production](https://docs.rytiv.com/concepts/production.md), which serves your users.

Reversible steps run without asking. Only an irreversible step waits for a [confirmation](https://docs.rytiv.com/concepts/confirmations.md) with your passkey. Projects as an object of the API are not available yet; the pieces (agent tokens with a class, database branches, preview apps, computers, automatic rollback after a deploy) are, and [Projects](https://docs.rytiv.com/concepts/projects.md) says how they fit together today.

---

<!-- Concepts: https://docs.rytiv.com/concepts/projects/ -->

# Projects

> A project holds everything one product needs on Rytiv: its sandbox, its twins and its production, so your agent can build it end to end.

> **Not available yet:** Projects are not an object of the API yet. This page describes how they will work, so you can plan for them. Today your agent works with [apps](https://docs.rytiv.com/apps.md), [computers](https://docs.rytiv.com/computers.md), [sandboxes](https://docs.rytiv.com/sandboxes.md) and [Postgres](https://docs.rytiv.com/postgres.md) directly, and an [agent token](https://docs.rytiv.com/guides/agents-and-tokens.md) with a class and a list of apps draws the line between them.

## One sentence to start

Connect your coding agent once, then ask it to "build project XY on Rytiv". The agent creates the project and works inside it. You do not set up environments, databases or preview addresses by hand.

## Three parts, three levels of risk

| Part | What it is for | What the agent may do |
| --- | --- | --- |
| [Sandbox](https://docs.rytiv.com/concepts/sandbox.md) | Trying things | Everything |
| [Twin](https://docs.rytiv.com/concepts/twins.md) | One task, against a copy of production | Everything, on the copy |
| [Production](https://docs.rytiv.com/concepts/production.md) | Serving your users | Reversible steps; irreversible ones wait for you |

## The rule

**Reversible steps run without asking.** A deploy that can be rolled back, a branch that can be dropped, a secret that can be changed again: none of these stop your agent.

**Only irreversible steps need a tap.** Deleting a production database or dropping a table waits until you confirm it with your passkey. See [Confirmations](https://docs.rytiv.com/concepts/confirmations.md).

The platform enforces this, not the agent: the key your agent holds cannot confirm its own request.

---

<!-- Concepts: https://docs.rytiv.com/concepts/sandbox/ -->

# Project sandbox

> The part of a project where your agent may do anything: build, break and try again.

> **Not available yet:** The project sandbox comes with [projects](https://docs.rytiv.com/concepts/projects.md). It is not the same as the [Sandboxes](https://docs.rytiv.com/sandboxes.md) you can create today: those are short-lived machines for one task, and a project sandbox will use them. An agent token of class `sandbox` is how you give an agent this freedom today.

## What it is for

The sandbox is the part of a project where nothing real is at stake. Your agent has full rights there: it can create and delete machines and databases, deploy, and start over, without asking you.

## What you can use today

The pieces exist already:

- [Sandboxes](https://docs.rytiv.com/sandboxes.md) for short-lived machines with a deadline.
- [Computers](https://docs.rytiv.com/computers.md) for a machine whose files stay between sessions.
- [Postgres branches](https://docs.rytiv.com/postgres.md#branch-a-database) for databases you can throw away.

---

<!-- Concepts: https://docs.rytiv.com/concepts/twins/ -->

# Twins

> A twin is a disposable copy of production for one task, with its own database branch, its own preview address, its own machine.

> **Not available yet as one call:** Twins come with [projects](https://docs.rytiv.com/concepts/projects.md). Your agent will create one per task with a single tool call. Every piece of a twin exists today and can be assembled by hand, see below; an agent token of class `twin` is the key for it.

## What a twin is

For every task, your agent gets a twin of production:

- a **branch of the production database**, with an expiry, so the data is real but the original is never touched,
- a **preview app** that only people with a signed link can open,
- a **sandbox or computer** whose `DATABASE_URL` points at the branch.

The agent can do anything inside a twin. When the task is done, the result goes to production with a promote step, and the twin goes away.

## Building one by hand today

Every piece of a twin exists already, so you or your agent can assemble one today:

1. Branch the database with an expiry: [`create_branch`](https://docs.rytiv.com/reference/mcp-tools.md#create_branch), or `ry postgres branch` with `--expires-in`.
2. Deploy the change to an app of its own, and protect it with `ry protect signed <app>`.
3. Attach the branch to that app with `ry attach <branch> --to <app>`. The app gets the branch's connection URL as its `DATABASE_URL`.

Rytiv's MCP tools never return a database password, and the connection URL of a branch is handed out only once, to whoever asks for it first. See [Postgres](https://docs.rytiv.com/postgres.md#connection-url-of-a-copy).

---

<!-- Concepts: https://docs.rytiv.com/concepts/production/ -->

# Production

> The part of a project that serves your users. Your agent reads it freely and changes it only in ways that can be undone.

> **Partly available:** Production as a part of a [project](https://docs.rytiv.com/concepts/projects.md) is not an object of the API yet. What exists today: an [agent token](https://docs.rytiv.com/guides/agents-and-tokens.md) of class `production` may only read, and a deploy that makes the app worse is rolled back on its own. The platform does not yet know which app is production; the token's class and app list say it.

## What your agent may do

- **Read** without asking: logs, releases, and read-only SQL.
- **Change** what can be undone: a deploy that can be rolled back, a promote from a twin.
- **Ask you** before anything irreversible, see [Confirmations](https://docs.rytiv.com/concepts/confirmations.md).

Whether an agent may read production data at all will be a setting, because production holds your customers' data.

## Safety nets

- **Watching after a deploy.** For five minutes after the switch, Rytiv compares the app's error rate (the share of `5xx` answers, with at least 20 requests to judge) with the rate before. If it is clearly worse, the deploy is rolled back on its own; the verdict is in the deploy's `watch` field.
- **The database is never rolled back automatically.** A point-in-time restore is offered instead, and the state before a restore is kept as a branch.
- **A restore point before every production migration** comes with projects.

## What exists today

- [Rollbacks](https://docs.rytiv.com/apps.md#releases-and-rollback) of an app to an earlier release, without a rebuild, by hand and automatically after a bad deploy.
- [Point-in-time restore](https://docs.rytiv.com/postgres.md#restore-in-place) of a database in place, with the old state kept as a branch.
- [Read-only SQL](https://docs.rytiv.com/reference/mcp-tools.md#execute_sql) for your agent: without a branch, `execute_sql` runs in a read-only transaction.
- An [agent token](https://docs.rytiv.com/guides/agents-and-tokens.md) of class `production`, which may read and nothing else.

---

<!-- Concepts: https://docs.rytiv.com/concepts/confirmations/ -->

# Confirmations

> Irreversible steps wait for one tap with your passkey. Everything else runs without asking.

> **Not available yet:** Confirmation requests are not an object of the API yet. This page describes how they will work. Today the platform draws the line with the agent token's class: class `production` may only read, and a change it asks for is refused with `agent-token-production-readonly` until a person makes it with their own key or in the console.

## Why only irreversible steps

An agent that asks before every action is an agent nobody uses. So Rytiv sorts every action into two kinds:

- **Reversible**: it can be undone. It runs right away.
- **Irreversible**: it cannot be undone. It waits for you.

## What counts as irreversible

The planned list:

- deleting a production database, volume or app,
- `DROP` or `TRUNCATE` in production,
- moving a domain,
- sending mail to many real recipients,
- going over your budget.

## How a confirmation works

1. Your agent asks for the step. Rytiv does not run it, it creates a confirmation request with a number, what will happen, and a preview link.
2. You open the request and confirm it with your passkey, or reject it.
3. Only then does the step run.

A confirmation can never be given with the agent's own key. The approval comes from you, not from the conversation.

---

<!-- Concepts: https://docs.rytiv.com/concepts/limits/ -->

# Limits and quotas

> Every bound the platform enforces, in one place. Organization limits, machine sizes, build machines, sandboxes, databases, tokens, schedules, jobs, domains, buckets and rate limits.

These are the bounds the API enforces. A request outside them answers `400` with `bad-request` and the field named, or `403` and `429` where the table says so. Where a number can be raised for you, the table says "contact us".

## Organization

| Limit | Value | When reached |
| --- | --- | --- |
| Computers | 2 | `403` with `org-limit-computers`; contact us for more |
| Apps, computers included | 10 | `403` with `org-limit-apps`; contact us for more |
| Sandboxes running at once | 100 | `429` with `too-many-sandboxes` |
| Webhooks | 20 | |
| Starting credit | 100 EUR, once per person | see [Credit and prices](https://docs.rytiv.com/billing.md) |

The computer and app limits apply to organizations created in the console on starting credit. Only creation is limited: a computer or app that exists keeps running whatever its state, and waking it never counts. Database backing apps, sandboxes and previews do not count as apps.

## Machines

| Setting | Range | Default |
| --- | --- | --- |
| Memory (`memoryMb`) | 128 to 16384 | 512 for a new app, 1024 suggested for Next.js |
| vCPUs (`vcpus`) | 1 to 16 | 1 |
| Disk (`diskMb`) | 512 to 131072 | the image's size plus headroom |
| Volume (`volumeGb`) | 1 to 500 | |
| Machines per app (`count`) | 1 to 20; exactly 1 with a volume | 1 |
| Internal port | 1 to 65535 | 3000 |
| Start command | up to 2000 characters | the image's or the detected one |
| Kill timeout (`killTimeoutS`) | 1 to 300 | 30 |
| Sleep after idle (`idleSeconds`) | 10 to 86400 | 300 (only if a sleep rule is chosen) |
| Stop after sleeping (`stopAfterSeconds`) | greater than `idleSeconds`, up to 7 days | |
| Sleeps with its memory | machines up to 2048 MB; larger ones stop instead | |
| Health check `maxWaitMs` | 1000 to 300000 | 60000, 120000 with a volume |
| Health probe `timeoutMs`, `intervalMs`, `healthyThreshold` | 100 to 30000, 100 to 10000, 1 to 10 | 2000, 500, 1 |
| Restart retries | 1 to 10 | 3 |
| App name | 2 to 63 characters, `a-z`, `0-9`, `-`, starting with a letter | |
| Reserved app names | `api`, `console`, `s3`, `admin`, `app`, `db`, `docs`, `internal`, `mail`, `pub`, `ssh`, `status`, `www`, and `rytiv` or `rytiv-*` | |

## Computers

| Size | vCPU | Memory | Home disk |
| --- | --- | --- | --- |
| `small` | 1 | 2304 MB | 50 GB |
| `base` (default) | 2 | 4096 MB | 100 GB |
| `large` | 4 | 8192 MB | 128 GB |

A computer shuts down after 10 minutes without activity; its home stays. Computer names are 2 to 31 characters.

## Builds

| Setting | Value |
| --- | --- |
| Build machine | 4096 MB, 4 vCPU |
| Build machine for Next.js and Dockerfile projects | 8192 MB, 4 vCPU |
| `--build-memory` | 1024 to 16384 MB |
| Build timeout | 8 minutes; 15 for Next.js, 20 for a Dockerfile |
| Build environment (the secrets a build sees) | 96 KiB encoded, else `413` |
| Git deploy archive | 200 MB compressed, 2 GiB unpacked |
| Static site | 1 GiB and 100,000 files |
| Builds kept per app | 3 |

## Sandboxes

| Setting | Range | Default |
| --- | --- | --- |
| Lifetime (`ttlSeconds`) | 10 to 86400 | 300 |
| Memory, vCPUs, disk | as a machine | 512 MB, 1 vCPU |
| Environment variables | up to 128, values up to 32768 characters | |
| Extra ports | up to 8 | |
| Metadata entries | up to 16 | |
| Exec timeout (`timeoutMs`) | 1000 to 600000 | 60000 |
| Exec output, stdin | 1 MiB each | |
| One file | 64 MiB | |
| Ended sandboxes listed for | 14 days | |

## Postgres

| Setting | Range | Default |
| --- | --- | --- |
| Memory | 128 to 16384 MB | 1024 |
| Volume (`sizeGb`) | 4 to 500 GB for Postgres | 10 |
| Branches per database | 15 | |
| Expiry of a branch or fork | 60 seconds to 30 days | none |
| Fork from a point in time | within the archive, 7 days | |
| Sleep after idle | 10 seconds to 1 day; second stage up to 7 days | 300 s, stop after 1 day |

## Tokens

| Setting | Range |
| --- | --- |
| Name | 1 to 120 characters |
| Scopes per key | up to 20 |
| Expiry | 60 seconds to 365 days; never later than the key that creates it |
| Apps on an agent token | 1 to 50 |
| SSH tokens | 60 seconds to 72 hours, default 1 hour |

## Snapshots

Labels are 1 to 63 characters of letters, digits, `.`, `-` and `_`, starting with a letter or digit; `auto-` is reserved. Automatic snapshots of agent machines are taken hourly; the newest per hour is kept for 24 hours, the newest per day for 30 days.

## Schedules and jobs

| Setting | Value |
| --- | --- |
| Schedules per app | 20 |
| Path call timeout | 60 s default, 240 s at most; down to every minute |
| Command timeout | 900 s default, 3600 s at most; at most hourly |
| Runs kept per schedule | 100 |
| Cron expression, time zone | up to 200 and 64 characters |
| Job command | up to 64 arguments; up to 8 linked apps |
| Job timeout | 1 to 3600 s, default 900 |
| Job output kept | 1 MiB |

## Domains and buckets

| Setting | Value |
| --- | --- |
| Domain length | up to 253 characters, labels up to 63 |
| Certificate renewal | when fewer than 30 days remain |
| Previews per app | 10; idle previews close after 14 days |
| Bucket name | 3 to 63 characters, `a-z`, `0-9`, `-`; `rytiv*` reserved |
| Presigned URL | 1 second to 7 days, default 15 minutes |
| Object key | up to 1024 bytes |
| CORS rules per bucket | 100 |
| Objects per list page | 100 default, 1000 at most |
| Sending domains waiting for DNS | 3 per organization |

## Rate limits

The product API has no general rate limit. These entrances have one and answer `429` with `Retry-After`:

| Entrance | Limit |
| --- | --- |
| MCP tool calls | 120 per minute per organization |
| Shell session starts | 120 per minute per organization; 64 open sessions per organization, 16 per machine |
| Computer viewer links | 120 per minute per organization |
| Device login codes | 20 per 10 minutes per address |
| OAuth register, authorize, token | 30, 60 and 300 per 10 minutes per address |
| Organizations created from the console | 10 per person per day |

## Credit

| Setting | Value |
| --- | --- |
| Smallest top-up | 10 EUR |
| Largest top-up | 1,000 EUR |
| Auto-recharge amount | 10 to 500 EUR; monthly cap up to 2,000 EUR |
| Warning | below 20 percent of the last top-up |

---

<!-- Concepts: https://docs.rytiv.com/concepts/errors/ -->

# Error catalog

> Every error code the API answers, with its HTTP status and what to do about it. Generated from the contract's code lists.

Every error of the API is a JSON object with a sentence and a stable code: `{ "error": "name already taken", "code": "name-taken" }`. Branch on `code`, show `error`. A code your program does not know should fall back on the HTTP status; the generic code of a status is listed first. See [REST API basics](https://docs.rytiv.com/reference/api-basics.md) for the request and response format.

## Generic codes

One per HTTP status. A route answers one of these when it has nothing more specific to say.

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work (unknown, revoked or expired). |
| 403 | `forbidden` | The key may not do this. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `conflict` | The request conflicts with the current state. |
| 410 | `gone` | The object existed and is gone. |
| 413 | `too-large` | The body is larger than the route accepts. |
| 422 | `unprocessable` | The request is well-formed but cannot be carried out as it is. |
| 426 | `upgrade-required` | The route needs a WebSocket upgrade; use the CLI. |
| 429 | `rate-limited` | Too many requests; wait for `Retry-After` and try again. |
| 500 | `internal` | Something failed on Rytiv's side. The sentence carries a reference you can quote. |
| 501 | `not-implemented` | Not available on this installation. |
| 502 | `upstream-failed` | A host, the object store or a connected service failed. |
| 503 | `unavailable` | Not possible right now; try again shortly. |
| 504 | `upstream-timeout` | A host or a connected service did not answer in time. |

## Codes shared by several routes

| Status | Code | Meaning |
| --- | --- | --- |
| 409 | `name-taken` | The name is used somewhere on Rytiv (an app, a database, a volume or a bucket). |
| 409 | `already-exists` | You already have it; an idempotent create may treat this as done. |
| 400 | `name-reserved` | The platform keeps this name (for example `api`, `console`, `docs`, `www`, and every name that is `rytiv` or starts with `rytiv-`). |
| 403 | `org-suspended` | The organization was suspended by the operator. |
| 403 | `delegation-refused` | `X-Rytiv-Org` names an organization this key may not act for. |
| 403 | `creator-proof` | Creating an organization needs the console's signed proof of the person. |
| 403 | `token-scope` | The key's scopes do not cover this route, this mail domain or this upgrade. The sentence names the scope needed. |
| 503 | `no-capacity` | No host in the region has room for the machine right now; try again. |
| 503 | `lease-held` | Another host still holds the volume or checkpoint; try again shortly. |
| 503 | `create-failed` | The host could not create the machine (image, start command or port). The sentence says which. |
| 503 | `database-unavailable` | The platform database cannot be reached right now; retry after `Retry-After`. |
| 408 | `wait-timeout` | The wait ran out before the machine reached the state; ask again. |
| 409 | `not-a-copy` | The database is neither a fork nor a branch; its URL came with its create answer. |
| 409 | `not-ready` | The copy is still restoring, or failed; there is nothing to hand out yet. |
| 409 | `url-handed-out` | The URL of this copy was handed out already. It leaves the platform exactly once. |
| 403 | `agent-token-production-readonly` | An agent token of class `production` may read; a change needs a person. |
| 403 | `agent-token-production-data` | An agent token of class `production` without `prodDataRead` may not read what production holds. |
| 403 | `agent-token-credential` | No agent token mints, reveals or revokes a credential, or administers the organization. |
| 403 | `agent-token-app-scope` | The request is about an app outside the token's list, or about no app at all. |
| 403 | `agent-token-route-unknown` | A route the agent rules do not know is refused. |
| 403 | `agent-token-delegation` | An agent token acts in its own organization only. |
| 503 | `agent-audit-unavailable` | The audit record of the action could not be written, so the action did not run; ask again shortly. |
| 403 | `org-limit-computers` | The organization has as many computers as it may have. The body carries `limit` and `current`. Delete one, or contact us for more. |
| 403 | `org-limit-apps` | The organization has as many apps as it may have (computers included). The body carries `limit` and `current`. |

## Machine actions

Answered by `POST /v1/machines/:id/:action` and a machine create when the host could not start the machine.

| Status | Code | Meaning |
| --- | --- | --- |
| 503 | `start-interrupted` | The start was interrupted on the host. |
| 503 | `guest-exited` | The machine's process ended during the start. |
| 503 | `port-timeout` | The machine did not answer on its port in time. |
| 503 | `no-capacity` | No host in the region has room for the machine right now; try again. |
| 503 | `host-refused` | The host refused the action. |
| 503 | `host-unreachable` | The host did not answer. |
| 409 | `machine-busy` | Another operation on the machine is in progress; try again. |
| 503 | `create-failed` | The host could not create the machine (image, start command or port). The sentence says which. |

## Rollbacks

Answered by `POST /v1/apps/:name/rollback`.

| Status | Code | Meaning |
| --- | --- | --- |
| 404 | `release-not-found` | No release with that version or id. |
| 409 | `rollback-target-current` | That release is the one that runs. |
| 409 | `rollback-same-build` | That release runs the same build as the current one. |
| 409 | `rollback-target-never-live` | That release never went live, so there is nothing to bring back. |
| 409 | `release-artifact-gone` | The release's image is no longer available. |
| 409 | `no-previous-release` | There is no earlier release that went live. |
| 409 | `rollback-not-for-resources` | The app backs a database; databases are restored, not rolled back. |
| 409 | `rollback-needs-machine-config` | The app has no machine whose settings a rollback could reuse. |
| 409 | `deploy-in-flight` | Another deploy of this app is running. |

## Credit and billing

Answered by the routes under `/v1/billing`.

| Status | Code | Meaning |
| --- | --- | --- |
| 402 | `credit-blocked` | The organization's credit is at zero: nothing new starts until a top-up. Reads, stops and the billing routes still answer. |
| 409 | `no-customer` | No payment relationship yet; a first top-up creates it. |
| 403 | `billing-console-only` | A billing change is made in the console by an admin, not with an API key. |
| 409 | `not-prepaid` | The organization has no credit account; only org creation or an operator's grant starts prepaid credit. |

## Computers

Answered by the viewer and control routes of a computer.

| Status | Code | Meaning |
| --- | --- | --- |
| 409 | `not-a-computer` | The machine is not a computer (it has no `COMPUTER_VIEW_KEY`), or it is a console or job machine. |
| 409 | `machine-stopped` | The machine is stopped; start it first. |
| 503 | `not-placed` | The machine has no host yet. |
| 503 | `view-key-unreadable` | The computer's key cannot be decrypted right now. |
| 409 | `view-key-too-short` | The computer's key is too short; the image would refuse to start with it. |
| 409 | `several-machines` | Control needs exactly one machine; the app has several. |
| 409 | `control-held` | Somebody else holds control; the body names `heldBy`, `until` and `leaseId`. Use `force` to take it. |
| 409 | `control-busy` | Another change of control is in progress; try again after `Retry-After`. |
| 409 | `computer-control-missing` | The machine runs a computer image from before control leases; deploy it again. |
| 409 | `guest-agent-absent` | The machine has no guest channel; it was created before shell sessions existed. Deploy it again. |
| 503 | `guest-channel-off` | The guest channel is switched off on the machine's host. |
| 503 | `guest-unreachable` | The guest did not answer; try again after `Retry-After`. |
| 502 | `guest-failed` | The control tool in the machine ran and failed. |
| 409 | `managed-service` | A managed database; its machine is not opened to a shell. |
| 503 | `resource-check-failed` | Could not tell whether the machine backs a managed database; try again. |

## Shell sessions

Answered when a shell, a tunnel or a file transfer into a machine is refused (`ry exec`, `ry ssh`, `ry proxy`).

| Status | Code | Meaning |
| --- | --- | --- |
| 404 | `machine-not-found` | No such machine in your organization. |
| 409 | `console-machine` | The machine is a console or job machine; it takes no shell. |
| 409 | `managed-service` | A managed database; its machine is not opened to a shell. |
| 503 | `resource-check-failed` | Could not tell whether the machine backs a managed database; try again. |
| 409 | `machine-stopped` | The machine is stopped; start it first. |
| 409 | `machine-suspended-no-wake` | The machine is suspended and cannot be woken for this. |
| 503 | `machine-not-placed` | The machine has no host yet. |
| 429 | `too-many-sessions` | The machine has as many shell sessions open as it may. |
| 503 | `host-unavailable` | The machine's host is not reachable right now. |
| 503 | `audit-unavailable` | The audit record of the session could not be written, so it was not opened. |
| 503 | `exec-disabled` | Shell sessions are switched off on this installation. |
| 409 | `guest-agent-absent` | The machine has no guest channel; it was created before shell sessions existed. Deploy it again. |
| 504 | `guest-agent-timeout` | The guest did not answer in time. |
| 409 | `guest-agent-version` | The guest's agent is too old for this; deploy the machine again. |
| 502 | `guest-agent-protocol` | The guest answered something the platform did not expect. |
| 502 | `host-error` | The host failed to open the session. |
| 504 | `host-timeout` | The host did not answer in time. |

## Validation errors

A request that breaks a schema answers `400` with the code `bad-request`. The `error` sentence names every field that was wrong (`invalid request: memoryMb: Too big: expected number to be <=16384`), and `issues` carries the same problems as a list, one entry per field, each with `path` and `message`. Fix every named field at once; the server reports them all in one answer.

---

<!-- Concepts: https://docs.rytiv.com/concepts/regions/ -->

# Regions

> Where your machines, databases and files run. One EU region at launch; a machine never leaves the region it was created in.

A region is the unit everything runs in: its own hosts, its own API, its own address space. Your workloads and data stay in the region of your workspace. Account and billing data stay in the EU whatever the region.

## At launch: EU

Rytiv launches with one region in the EU. Every app, computer, sandbox, database and bucket of a workspace runs there, under `https://<app>.rytiv.app`, and the API is `https://api.rytiv.app`. The region's code in the API is `ams`; the API field `region` on a machine carries it.

A US region follows. When it is offered, a workspace is created in one region and stays there; one login reaches every workspace, and each region has its own API address.

## A machine never moves between regions

A machine is placed in its region when it is created and stays there for its lifetime: a move to another host (`POST /v1/machines/:id/migrate`), a host failure, a deploy that replaces machines, all of it stays inside the region. Capacity is found in the region or not at all (`503` with `no-capacity`), never somewhere else. That is what makes the residency promise a property of the platform rather than a setting.

## What this means for you

- Choose the region with the workspace; nothing after that asks again.
- Internal addresses (`<database>.internal`, app links) resolve inside the region only.
- Static sites are served from the region's edge. It is one region, not a content delivery network.
- Mail is sent from the region's own delivery hosts; the sending domain is yours.

See [Security and data](https://docs.rytiv.com/concepts/security.md) for what stays encrypted and who can read what.

---

<!-- Concepts: https://docs.rytiv.com/concepts/security/ -->

# Security and data

> Where your data lives, how secrets are kept, what a key can reach, how machines are isolated and what TLS covers.

## Data residency

Your workloads and data stay in the region of your workspace, in the EU at launch; see [Regions](https://docs.rytiv.com/concepts/regions.md). Account and billing data stay in the EU whatever the region. Payment pages are served by the payment provider; no card data crosses the Rytiv API.

## Secrets

- Secrets are encrypted at rest with AES-256-GCM under a key the platform holds outside the database, and decrypted only when they are handed to a machine that starts.
- The API never returns a value: `GET /v1/apps/:name/secrets` lists names, when they changed, whether Rytiv manages them, and whether a build sees them.
- **Runtime and build are separate.** Every secret reaches the running app. A build sees only the secrets marked for it (`build: true`; `ry secrets set --build`). A new secret is marked by default only when its name carries a public prefix such as `NEXT_PUBLIC_` or `VITE_`. Secrets the platform creates (`DATABASE_URL`, `S3_*`, `RYTIV_CRON_SECRET`) are runtime only.
- Secrets reach a machine when it starts. A running machine keeps the environment it started with; a new deploy, or a stop and start, picks up the change.
- Managed secrets (the connection URL of an attached database, the key of an attached bucket) follow their attachment and cannot be changed or removed by hand.

## Keys and what they reach

- A key acts as one organization and sees nothing of another; a name of another organization answers like a name that does not exist.
- Keys are stored as a hash; the value is shown once, when created.
- Scopes narrow a key to reading, deploying one app, or sending mail; agent tokens carry a class and an app list the platform enforces on every request. See [Agents and tokens](https://docs.rytiv.com/guides/agents-and-tokens.md).
- A key with scopes or an agent token can never mint, reveal or revoke a credential.
- A shell, a tunnel or a file transfer into a machine needs a key with full access and is audited.

## Machines

- Every app, computer, sandbox and database runs in its own virtual machine with its own kernel, not a container on a shared kernel.
- Machines of one app reach each other over the private network; another app only through an explicit link (`ry link`). A database's internal name resolves only inside the apps attached to it.
- A sandbox can be created with an outbound policy: everything, nothing, or an allowlist of domains and address ranges.

## TLS

- `https://<app>.rytiv.app` is covered by the platform's certificate from the first deploy; port 80 redirects to HTTPS.
- A custom domain gets its own certificate over ACME once ownership is proven, renewed when fewer than 30 days remain. See [Custom domains and TLS](https://docs.rytiv.com/guides/custom-domains.md).
- A Postgres database accepts TLS connections only. The connection URL uses `sslmode=verify-full` against a certificate authority that every machine carries at `/etc/rytiv/ca/postgres.crt`.

## Signing in

The console signs in with a passkey, a one-time code by e-mail, or GitHub where it is switched on; new accounts have no password, and every account enrols a second factor. `ry login` uses a device code you confirm in the console at `https://console.rytiv.com/device`; the key it receives is a key of your team like any other and can be revoked under **Team, Tokens & keys**.

## Durability

- A volume is copied to object storage on a schedule and before its machine sleeps; a database keeps a continuous archive of its write-ahead log (7 days) on top of that, which forks and point-in-time restores read.
- An agent machine with durable checkpoints survives a host failure with its last checkpoint; a computer comes back with the last copy of its home.
- Deleting an app, a database, a volume or a bucket cannot be undone. The CLI asks you to type the name; automation passes `--yes`.

---

<!-- API reference: https://docs.rytiv.com/reference/api-basics/ -->

# REST API basics

> The base URL, how requests are authenticated, the one error format every route answers with, and how to act for a managed organization.

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](https://docs.rytiv.com/reference/api.md) pages, one per family, generated from the control plane's code.

## Base URL

```text
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](https://docs.rytiv.com/authentication.md) as a bearer token on every request:

**curl**

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

**TypeScript**

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

**Python**

```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**

```bash
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](https://docs.rytiv.com/guides/agents-and-tokens.md) 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:

```json
{ "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](https://docs.rytiv.com/concepts/errors.md) 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](https://docs.rytiv.com/reference/api/apps.md) |
| Deploys and releases | detect, builds, deploy, deploys, releases, rollback, previews, Git | [Deploys and releases](https://docs.rytiv.com/reference/api/deploys.md) |
| Machines | `/v1/apps/:name/machines`, `/v1/machines/:id`, logs, snapshots, files | [Machines](https://docs.rytiv.com/reference/api/machines.md) |
| Computers | viewer and control links, control audit | [Computers](https://docs.rytiv.com/reference/api/computers.md) |
| Sandboxes | `/v1/sandboxes` | [Sandboxes](https://docs.rytiv.com/reference/api/sandboxes.md) |
| Postgres | `/v1/resources` | [Postgres](https://docs.rytiv.com/reference/api/postgres.md) |
| Volumes | `/v1/volumes` | [Volumes](https://docs.rytiv.com/reference/api/volumes.md) |
| Buckets | `/v1/buckets`, presign, objects, CORS | [Buckets](https://docs.rytiv.com/reference/api/buckets.md) |
| Secrets | `/v1/apps/:name/secrets` | [Secrets](https://docs.rytiv.com/reference/api/secrets.md) |
| Tokens and keys | `/v1/tokens`, agent actions, SSH keys, device login | [Tokens and keys](https://docs.rytiv.com/reference/api/tokens.md) |
| Organization | `/v1/org`, managed organizations | [Organization](https://docs.rytiv.com/reference/api/organization.md) |
| Billing and usage | `/v1/billing/*`, `/v1/usage` | [Billing and usage](https://docs.rytiv.com/reference/api/billing.md) |
| Custom domains | `/v1/apps/:name/domains`, zones | [Custom domains](https://docs.rytiv.com/reference/api/domains.md) |
| Cron and jobs | schedules, jobs | [Cron and jobs](https://docs.rytiv.com/reference/api/cron-and-jobs.md) |
| Protection and network | protection, network policy, UDP | [Protection and network](https://docs.rytiv.com/reference/api/protection-and-network.md) |
| Mail | `/v1/emails`, `/v1/mail/*` | [Mail](https://docs.rytiv.com/reference/api/mail.md) |
| Webhooks | `/v1/webhooks` | [Webhooks](https://docs.rytiv.com/reference/api/webhooks.md) |
| MCP | `POST /v1/mcp` | [MCP](https://docs.rytiv.com/reference/api/mcp.md), [MCP tools](https://docs.rytiv.com/reference/mcp-tools.md) |
| OAuth and device login | `/v1/oauth/*`, `/v1/device/*` | [OAuth and device login](https://docs.rytiv.com/reference/api/oauth.md) |

---

<!-- API reference: https://docs.rytiv.com/reference/api/ -->

# API reference

> Every endpoint of the Rytiv REST API, generated from the control plane's routes and the contract's schemas.

Everything Rytiv does goes through one HTTP API at `https://api.rytiv.app/v1`. The CLI, the console and the MCP server use the same routes you can call yourself. This reference lists 183 endpoints, generated from the control plane's route registrations and the contract's schemas: every path, every field, every bound and every error code is what the code enforces.

Start with [REST API basics](https://docs.rytiv.com/reference/api-basics.md) for authentication, the error format and how to act for a managed organization. Each family page below lists its endpoints with an example request and the shape of the answer.

## Families

- [Apps](https://docs.rytiv.com/reference/api/apps.md): Create, list, label and delete apps; attach databases, buckets and volumes; link apps to each other.
- [Deploys and releases](https://docs.rytiv.com/reference/api/deploys.md): Detect a project, build it, deploy an image, follow a deploy, list releases and roll back; previews and Git-connected deploys.
- [Machines](https://docs.rytiv.com/reference/api/machines.md): The virtual machines behind an app: create, read, start, stop, suspend, destroy, migrate; logs, snapshots, files and shell sessions.
- [Computers](https://docs.rytiv.com/reference/api/computers.md): Watch or take over a computer's desktop, and see who had control.
- [Sandboxes](https://docs.rytiv.com/reference/api/sandboxes.md): Short-lived machines with a deadline: create from a template, run commands, read and write files, extend, end.
- [Postgres](https://docs.rytiv.com/reference/api/postgres.md): Databases Rytiv runs for you: create, branch, fork, restore, expire, fetch a copy's connection URL, delete.
- [Volumes](https://docs.rytiv.com/reference/api/volumes.md): Persistent disks: create, list, resize, attach to an app, detach, delete.
- [Buckets](https://docs.rytiv.com/reference/api/buckets.md): S3-compatible object storage: create buckets, presign object URLs, list and delete objects, set CORS, attach to apps.
- [Secrets](https://docs.rytiv.com/reference/api/secrets.md): Encrypted environment variables of an app: set, list names, remove, and choose which ones a build may see.
- [Tokens and keys](https://docs.rytiv.com/reference/api/tokens.md): API keys with scopes and expiry, agent tokens with a class, the audit of agent actions, SSH keys and the device login.
- [Organization](https://docs.rytiv.com/reference/api/organization.md): Your organization, its wake page and signed-access keys, organizations you manage for others, and deleting your own.
- [Billing and usage](https://docs.rytiv.com/reference/api/billing.md): Prepaid credit in euro: balance, ledger, top-ups, auto-recharge, the payment portal, the billing preview and metered usage.
- [Custom domains](https://docs.rytiv.com/reference/api/domains.md): Your own domains on an app: add, check, redirect, remove; prove a whole zone once.
- [Cron and jobs](https://docs.rytiv.com/reference/api/cron-and-jobs.md): Schedules that call a path of an app or run a command on a machine of their own, their run history, and one-off jobs.
- [Protection and network](https://docs.rytiv.com/reference/api/protection-and-network.md): Who may open an app (password, signed links), what its machines may reach, and public UDP endpoints.
- [Mail](https://docs.rytiv.com/reference/api/mail.md): Send mail from your own domains, read the delivery log, receive inbound mail, and manage suppressions.
- [Webhooks](https://docs.rytiv.com/reference/api/webhooks.md): Be called when something happens in your organization, and read the deliveries.
- [MCP](https://docs.rytiv.com/reference/api/mcp.md): The MCP server your coding agent talks to: one endpoint, JSON-RPC over HTTP, the same key as every other route.
- [OAuth and device login](https://docs.rytiv.com/reference/api/oauth.md): How a hosted MCP client connects without a pasted key, and how the CLI signs in with a code.

---

<!-- API reference: https://docs.rytiv.com/reference/api/apps/ -->

# Apps

> Create, list, label and delete apps; attach databases, buckets and volumes; link apps to each other.

An app is a name with an address: it answers on `https://<app>.rytiv.app` and owns its machines, deploys, secrets, logs and releases. Names are unique across all of Rytiv: 2 to 63 characters, lowercase letters, digits and hyphens, starting with a letter. A computer is an app too, created with `"computer": true` (see [Computers](https://docs.rytiv.com/reference/api/computers.md)).

Deploying is on its own page: [Deploys and releases](https://docs.rytiv.com/reference/api/deploys.md).

## Endpoints

- [`POST /v1/apps`](#post-v1apps): Creates an app. With `computer: true` it is created as a computer and counts against the organization's computer limit
- [`GET /v1/apps`](#get-v1apps): Lists the organization's apps. Repeat `label=<key>=<value>` to filter by label. A key with `deploy:<app>` scopes sees only its apps
- [`GET /v1/apps/:name`](#get-v1appsname): One app
- [`PATCH /v1/apps/:name`](#patch-v1appsname): Changes an app's labels
- [`DELETE /v1/apps/:name`](#delete-v1appsname): Deletes the app and all its machines. It cannot be undone. An app that backs a database is removed with the database, not on its own
- [`PUT /v1/apps/:name/labels`](#put-v1appsnamelabels): Replaces the app's labels
- [`GET /v1/apps/:name/maintenance`](#get-v1appsnamemaintenance): Whether the app is in maintenance mode
- [`PUT /v1/apps/:name/maintenance`](#put-v1appsnamemaintenance): Switches maintenance mode on or off
- [`POST /v1/apps/:name/attach`](#post-v1appsnameattach): Attaches a database (`resource`), a bucket (`bucket`, optional `as` prefix) or a free volume (`volume`) to the app. The app sees the new environment from its next start
- [`POST /v1/apps/:name/detach`](#post-v1appsnamedetach): Detaches a bucket from the app and removes the environment it injected
- [`GET /v1/attachments`](#get-v1attachments): Every database attachment of the organization
- [`POST /v1/apps/:name/link`](#post-v1appsnamelink): Lets this app reach another app of the organization over the private network
- [`DELETE /v1/apps/:name/link/:target`](#delete-v1appsnamelinktarget): Removes that link
- [`GET /v1/app-links`](#get-v1app-links): Every app link of the organization

## POST /v1/apps

Creates an app. With `computer: true` it is created as a computer and counts against the organization's computer limit.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Request body

JSON, the shape `CreateAppRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | required | The app's name: 2 to 63 characters, lowercase letters, digits and hyphens, starting with a letter. Unique across Rytiv. |
| `labels` | object of string | optional | Free key/value pairs to find the app again (`?label=key=value`). Never a secret, never part of the environment. |
| `computer` | boolean | optional | `true` creates the app as a computer: it counts against the organization's computer limit. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-app"}'
```

### Response

`201` with the app:

```json
{
  "name": "my-app",
  "orgId": "<orgId>",
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `name` | string | always | The app's name. |
| `orgId` | string | always | The organization that owns it. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `kind` | `machine` \| `static` | if set | `machine`: served by machines. `static`: files served at the edge, no machine. |
| `protection` | `password` \| `link` \| `signed` | if set | How the app is protected, if it is; absent means public. |
| `slug` | string | if set | The app's fixed identifier; the CNAME target of a custom domain is built from it. |
| `labels` | object of string | if set | The app's labels. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 400 | `name-reserved` | The platform keeps this name (for example `api`, `console`, `docs`, `www`, and every name that is `rytiv` or starts with `rytiv-`). |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `org-limit-apps` | The organization has as many apps as it may have (computers included). The body carries `limit` and `current`. |
| 403 | `org-limit-computers` | The organization has as many computers as it may have. The body carries `limit` and `current`. Delete one, or contact us for more. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 409 | `name-taken` | The name is used somewhere on Rytiv (an app, a database, a volume or a bucket). |

## GET /v1/apps

Lists the organization's apps. Repeat `label=<key>=<value>` to filter by label. A key with `deploy:<app>` scopes sees only its apps.

**Auth:** API key with full access or a deploy scope (`deploy` or `deploy:<app>`), or the scope `read`. Every class of agent token may call it.

### Query parameters

| Name | Description |
| --- | --- |
| `label` | Filter by label, `key=value`; repeat for several. Apps match when every term matches. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of apps, each:

```json
[
  {
    "name": "my-app",
    "orgId": "<orgId>",
    "createdAt": "2026-10-21T09:00:00Z"
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `name` | string | always | The app's name. |
| `orgId` | string | always | The organization that owns it. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `kind` | `machine` \| `static` | if set | `machine`: served by machines. `static`: files served at the edge, no machine. |
| `protection` | `password` \| `link` \| `signed` | if set | How the app is protected, if it is; absent means public. |
| `slug` | string | if set | The app's fixed identifier; the CNAME target of a custom domain is built from it. |
| `labels` | object of string | if set | The app's labels. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid-label-filter` | A `label` term is not `key=value` with a valid key. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/apps/:name

One app.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app, or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the app:

```json
{
  "name": "my-app",
  "orgId": "<orgId>",
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `name` | string | always | The app's name. |
| `orgId` | string | always | The organization that owns it. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `kind` | `machine` \| `static` | if set | `machine`: served by machines. `static`: files served at the edge, no machine. |
| `protection` | `password` \| `link` \| `signed` | if set | How the app is protected, if it is; absent means public. |
| `slug` | string | if set | The app's fixed identifier; the CNAME target of a custom domain is built from it. |
| `labels` | object of string | if set | The app's labels. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## PATCH /v1/apps/:name

Changes an app's labels.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `PatchAppRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `labels` | object of string or null | required |  |

### Example request

```bash
curl -X PATCH "https://api.rytiv.app/v1/apps/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"labels":{"<key>":"<value>"}}'
```

### Response

A JSON body on success.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/apps/:name

Deletes the app and all its machines. It cannot be undone. An app that backs a database is removed with the database, not on its own.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/apps/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `sandbox-carrier` |  |

## PUT /v1/apps/:name/labels

Replaces the app's labels.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `PutAppLabelsRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `labels` | object of string | required |  |

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/apps/<name>/labels" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"labels":{"<key>":"<value>"}}'
```

### Response

A JSON body on success.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/apps/:name/maintenance

Whether the app is in maintenance mode.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/maintenance" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## PUT /v1/apps/:name/maintenance

Switches maintenance mode on or off.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `SetMaintenanceRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | required | `false` creates the schedule paused. |

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/apps/<name>/maintenance" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/apps/:name/attach

Attaches a database (`resource`), a bucket (`bucket`, optional `as` prefix) or a free volume (`volume`) to the app. The app sees the new environment from its next start.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `AttachRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `resource` | string | required | The name of the database to attach. The app gets its connection URL as the secret `DATABASE_URL`. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/attach" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource":"my-db"}'
```

### Response

`200` with a JSON object carrying `app`, `resource`, `injected`, `url`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/apps/:name/detach

Detaches a bucket from the app and removes the environment it injected.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/detach" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bucket":"my-bucket"}'
```

### Response

A JSON body on success.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/attachments

Every database attachment of the organization.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/attachments" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## POST /v1/apps/:name/link

Lets this app reach another app of the organization over the private network.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `AppLinkRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `target` | string | required |  |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/link" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"my-api"}'
```

### Response

`201` with a JSON object carrying `app`, `target`, `name`, `activeInS`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/apps/:name/link/:target

Removes that link.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `target` | The name of the linked app. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/apps/<name>/link/<target>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/app-links

Every app link of the organization.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/app-links" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/deploys/ -->

# Deploys and releases

> Detect a project, build it, deploy an image, follow a deploy, list releases and roll back; previews and Git-connected deploys.

A deploy puts an image behind an app: an OCI reference such as `nginx:alpine`, or `build:<id>` for a build Rytiv made from your source. Every deploy that goes live is a release, and a rollback deploys an earlier release's image again without a rebuild.

A deploy rolls one machine at a time: the new machine must boot and answer on its port (and pass the health check, if you set one) before an old one is taken out of traffic. If the new machine fails, the deploy stops and the old version keeps serving. After the switch, the deploy keeps watching the app's error rate for a while and rolls back on its own if it gets worse than before; the deploy's `watch` field says what it found.

The CLI does the whole path for you: `ry deploy <app> --source .` detects the project, uploads it, builds it on Rytiv's machines and deploys the result. See the guide [Deploy a Next.js app](https://docs.rytiv.com/guides/deploy-nextjs.md).

## Endpoints

- [`POST /v1/detect`](#post-v1detect): Reads a project's manifest and answers what Rytiv would build and start, before any build
- [`POST /v1/apps/:name/builds`](#post-v1appsnamebuilds): Uploads a source archive and starts a build on Rytiv's build machines
- [`GET /v1/apps/:name/builds/:id`](#get-v1appsnamebuildsid): One build with its state and log
- [`POST /v1/apps/:name/deploy`](#post-v1appsnamedeploy): Deploys an image to the app and answers the deploy right away. Poll `GET /v1/deploys/:id` until `status` is `done` or `error`
- [`GET /v1/apps/:name/deploys`](#get-v1appsnamedeploys): The app's deploys, newest first
- [`GET /v1/deploys/:id`](#get-v1deploysid): One deploy: its status, the machines it created and retired, and after the switch the watch verdict
- [`GET /v1/apps/:name/releases`](#get-v1appsnamereleases): The app's releases, which one runs, and which one a rollback would bring back
- [`POST /v1/apps/:name/rollback`](#post-v1appsnamerollback): Deploys an earlier release's image again, without a rebuild, with the app's current settings. Empty body: the previous release that went live
- [`GET /v1/apps/:name/previews`](#get-v1appsnamepreviews): The preview apps of a Git-connected app, one per branch
- [`POST /v1/apps/:name/previews`](#post-v1appsnamepreviews): Creates a preview app for a branch
- [`DELETE /v1/apps/:name/previews/:branch`](#delete-v1appsnamepreviewsbranch): Removes the preview app of a branch
- [`PUT /v1/apps/:name/git`](#put-v1appsnamegit): Connects the app to a repository of an installed GitHub app: a push then deploys
- [`GET /v1/apps/:name/git`](#get-v1appsnamegit): The app's repository connection
- [`DELETE /v1/apps/:name/git`](#delete-v1appsnamegit): Disconnects the repository
- [`GET /v1/apps/:name/git/deploys`](#get-v1appsnamegitdeploys): The deploys a push triggered
- [`POST /v1/git/connect`](#post-v1gitconnect): Starts the installation of the GitHub app and answers the link to open
- [`GET /v1/git/connect/:id`](#get-v1gitconnectid): Whether that installation has completed
- [`POST /v1/git/installations`](#post-v1gitinstallations): Records an installation of the GitHub app
- [`GET /v1/git/installations`](#get-v1gitinstallations): The organization's installations
- [`DELETE /v1/git/installations/:id`](#delete-v1gitinstallationsid): Forgets an installation

## POST /v1/detect

Reads a project's manifest and answers what Rytiv would build and start, before any build.

**Auth:** API key with full access or a deploy scope (`deploy` or `deploy:<app>`). Every class of agent token may call it.

### Request body

JSON, the shape `DetectRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `app` | string | optional |  |
| `inventory` | object | required |  |
| `inventory.packageJson` | object of any or null | optional |  |
| `inventory.files` | array of string | optional | 0 to 4000 items. |
| `inventory.envExample` | string or null | optional |  |
| `inventory.envRefs` | array of string | optional | 0 to 500 items. |
| `inventory.configs` | object of string | optional |  |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/detect" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inventory":{"packageJson":{"<key>":"<value>"}}}'
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## POST /v1/apps/:name/builds

Uploads a source archive and starts a build on Rytiv's build machines.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app. An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Query parameters

| Name | Description |
| --- | --- |
| `buildMemoryMb` |  |
| `commitSha` |  |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/builds" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @source.tar.gz
```

### Response

`202` with a JSON object carrying `id`, `buildId`, `status`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/apps/:name/builds/:id

One build with its state and log.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app, or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `id` | The object's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/builds/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/apps/:name/deploy

Deploys an image to the app and answers the deploy right away. Poll `GET /v1/deploys/:id` until `status` is `done` or `error`.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app. An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `DeployRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `image` | string | required | What to deploy: an OCI reference, or `build:<id>` for a build of yours. 1 to 512 characters. |
| `class` | `shared-cpu-1x` \| `shared-cpu-2x` \| `shared-cpu-4x` \| `shared-cpu-8x` \| `performance-1x` \| `performance-2x` \| `performance-4x` \| `performance-8x` | optional | A named size instead of `vcpus`; the two must not contradict each other. |
| `vcpus` | integer | optional | Virtual CPUs. 1 to 16, default `1`. |
| `memoryMb` | integer | optional | Memory in MB. 128 to 16384, default `512`. |
| `env` | object of string | optional | Plain environment variables. Use secrets for credentials. |
| `diskMb` | integer | optional | The machine's disk in MB. Without it, the image's size plus headroom. 512 to 131072. |
| `volumeGb` | integer | optional | A volume of this size, attached to the machine. 1 to 500. |
| `start` | string | optional | The start command, run through `/bin/sh -c`. It replaces what detection chose or the image's `CMD`. 1 to 2000 characters. |
| `internalPort` | integer | optional | The port the app listens on. 1 to 65535, default `3000`. |
| `suspendPolicy` | object | optional | When the machine sleeps. Without it, a new app never sleeps; a deploy without it keeps the app's rule. |
| `suspendPolicy.mode` | `suspend` \| `stop` \| `off` | optional | `suspend` keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), `stop` shuts down, `off` never sleeps. default `"suspend"`. |
| `suspendPolicy.idleSeconds` | integer | optional | Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default `300`. |
| `suspendPolicy.stopAfterSeconds` | integer | optional | Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with `mode: "suspend"`, and greater than `idleSeconds`. 10 to 604800. |
| `healthCheck` | object | optional | An HTTP check a new machine must pass before it gets traffic. |
| `healthCheck.path` | string | optional | The path to call; empty means the port alone. default `""`. |
| `healthCheck.timeoutMs` | integer | optional | How long one probe may take. 100 to 30000, default `2000`. |
| `healthCheck.intervalMs` | integer | optional | Time between probes. 100 to 10000, default `500`. |
| `healthCheck.healthyThreshold` | integer | optional | Probes that must pass in a row. 1 to 10, default `1`. |
| `healthCheck.maxWaitMs` | integer | optional | How long a new machine may take in total before the deploy gives up on it. 1000 to 300000. |
| `restart` | object | optional | What happens when the process ends. Without it, a crashed machine is restarted. |
| `restart.policy` | `never` \| `on-failure` | optional | `never` or `on-failure`. default `"never"`. |
| `restart.retries` | integer | optional | Restarts before the machine stays down. 1 to 10, default `3`. |
| `killSignal` | `SIGTERM` \| `SIGINT` \| `SIGQUIT` \| `SIGHUP` \| `SIGUSR1` \| `SIGUSR2` \| `SIGWINCH` \| `SIGKILL` | optional | The signal sent before a machine is stopped or replaced. Default: the image's `STOPSIGNAL`, else `SIGTERM`. |
| `killTimeoutS` | integer | optional | Seconds between that signal and `SIGKILL`. 1 to 300. |
| `durableCheckpoint` | boolean | optional | Agent machine: the whole state (memory and disk) is checkpointed and survives a host failure. default `false`. |
| `checkpointIntervalS` | integer | optional | 5 to 3600. |
| `console` | boolean | optional | default `false`. |
| `command` | array of string | optional | Runs on a machine of its own, as an argument list. 1 to 64 items. |
| `diskIsCache` | boolean | optional |  |
| `readiness` | `port` \| `boot` | optional | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. |
| `exposePorts` | array of integer | optional | 0 to 8 items. |
| `egress` | object | optional | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `egress.mode` | `deny-all` \| `allowlist` | required | `view` to watch, `control` to take keyboard and mouse. |
| `egress.domains` | array of string | required | 0 to 100 items. |
| `egress.cidrs` | array of string | required | 0 to 10 items. |
| `count` | integer | optional | How many machines the app runs. A deploy without it keeps the current count. 1 to 20. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/deploy" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image":"nginx:alpine"}'
```

### Response

`202` with the deploy (`deployId` repeats `id` for older readers):

```json
{
  "id": "<id>",
  "orgId": "<orgId>",
  "app": "my-app",
  "image": "nginx:alpine",
  "status": "running",
  "created": [
    "<created>"
  ],
  "retired": [
    "<retired>"
  ],
  "at": "2026-10-21T09:00:00Z",
  "deployId": "<deployId>"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always |  |
| `orgId` | string | always | The organization that owns it. |
| `app` | string | always |  |
| `image` | string | always | An OCI reference such as `nginx:alpine`, or `build:<id>` for a build of your organization. |
| `status` | `running` \| `done` \| `error` | always |  |
| `created` | array of string | always |  |
| `retired` | array of string | always |  |
| `at` | string (ISO 8601) | always |  |
| `error` | string | if set |  |
| `bootLog` | string | if set |  |
| `watch` | object | if set |  |
| `watch.forDeployId` | string | always |  |
| `watch.from` | string (ISO 8601) | always |  |
| `watch.until` | string (ISO 8601) | always |  |
| `watch.baseline` | object | always |  |
| `watch.rounds` | integer | always | 0 to 9007199254740991. |
| `watch.lastAt` | string (ISO 8601) | if set |  |
| `watch.lastText` | string | if set |  |
| `watch.outcome` | `healthy` \| `unproven` \| `rolled-back` \| `not-rolled-back` \| `superseded` \| `expired` | if set |  |
| `watch.outcomeText` | string | if set |  |
| `watch.outcomeAt` | string (ISO 8601) | if set |  |
| `watch.rollback` | object | if set |  |
| `watch.database` | object | if set |  |
| `kind` | `"static"` | if set | `static` for a site deploy. |
| `deployId` | string | always | The same value as `id`, for readers from before. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `build-not-found` | `build:<id>` is not a build of your organization. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `deploy-in-flight` | Another deploy of this app is running. |
| 409 | `volume-needs-single-machine` | An app with a volume runs exactly one machine. |

## GET /v1/apps/:name/deploys

The app's deploys, newest first.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app, or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | How many entries, at most. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/deploys" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of deploys, each:

```json
[
  {
    "id": "<id>",
    "orgId": "<orgId>",
    "app": "my-app",
    "image": "nginx:alpine",
    "status": "running",
    "created": [
      "<created>"
    ],
    "retired": [
      "<retired>"
    ],
    "at": "2026-10-21T09:00:00Z"
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The deploy's id. |
| `orgId` | string | always | The organization that owns it. |
| `app` | string | always | The app. |
| `image` | string | always | What was deployed. |
| `status` | `running` \| `done` \| `error` | always | `running` while it rolls, then `done` or `error`. |
| `created` | array of string | always | The machines this deploy created. |
| `retired` | array of string | always | The machines it took out of traffic. |
| `at` | string (ISO 8601) | always | When it started. |
| `error` | string | if set | On `error`: why. |
| `bootLog` | string | if set | On `error`: the last console lines of the machine that failed. |
| `watch` | object | if set | After the switch: what the watch over the app's error rate found (`healthy`, `unproven`, `rolled-back` and more). Absent while the deploy rolls, and for a rollback. |
| `watch.forDeployId` | string | always |  |
| `watch.from` | string (ISO 8601) | always |  |
| `watch.until` | string (ISO 8601) | always |  |
| `watch.baseline` | object | always |  |
| `watch.rounds` | integer | always | 0 to 9007199254740991. |
| `watch.lastAt` | string (ISO 8601) | if set |  |
| `watch.lastText` | string | if set |  |
| `watch.outcome` | `healthy` \| `unproven` \| `rolled-back` \| `not-rolled-back` \| `superseded` \| `expired` | if set |  |
| `watch.outcomeText` | string | if set |  |
| `watch.outcomeAt` | string (ISO 8601) | if set |  |
| `watch.rollback` | object | if set |  |
| `watch.database` | object | if set |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/deploys/:id

One deploy: its status, the machines it created and retired, and after the switch the watch verdict.

**Auth:** API key with full access or a deploy scope (`deploy` or `deploy:<app>`), or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The deploy's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/deploys/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the deploy:

```json
{
  "id": "<id>",
  "orgId": "<orgId>",
  "app": "my-app",
  "image": "nginx:alpine",
  "status": "running",
  "created": [
    "<created>"
  ],
  "retired": [
    "<retired>"
  ],
  "at": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The deploy's id. |
| `orgId` | string | always | The organization that owns it. |
| `app` | string | always | The app. |
| `image` | string | always | What was deployed. |
| `status` | `running` \| `done` \| `error` | always | `running` while it rolls, then `done` or `error`. |
| `created` | array of string | always | The machines this deploy created. |
| `retired` | array of string | always | The machines it took out of traffic. |
| `at` | string (ISO 8601) | always | When it started. |
| `error` | string | if set | On `error`: why. |
| `bootLog` | string | if set | On `error`: the last console lines of the machine that failed. |
| `watch` | object | if set | After the switch: what the watch over the app's error rate found (`healthy`, `unproven`, `rolled-back` and more). Absent while the deploy rolls, and for a rollback. |
| `watch.forDeployId` | string | always |  |
| `watch.from` | string (ISO 8601) | always |  |
| `watch.until` | string (ISO 8601) | always |  |
| `watch.baseline` | object | always |  |
| `watch.rounds` | integer | always | 0 to 9007199254740991. |
| `watch.lastAt` | string (ISO 8601) | if set |  |
| `watch.lastText` | string | if set |  |
| `watch.outcome` | `healthy` \| `unproven` \| `rolled-back` \| `not-rolled-back` \| `superseded` \| `expired` | if set |  |
| `watch.outcomeText` | string | if set |  |
| `watch.outcomeAt` | string (ISO 8601) | if set |  |
| `watch.rollback` | object | if set |  |
| `watch.database` | object | if set |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/apps/:name/releases

The app's releases, which one runs, and which one a rollback would bring back.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app, or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | How many entries, at most. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/releases" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the release list:

```json
{
  "app": "<app>",
  "releases": [
    {
      "id": "<id>",
      "version": 1,
      "status": "running",
      "at": "2026-10-21T09:00:00Z",
      "startedAt": "2026-10-21T09:00:00Z",
      "image": "nginx:alpine",
      "source": {
        "kind": "git",
        "repo": "<repo>",
        "branch": "<branch>",
        "commit": "<commit>"
      },
      "current": true,
      "rolledBack": true,
      "artifact": "retained",
      "rollback": {
        "possible": true
      }
    }
  ],
  "retention": {
    "keepBuilds": 1
  }
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `app` | string | always |  |
| `currentId` | string | if set |  |
| `releases` | array of object | always | The releases, newest first. |
| `rollbackTarget` | object | if set |  |
| `rollbackTarget.id` | string | always |  |
| `rollbackTarget.version` | integer | always | 1 to 9007199254740991. |
| `retention` | object | always |  |
| `retention.keepBuilds` | integer | always | 1 to 9007199254740991. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/apps/:name/rollback

Deploys an earlier release's image again, without a rebuild, with the app's current settings. Empty body: the previous release that went live.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app. An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `RollbackRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | integer | optional | 1 to 9007199254740991. |
| `releaseId` | string | optional | 1 to 64 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/rollback" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Response

`202` with the deploy that brings the release back:

```json
{
  "id": "<id>",
  "orgId": "<orgId>",
  "app": "my-app",
  "image": "nginx:alpine",
  "status": "running",
  "created": [
    "<created>"
  ],
  "retired": [
    "<retired>"
  ],
  "at": "2026-10-21T09:00:00Z",
  "deployId": "<deployId>"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always |  |
| `orgId` | string | always | The organization that owns it. |
| `app` | string | always |  |
| `image` | string | always | An OCI reference such as `nginx:alpine`, or `build:<id>` for a build of your organization. |
| `status` | `running` \| `done` \| `error` | always |  |
| `created` | array of string | always |  |
| `retired` | array of string | always |  |
| `at` | string (ISO 8601) | always |  |
| `error` | string | if set |  |
| `bootLog` | string | if set |  |
| `watch` | object | if set |  |
| `watch.forDeployId` | string | always |  |
| `watch.from` | string (ISO 8601) | always |  |
| `watch.until` | string (ISO 8601) | always |  |
| `watch.baseline` | object | always |  |
| `watch.rounds` | integer | always | 0 to 9007199254740991. |
| `watch.lastAt` | string (ISO 8601) | if set |  |
| `watch.lastText` | string | if set |  |
| `watch.outcome` | `healthy` \| `unproven` \| `rolled-back` \| `not-rolled-back` \| `superseded` \| `expired` | if set |  |
| `watch.outcomeText` | string | if set |  |
| `watch.outcomeAt` | string (ISO 8601) | if set |  |
| `watch.rollback` | object | if set |  |
| `watch.database` | object | if set |  |
| `kind` | `"static"` | if set | `static` for a site deploy. |
| `deployId` | string | always | The same value as `id`, for readers from before. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 404 | `release-not-found` | No release with that version or id. |
| 409 | `deploy-in-flight` | Another deploy of this app is running. |
| 409 | `no-previous-release` | There is no earlier release that went live. |
| 409 | `release-artifact-gone` | The release's image is no longer available. |
| 409 | `rollback-needs-machine-config` | The app has no machine whose settings a rollback could reuse. |
| 409 | `rollback-not-for-resources` | The app backs a database; databases are restored, not rolled back. |
| 409 | `rollback-same-build` | That release runs the same build as the current one. |
| 409 | `rollback-target-current` | That release is the one that runs. |
| 409 | `rollback-target-never-live` | That release never went live, so there is nothing to bring back. |

## GET /v1/apps/:name/previews

The preview apps of a Git-connected app, one per branch.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/previews" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `previews`, `ttlDays`, `maxPerApp`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/apps/:name/previews

Creates a preview app for a branch.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/previews" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"feature/login"}'
```

### Response

A JSON body on success.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `branch` |  |
| 400 | `name-reserved` | The platform keeps this name (for example `api`, `console`, `docs`, `www`, and every name that is `rytiv` or starts with `rytiv-`). |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `already-a-preview` |  |
| 409 | `base-branch` |  |
| 409 | `not-connected` |  |
| 409 | `preview-name-taken` |  |

## DELETE /v1/apps/:name/previews/:branch

Removes the preview app of a branch.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `branch` | The branch name of the preview. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/apps/<name>/previews/<branch>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## PUT /v1/apps/:name/git

Connects the app to a repository of an installed GitHub app: a push then deploys.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `ConnectRepoRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `installationId` | string | required | 1 to 64 characters. |
| `repo` | string | required | 1 to 300 characters. |
| `branch` | string | optional | 1 to 255 characters. |
| `repoExternalId` | string | optional | 1 to 64 characters. |
| `autoDeploy` | boolean | optional |  |
| `subdirectory` | string | optional | at most 200 characters. |
| `previewDeploys` | boolean | optional |  |

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/apps/<name>/git" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"installationId":"<installationId>","repo":"<repo>"}'
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 400 | `branch` |  |
| 400 | `subdirectory` |  |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/apps/:name/git

The app's repository connection.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/git" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `connected`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/apps/:name/git

Disconnects the repository.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/apps/<name>/git" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/apps/:name/git/deploys

The deploys a push triggered.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | How many entries, at most. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/git/deploys" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/git/connect

Starts the installation of the GitHub app and answers the link to open.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/git/connect" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`201` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/git/connect/:id

Whether that installation has completed.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/git/connect/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/git/installations

Records an installation of the GitHub app.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `ConnectInstallationRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | `github` | optional |  |
| `externalId` | string | required |  |
| `state` | string | required |  |
| `code` | string | required | 1 to 256 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/git/installations" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"<externalId>","state":"<state>","code":"<code>"}'
```

### Response

`200` or `201` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `state` |  |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/git/installations

The organization's installations.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/git/installations" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## DELETE /v1/git/installations/:id

Forgets an installation.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Query parameters

| Name | Description |
| --- | --- |
| `force` |  |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/git/installations/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/machines/ -->

# Machines

> The virtual machines behind an app: create, read, start, stop, suspend, destroy, migrate; logs, snapshots, files and shell sessions.

A machine is one virtual machine of an app. A deploy creates machines for you; this family is for reading them, acting on one, and for the machines you create yourself (a computer, an agent's workspace). A machine is `requested`, `scheduled`, `starting`, `running`, `suspending`, `suspended`, `stopping`, `stopped`, `deleted` or `failed`.

The shell routes (`ry exec`, `ry ssh`, `ry proxy`) upgrade the connection to a WebSocket and are not plain JSON calls; use the CLI for them.

## Endpoints

- [`POST /v1/apps/:name/machines`](#post-v1appsnamemachines): Creates a machine in the app and waits until it runs. Add `?wait=false` for `202` right away and poll `GET /v1/machines/:id/wait`
- [`GET /v1/apps/:name/machines`](#get-v1appsnamemachines): The app's machines
- [`GET /v1/machines/:id`](#get-v1machinesid): One machine
- [`GET /v1/machines/:id/wait`](#get-v1machinesidwait): Holds the request until the machine reaches a state (`?state=`), at most `?timeout=` seconds; `408` when it runs out
- [`POST /v1/machines/:id/:action`](#post-v1machinesidaction): Acts on a machine: `start`, `stop`, `suspend` or `destroy`
- [`POST /v1/machines/:id/migrate`](#post-v1machinesidmigrate): Moves the machine to another host
- [`GET /v1/apps/:name/logs`](#get-v1appsnamelogs): The console output of the app's machines, with a cursor per machine for the next call
- [`POST /v1/machines/:id/checkpoints`](#post-v1machinesidcheckpoints): Takes a named snapshot of the machine: its disk, and with `memory: true` its running memory too
- [`GET /v1/machines/:id/checkpoints`](#get-v1machinesidcheckpoints): The machine's named snapshots. Add `?auto=1` to include the automatic ones
- [`DELETE /v1/machines/:id/checkpoints/:label`](#delete-v1machinesidcheckpointslabel): Forgets a snapshot
- [`POST /v1/machines/:id/checkpoints/:label/restore`](#post-v1machinesidcheckpointslabelrestore): Brings the machine back to that snapshot. With `keepCurrent: true` (the default) the current state is saved first
- [`GET /v1/machines/:id/files`](#get-v1machinesidfiles): Reads one file of the machine (`?path=`), as raw bytes
- [`PUT /v1/machines/:id/files`](#put-v1machinesidfiles): Writes one file of the machine (`?path=`); the body is the file's bytes
- [`GET /v1/machines/:id/files/list`](#get-v1machinesidfileslist): Lists a directory of the machine (`?path=`)
- [`GET /v1/machines/:id/screenshot`](#get-v1machinesidscreenshot): A screenshot of the machine's desktop, for a machine that has one
- [`GET /v1/machines/:id/exec`](#get-v1machinesidexec): Opens a shell session over a WebSocket. This is what `ry exec` and `ry ssh` use; it is not a plain JSON call
- [`GET /v1/machines/:id/exec-sessions`](#get-v1machinesidexec-sessions): The shell sessions open on the machine

## POST /v1/apps/:name/machines

Creates a machine in the app and waits until it runs. Add `?wait=false` for `202` right away and poll `GET /v1/machines/:id/wait`.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Query parameters

| Name | Description |
| --- | --- |
| `wait` | `false` answers `202` as soon as the row exists, before the boot; the default waits for the running machine. |

### Request body

JSON, the shape `CreateMachineRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `image` | string | required | An OCI reference such as `nginx:alpine`, or `build:<id>` for a build of your organization. 1 to 512 characters. |
| `class` | `shared-cpu-1x` \| `shared-cpu-2x` \| `shared-cpu-4x` \| `shared-cpu-8x` \| `performance-1x` \| `performance-2x` \| `performance-4x` \| `performance-8x` | optional | A named size instead of `vcpus`; the two must not contradict each other. |
| `vcpus` | integer | optional | Virtual CPUs. 1 to 16, default `1`. |
| `memoryMb` | integer | optional | Memory in MB. 128 to 16384, default `512`. |
| `env` | object of string | optional | Plain environment variables. Use secrets for credentials. |
| `diskMb` | integer | optional | The machine's disk in MB. Without it, the image's size plus headroom. 512 to 131072. |
| `volumeGb` | integer | optional | A volume of this size, attached to the machine. 1 to 500. |
| `start` | string | optional | The start command, run through `/bin/sh -c`. It replaces what detection chose or the image's `CMD`. 1 to 2000 characters. |
| `internalPort` | integer | optional | The port the app listens on. 1 to 65535, default `3000`. |
| `suspendPolicy` | object | optional | When the machine sleeps. Without it, a new app never sleeps; a deploy without it keeps the app's rule. |
| `suspendPolicy.mode` | `suspend` \| `stop` \| `off` | optional | `suspend` keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), `stop` shuts down, `off` never sleeps. default `"suspend"`. |
| `suspendPolicy.idleSeconds` | integer | optional | Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default `300`. |
| `suspendPolicy.stopAfterSeconds` | integer | optional | Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with `mode: "suspend"`, and greater than `idleSeconds`. 10 to 604800. |
| `healthCheck` | object | optional | An HTTP check a new machine must pass before it gets traffic. |
| `healthCheck.path` | string | optional | The path to call; empty means the port alone. default `""`. |
| `healthCheck.timeoutMs` | integer | optional | How long one probe may take. 100 to 30000, default `2000`. |
| `healthCheck.intervalMs` | integer | optional | Time between probes. 100 to 10000, default `500`. |
| `healthCheck.healthyThreshold` | integer | optional | Probes that must pass in a row. 1 to 10, default `1`. |
| `healthCheck.maxWaitMs` | integer | optional | How long a new machine may take in total before the deploy gives up on it. 1000 to 300000. |
| `restart` | object | optional | What happens when the process ends. Without it, a crashed machine is restarted. |
| `restart.policy` | `never` \| `on-failure` | optional | `never` or `on-failure`. default `"never"`. |
| `restart.retries` | integer | optional | Restarts before the machine stays down. 1 to 10, default `3`. |
| `killSignal` | `SIGTERM` \| `SIGINT` \| `SIGQUIT` \| `SIGHUP` \| `SIGUSR1` \| `SIGUSR2` \| `SIGWINCH` \| `SIGKILL` | optional | The signal sent before a machine is stopped or replaced. Default: the image's `STOPSIGNAL`, else `SIGTERM`. |
| `killTimeoutS` | integer | optional | Seconds between that signal and `SIGKILL`. 1 to 300. |
| `durableCheckpoint` | boolean | optional | Agent machine: the whole state (memory and disk) is checkpointed and survives a host failure. default `false`. |
| `checkpointIntervalS` | integer | optional | 5 to 3600. |
| `console` | boolean | optional | default `false`. |
| `command` | array of string | optional | Runs on a machine of its own, as an argument list. 1 to 64 items. |
| `diskIsCache` | boolean | optional |  |
| `readiness` | `port` \| `boot` | optional | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. |
| `exposePorts` | array of integer | optional | 0 to 8 items. |
| `egress` | object | optional | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `egress.mode` | `deny-all` \| `allowlist` | required | `view` to watch, `control` to take keyboard and mouse. |
| `egress.domains` | array of string | required | 0 to 100 items. |
| `egress.cidrs` | array of string | required | 0 to 10 items. |
| `region` | string | optional | The region to place the machine in. Without it, the organization's region. 2 to 12 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/machines" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image":"rytiv/computer:0.1.0"}'
```

### Response

`201` with the machine (plus `bootMs`, the time the boot took):

```json
{
  "id": "<id>",
  "appName": "my-app",
  "config": {
    "image": "nginx:alpine",
    "vcpus": 1,
    "memoryMb": 512,
    "env": {
      "<key>": "<value>"
    },
    "internalPort": 3000,
    "suspendPolicy": {
      "mode": "suspend",
      "idleSeconds": 300
    },
    "durableCheckpoint": false,
    "console": false
  },
  "desiredState": "requested",
  "observedState": "requested",
  "region": "<region>",
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The machine's id. |
| `appName` | string | always | The app it belongs to. |
| `config` | object | always | What it runs: image, size, environment and the settings of a deploy request. |
| `config.image` | string | always | An OCI reference such as `nginx:alpine`, or `build:<id>` for a build of your organization. 1 to 512 characters. |
| `config.class` | `shared-cpu-1x` \| `shared-cpu-2x` \| `shared-cpu-4x` \| `shared-cpu-8x` \| `performance-1x` \| `performance-2x` \| `performance-4x` \| `performance-8x` | if set | A named size instead of `vcpus`; the two must not contradict each other. |
| `config.vcpus` | integer | always | Virtual CPUs. 1 to 16, default `1`. |
| `config.memoryMb` | integer | always | Memory in MB. 128 to 16384, default `512`. |
| `config.env` | object of string | always | Plain environment variables. Use secrets for credentials. |
| `config.diskMb` | integer | if set | The machine's disk in MB. Without it, the image's size plus headroom. 512 to 131072. |
| `config.volumeGb` | integer | if set | A volume of this size, attached to the machine. 1 to 500. |
| `config.start` | string | if set | The start command, run through `/bin/sh -c`. It replaces what detection chose or the image's `CMD`. 1 to 2000 characters. |
| `config.internalPort` | integer | always | The port the app listens on. 1 to 65535, default `3000`. |
| `config.suspendPolicy` | object | always | When the machine sleeps. Without it, a new app never sleeps; a deploy without it keeps the app's rule. |
| `config.healthCheck` | object | if set | An HTTP check a new machine must pass before it gets traffic. |
| `config.restart` | object | if set | What happens when the process ends. Without it, a crashed machine is restarted. |
| `config.killSignal` | `SIGTERM` \| `SIGINT` \| `SIGQUIT` \| `SIGHUP` \| `SIGUSR1` \| `SIGUSR2` \| `SIGWINCH` \| `SIGKILL` | if set | The signal sent before a machine is stopped or replaced. Default: the image's `STOPSIGNAL`, else `SIGTERM`. |
| `config.killTimeoutS` | integer | if set | Seconds between that signal and `SIGKILL`. 1 to 300. |
| `config.durableCheckpoint` | boolean | always | Agent machine: the whole state (memory and disk) is checkpointed and survives a host failure. default `false`. |
| `config.checkpointIntervalS` | integer | if set | 5 to 3600. |
| `config.console` | boolean | always | default `false`. |
| `config.command` | array of string | if set | Runs on a machine of its own, as an argument list. 1 to 64 items. |
| `config.diskIsCache` | boolean | if set |  |
| `config.readiness` | `port` \| `boot` | if set | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. |
| `config.exposePorts` | array of integer | if set | 0 to 8 items. |
| `config.egress` | object | if set | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `desiredState` | `requested` \| `scheduled` \| `starting` \| `running` \| `suspending` \| `suspended` \| `stopping` \| `stopped` \| `deleted` \| `failed` | always | What the platform wants the machine to be. |
| `observedState` | `requested` \| `scheduled` \| `starting` \| `running` \| `suspending` \| `suspended` \| `stopping` \| `stopped` \| `deleted` \| `failed` | always | What it is right now. |
| `host` | string | if set | Internal; not shown to a customer. |
| `privateIp` | string | if set | The machine's address on the private network. |
| `role` | `primary` \| `standby` | if set | `primary` or `standby`, for a redundant database only. |
| `region` | string | always | Where it runs. Fixed for the machine's lifetime. 2 to 12 characters. |
| `checkpointAt` | string (ISO 8601) | if set | Agent machines: when the last durable checkpoint was taken. |
| `zone` | string | if set | The availability zone, where the host reports one. |
| `diskUsedMb` | integer | if set | How full the disk is, an upper bound. 0 to 9007199254740991. |
| `diskTotalMb` | integer | if set | The disk's size. 0 to 9007199254740991. |
| `diskAt` | string (ISO 8601) | if set | When the disk numbers were reported. |
| `restoreChunksDone` | integer | if set | 0 to 9007199254740991. |
| `restoreChunksTotal` | integer | if set | 0 to 9007199254740991. |
| `restoreAt` | string (ISO 8601) | if set |  |
| `readyAt` | string (ISO 8601) | if set |  |
| `net` | object or null | if set |  |
| `liveness` | `listening` \| `not-listening` \| `no-signal` | if set |  |
| `livenessReason` | string | if set |  |
| `livenessSince` | string (ISO 8601) | if set |  |
| `livenessAt` | string (ISO 8601) | if set |  |
| `createError` | string | if set |  |
| `createErrorCode` | string | if set |  |
| `createBootLog` | string | if set |  |
| `createWarning` | string | if set |  |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `build-not-found` | `build:<id>` is not a build of your organization. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `conflict` | The request conflicts with the current state. |
| 409 | `volume-needs-single-machine` | An app with a volume runs exactly one machine. |
| 503 | `create-failed` | The host could not create the machine (image, start command or port). The sentence says which. |
| 503 | `no-capacity` | No host in the region has room for the machine right now; try again. |

## GET /v1/apps/:name/machines

The app's machines.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app, or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/machines" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of machines, each:

```json
[
  {
    "id": "<id>",
    "appName": "my-app",
    "config": {
      "image": "nginx:alpine",
      "vcpus": 1,
      "memoryMb": 512,
      "env": {
        "<key>": "<value>"
      },
      "internalPort": 3000,
      "suspendPolicy": {
        "mode": "suspend",
        "idleSeconds": 300
      },
      "durableCheckpoint": false,
      "console": false
    },
    "desiredState": "requested",
    "observedState": "requested",
    "region": "<region>",
    "createdAt": "2026-10-21T09:00:00Z"
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The machine's id. |
| `appName` | string | always | The app it belongs to. |
| `config` | object | always | What it runs: image, size, environment and the settings of a deploy request. |
| `config.image` | string | always | An OCI reference such as `nginx:alpine`, or `build:<id>` for a build of your organization. 1 to 512 characters. |
| `config.class` | `shared-cpu-1x` \| `shared-cpu-2x` \| `shared-cpu-4x` \| `shared-cpu-8x` \| `performance-1x` \| `performance-2x` \| `performance-4x` \| `performance-8x` | if set | A named size instead of `vcpus`; the two must not contradict each other. |
| `config.vcpus` | integer | always | Virtual CPUs. 1 to 16, default `1`. |
| `config.memoryMb` | integer | always | Memory in MB. 128 to 16384, default `512`. |
| `config.env` | object of string | always | Plain environment variables. Use secrets for credentials. |
| `config.diskMb` | integer | if set | The machine's disk in MB. Without it, the image's size plus headroom. 512 to 131072. |
| `config.volumeGb` | integer | if set | A volume of this size, attached to the machine. 1 to 500. |
| `config.start` | string | if set | The start command, run through `/bin/sh -c`. It replaces what detection chose or the image's `CMD`. 1 to 2000 characters. |
| `config.internalPort` | integer | always | The port the app listens on. 1 to 65535, default `3000`. |
| `config.suspendPolicy` | object | always | When the machine sleeps. Without it, a new app never sleeps; a deploy without it keeps the app's rule. |
| `config.healthCheck` | object | if set | An HTTP check a new machine must pass before it gets traffic. |
| `config.restart` | object | if set | What happens when the process ends. Without it, a crashed machine is restarted. |
| `config.killSignal` | `SIGTERM` \| `SIGINT` \| `SIGQUIT` \| `SIGHUP` \| `SIGUSR1` \| `SIGUSR2` \| `SIGWINCH` \| `SIGKILL` | if set | The signal sent before a machine is stopped or replaced. Default: the image's `STOPSIGNAL`, else `SIGTERM`. |
| `config.killTimeoutS` | integer | if set | Seconds between that signal and `SIGKILL`. 1 to 300. |
| `config.durableCheckpoint` | boolean | always | Agent machine: the whole state (memory and disk) is checkpointed and survives a host failure. default `false`. |
| `config.checkpointIntervalS` | integer | if set | 5 to 3600. |
| `config.console` | boolean | always | default `false`. |
| `config.command` | array of string | if set | Runs on a machine of its own, as an argument list. 1 to 64 items. |
| `config.diskIsCache` | boolean | if set |  |
| `config.readiness` | `port` \| `boot` | if set | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. |
| `config.exposePorts` | array of integer | if set | 0 to 8 items. |
| `config.egress` | object | if set | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `desiredState` | `requested` \| `scheduled` \| `starting` \| `running` \| `suspending` \| `suspended` \| `stopping` \| `stopped` \| `deleted` \| `failed` | always | What the platform wants the machine to be. |
| `observedState` | `requested` \| `scheduled` \| `starting` \| `running` \| `suspending` \| `suspended` \| `stopping` \| `stopped` \| `deleted` \| `failed` | always | What it is right now. |
| `host` | string | if set | Internal; not shown to a customer. |
| `privateIp` | string | if set | The machine's address on the private network. |
| `role` | `primary` \| `standby` | if set | `primary` or `standby`, for a redundant database only. |
| `region` | string | always | Where it runs. Fixed for the machine's lifetime. 2 to 12 characters. |
| `checkpointAt` | string (ISO 8601) | if set | Agent machines: when the last durable checkpoint was taken. |
| `zone` | string | if set | The availability zone, where the host reports one. |
| `diskUsedMb` | integer | if set | How full the disk is, an upper bound. 0 to 9007199254740991. |
| `diskTotalMb` | integer | if set | The disk's size. 0 to 9007199254740991. |
| `diskAt` | string (ISO 8601) | if set | When the disk numbers were reported. |
| `restoreChunksDone` | integer | if set | 0 to 9007199254740991. |
| `restoreChunksTotal` | integer | if set | 0 to 9007199254740991. |
| `restoreAt` | string (ISO 8601) | if set |  |
| `readyAt` | string (ISO 8601) | if set |  |
| `net` | object or null | if set |  |
| `liveness` | `listening` \| `not-listening` \| `no-signal` | if set |  |
| `livenessReason` | string | if set |  |
| `livenessSince` | string (ISO 8601) | if set |  |
| `livenessAt` | string (ISO 8601) | if set |  |
| `createError` | string | if set |  |
| `createErrorCode` | string | if set |  |
| `createBootLog` | string | if set |  |
| `createWarning` | string | if set |  |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/machines/:id

One machine.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The machine's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/machines/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the machine:

```json
{
  "id": "<id>",
  "appName": "my-app",
  "config": {
    "image": "nginx:alpine",
    "vcpus": 1,
    "memoryMb": 512,
    "env": {
      "<key>": "<value>"
    },
    "internalPort": 3000,
    "suspendPolicy": {
      "mode": "suspend",
      "idleSeconds": 300
    },
    "durableCheckpoint": false,
    "console": false
  },
  "desiredState": "requested",
  "observedState": "requested",
  "region": "<region>",
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The machine's id. |
| `appName` | string | always | The app it belongs to. |
| `config` | object | always | What it runs: image, size, environment and the settings of a deploy request. |
| `config.image` | string | always | An OCI reference such as `nginx:alpine`, or `build:<id>` for a build of your organization. 1 to 512 characters. |
| `config.class` | `shared-cpu-1x` \| `shared-cpu-2x` \| `shared-cpu-4x` \| `shared-cpu-8x` \| `performance-1x` \| `performance-2x` \| `performance-4x` \| `performance-8x` | if set | A named size instead of `vcpus`; the two must not contradict each other. |
| `config.vcpus` | integer | always | Virtual CPUs. 1 to 16, default `1`. |
| `config.memoryMb` | integer | always | Memory in MB. 128 to 16384, default `512`. |
| `config.env` | object of string | always | Plain environment variables. Use secrets for credentials. |
| `config.diskMb` | integer | if set | The machine's disk in MB. Without it, the image's size plus headroom. 512 to 131072. |
| `config.volumeGb` | integer | if set | A volume of this size, attached to the machine. 1 to 500. |
| `config.start` | string | if set | The start command, run through `/bin/sh -c`. It replaces what detection chose or the image's `CMD`. 1 to 2000 characters. |
| `config.internalPort` | integer | always | The port the app listens on. 1 to 65535, default `3000`. |
| `config.suspendPolicy` | object | always | When the machine sleeps. Without it, a new app never sleeps; a deploy without it keeps the app's rule. |
| `config.healthCheck` | object | if set | An HTTP check a new machine must pass before it gets traffic. |
| `config.restart` | object | if set | What happens when the process ends. Without it, a crashed machine is restarted. |
| `config.killSignal` | `SIGTERM` \| `SIGINT` \| `SIGQUIT` \| `SIGHUP` \| `SIGUSR1` \| `SIGUSR2` \| `SIGWINCH` \| `SIGKILL` | if set | The signal sent before a machine is stopped or replaced. Default: the image's `STOPSIGNAL`, else `SIGTERM`. |
| `config.killTimeoutS` | integer | if set | Seconds between that signal and `SIGKILL`. 1 to 300. |
| `config.durableCheckpoint` | boolean | always | Agent machine: the whole state (memory and disk) is checkpointed and survives a host failure. default `false`. |
| `config.checkpointIntervalS` | integer | if set | 5 to 3600. |
| `config.console` | boolean | always | default `false`. |
| `config.command` | array of string | if set | Runs on a machine of its own, as an argument list. 1 to 64 items. |
| `config.diskIsCache` | boolean | if set |  |
| `config.readiness` | `port` \| `boot` | if set | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. |
| `config.exposePorts` | array of integer | if set | 0 to 8 items. |
| `config.egress` | object | if set | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `desiredState` | `requested` \| `scheduled` \| `starting` \| `running` \| `suspending` \| `suspended` \| `stopping` \| `stopped` \| `deleted` \| `failed` | always | What the platform wants the machine to be. |
| `observedState` | `requested` \| `scheduled` \| `starting` \| `running` \| `suspending` \| `suspended` \| `stopping` \| `stopped` \| `deleted` \| `failed` | always | What it is right now. |
| `host` | string | if set | Internal; not shown to a customer. |
| `privateIp` | string | if set | The machine's address on the private network. |
| `role` | `primary` \| `standby` | if set | `primary` or `standby`, for a redundant database only. |
| `region` | string | always | Where it runs. Fixed for the machine's lifetime. 2 to 12 characters. |
| `checkpointAt` | string (ISO 8601) | if set | Agent machines: when the last durable checkpoint was taken. |
| `zone` | string | if set | The availability zone, where the host reports one. |
| `diskUsedMb` | integer | if set | How full the disk is, an upper bound. 0 to 9007199254740991. |
| `diskTotalMb` | integer | if set | The disk's size. 0 to 9007199254740991. |
| `diskAt` | string (ISO 8601) | if set | When the disk numbers were reported. |
| `restoreChunksDone` | integer | if set | 0 to 9007199254740991. |
| `restoreChunksTotal` | integer | if set | 0 to 9007199254740991. |
| `restoreAt` | string (ISO 8601) | if set |  |
| `readyAt` | string (ISO 8601) | if set |  |
| `net` | object or null | if set |  |
| `liveness` | `listening` \| `not-listening` \| `no-signal` | if set |  |
| `livenessReason` | string | if set |  |
| `livenessSince` | string (ISO 8601) | if set |  |
| `livenessAt` | string (ISO 8601) | if set |  |
| `createError` | string | if set |  |
| `createErrorCode` | string | if set |  |
| `createBootLog` | string | if set |  |
| `createWarning` | string | if set |  |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/machines/:id/wait

Holds the request until the machine reaches a state (`?state=`), at most `?timeout=` seconds; `408` when it runs out.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Query parameters

| Name | Description |
| --- | --- |
| `state` | The state to wait for, for example `running` or `stopped`. |
| `timeout` | Seconds to hold the request, at most 60. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/machines/<id>/wait" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the machine, once it is in the state:

```json
{
  "id": "<id>",
  "appName": "my-app",
  "config": {
    "image": "nginx:alpine",
    "vcpus": 1,
    "memoryMb": 512,
    "env": {
      "<key>": "<value>"
    },
    "internalPort": 3000,
    "suspendPolicy": {
      "mode": "suspend",
      "idleSeconds": 300
    },
    "durableCheckpoint": false,
    "console": false
  },
  "desiredState": "requested",
  "observedState": "requested",
  "region": "<region>",
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The machine's id. |
| `appName` | string | always | The app it belongs to. |
| `config` | object | always | What it runs: image, size, environment and the settings of a deploy request. |
| `config.image` | string | always | An OCI reference such as `nginx:alpine`, or `build:<id>` for a build of your organization. 1 to 512 characters. |
| `config.class` | `shared-cpu-1x` \| `shared-cpu-2x` \| `shared-cpu-4x` \| `shared-cpu-8x` \| `performance-1x` \| `performance-2x` \| `performance-4x` \| `performance-8x` | if set | A named size instead of `vcpus`; the two must not contradict each other. |
| `config.vcpus` | integer | always | Virtual CPUs. 1 to 16, default `1`. |
| `config.memoryMb` | integer | always | Memory in MB. 128 to 16384, default `512`. |
| `config.env` | object of string | always | Plain environment variables. Use secrets for credentials. |
| `config.diskMb` | integer | if set | The machine's disk in MB. Without it, the image's size plus headroom. 512 to 131072. |
| `config.volumeGb` | integer | if set | A volume of this size, attached to the machine. 1 to 500. |
| `config.start` | string | if set | The start command, run through `/bin/sh -c`. It replaces what detection chose or the image's `CMD`. 1 to 2000 characters. |
| `config.internalPort` | integer | always | The port the app listens on. 1 to 65535, default `3000`. |
| `config.suspendPolicy` | object | always | When the machine sleeps. Without it, a new app never sleeps; a deploy without it keeps the app's rule. |
| `config.healthCheck` | object | if set | An HTTP check a new machine must pass before it gets traffic. |
| `config.restart` | object | if set | What happens when the process ends. Without it, a crashed machine is restarted. |
| `config.killSignal` | `SIGTERM` \| `SIGINT` \| `SIGQUIT` \| `SIGHUP` \| `SIGUSR1` \| `SIGUSR2` \| `SIGWINCH` \| `SIGKILL` | if set | The signal sent before a machine is stopped or replaced. Default: the image's `STOPSIGNAL`, else `SIGTERM`. |
| `config.killTimeoutS` | integer | if set | Seconds between that signal and `SIGKILL`. 1 to 300. |
| `config.durableCheckpoint` | boolean | always | Agent machine: the whole state (memory and disk) is checkpointed and survives a host failure. default `false`. |
| `config.checkpointIntervalS` | integer | if set | 5 to 3600. |
| `config.console` | boolean | always | default `false`. |
| `config.command` | array of string | if set | Runs on a machine of its own, as an argument list. 1 to 64 items. |
| `config.diskIsCache` | boolean | if set |  |
| `config.readiness` | `port` \| `boot` | if set | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. |
| `config.exposePorts` | array of integer | if set | 0 to 8 items. |
| `config.egress` | object | if set | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `desiredState` | `requested` \| `scheduled` \| `starting` \| `running` \| `suspending` \| `suspended` \| `stopping` \| `stopped` \| `deleted` \| `failed` | always | What the platform wants the machine to be. |
| `observedState` | `requested` \| `scheduled` \| `starting` \| `running` \| `suspending` \| `suspended` \| `stopping` \| `stopped` \| `deleted` \| `failed` | always | What it is right now. |
| `host` | string | if set | Internal; not shown to a customer. |
| `privateIp` | string | if set | The machine's address on the private network. |
| `role` | `primary` \| `standby` | if set | `primary` or `standby`, for a redundant database only. |
| `region` | string | always | Where it runs. Fixed for the machine's lifetime. 2 to 12 characters. |
| `checkpointAt` | string (ISO 8601) | if set | Agent machines: when the last durable checkpoint was taken. |
| `zone` | string | if set | The availability zone, where the host reports one. |
| `diskUsedMb` | integer | if set | How full the disk is, an upper bound. 0 to 9007199254740991. |
| `diskTotalMb` | integer | if set | The disk's size. 0 to 9007199254740991. |
| `diskAt` | string (ISO 8601) | if set | When the disk numbers were reported. |
| `restoreChunksDone` | integer | if set | 0 to 9007199254740991. |
| `restoreChunksTotal` | integer | if set | 0 to 9007199254740991. |
| `restoreAt` | string (ISO 8601) | if set |  |
| `readyAt` | string (ISO 8601) | if set |  |
| `net` | object or null | if set |  |
| `liveness` | `listening` \| `not-listening` \| `no-signal` | if set |  |
| `livenessReason` | string | if set |  |
| `livenessSince` | string (ISO 8601) | if set |  |
| `livenessAt` | string (ISO 8601) | if set |  |
| `createError` | string | if set |  |
| `createErrorCode` | string | if set |  |
| `createBootLog` | string | if set |  |
| `createWarning` | string | if set |  |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 408 | `wait-timeout` | The wait ran out before the machine reached the state; ask again. |
| 410 | `gone` | The object existed and is gone. |

## POST /v1/machines/:id/:action

Acts on a machine: `start`, `stop`, `suspend` or `destroy`.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |
| `action` | `start`, `stop`, `suspend` or `destroy`. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/machines/<id>/<action>" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Response

`200` with the machine after the action:

```json
{
  "id": "<id>",
  "appName": "my-app",
  "config": {
    "image": "nginx:alpine",
    "vcpus": 1,
    "memoryMb": 512,
    "env": {
      "<key>": "<value>"
    },
    "internalPort": 3000,
    "suspendPolicy": {
      "mode": "suspend",
      "idleSeconds": 300
    },
    "durableCheckpoint": false,
    "console": false
  },
  "desiredState": "requested",
  "observedState": "requested",
  "region": "<region>",
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The machine's id. |
| `appName` | string | always | The app it belongs to. |
| `config` | object | always | What it runs: image, size, environment and the settings of a deploy request. |
| `config.image` | string | always | An OCI reference such as `nginx:alpine`, or `build:<id>` for a build of your organization. 1 to 512 characters. |
| `config.class` | `shared-cpu-1x` \| `shared-cpu-2x` \| `shared-cpu-4x` \| `shared-cpu-8x` \| `performance-1x` \| `performance-2x` \| `performance-4x` \| `performance-8x` | if set | A named size instead of `vcpus`; the two must not contradict each other. |
| `config.vcpus` | integer | always | Virtual CPUs. 1 to 16, default `1`. |
| `config.memoryMb` | integer | always | Memory in MB. 128 to 16384, default `512`. |
| `config.env` | object of string | always | Plain environment variables. Use secrets for credentials. |
| `config.diskMb` | integer | if set | The machine's disk in MB. Without it, the image's size plus headroom. 512 to 131072. |
| `config.volumeGb` | integer | if set | A volume of this size, attached to the machine. 1 to 500. |
| `config.start` | string | if set | The start command, run through `/bin/sh -c`. It replaces what detection chose or the image's `CMD`. 1 to 2000 characters. |
| `config.internalPort` | integer | always | The port the app listens on. 1 to 65535, default `3000`. |
| `config.suspendPolicy` | object | always | When the machine sleeps. Without it, a new app never sleeps; a deploy without it keeps the app's rule. |
| `config.healthCheck` | object | if set | An HTTP check a new machine must pass before it gets traffic. |
| `config.restart` | object | if set | What happens when the process ends. Without it, a crashed machine is restarted. |
| `config.killSignal` | `SIGTERM` \| `SIGINT` \| `SIGQUIT` \| `SIGHUP` \| `SIGUSR1` \| `SIGUSR2` \| `SIGWINCH` \| `SIGKILL` | if set | The signal sent before a machine is stopped or replaced. Default: the image's `STOPSIGNAL`, else `SIGTERM`. |
| `config.killTimeoutS` | integer | if set | Seconds between that signal and `SIGKILL`. 1 to 300. |
| `config.durableCheckpoint` | boolean | always | Agent machine: the whole state (memory and disk) is checkpointed and survives a host failure. default `false`. |
| `config.checkpointIntervalS` | integer | if set | 5 to 3600. |
| `config.console` | boolean | always | default `false`. |
| `config.command` | array of string | if set | Runs on a machine of its own, as an argument list. 1 to 64 items. |
| `config.diskIsCache` | boolean | if set |  |
| `config.readiness` | `port` \| `boot` | if set | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. |
| `config.exposePorts` | array of integer | if set | 0 to 8 items. |
| `config.egress` | object | if set | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `desiredState` | `requested` \| `scheduled` \| `starting` \| `running` \| `suspending` \| `suspended` \| `stopping` \| `stopped` \| `deleted` \| `failed` | always | What the platform wants the machine to be. |
| `observedState` | `requested` \| `scheduled` \| `starting` \| `running` \| `suspending` \| `suspended` \| `stopping` \| `stopped` \| `deleted` \| `failed` | always | What it is right now. |
| `host` | string | if set | Internal; not shown to a customer. |
| `privateIp` | string | if set | The machine's address on the private network. |
| `role` | `primary` \| `standby` | if set | `primary` or `standby`, for a redundant database only. |
| `region` | string | always | Where it runs. Fixed for the machine's lifetime. 2 to 12 characters. |
| `checkpointAt` | string (ISO 8601) | if set | Agent machines: when the last durable checkpoint was taken. |
| `zone` | string | if set | The availability zone, where the host reports one. |
| `diskUsedMb` | integer | if set | How full the disk is, an upper bound. 0 to 9007199254740991. |
| `diskTotalMb` | integer | if set | The disk's size. 0 to 9007199254740991. |
| `diskAt` | string (ISO 8601) | if set | When the disk numbers were reported. |
| `restoreChunksDone` | integer | if set | 0 to 9007199254740991. |
| `restoreChunksTotal` | integer | if set | 0 to 9007199254740991. |
| `restoreAt` | string (ISO 8601) | if set |  |
| `readyAt` | string (ISO 8601) | if set |  |
| `net` | object or null | if set |  |
| `liveness` | `listening` \| `not-listening` \| `no-signal` | if set |  |
| `livenessReason` | string | if set |  |
| `livenessSince` | string (ISO 8601) | if set |  |
| `livenessAt` | string (ISO 8601) | if set |  |
| `createError` | string | if set |  |
| `createErrorCode` | string | if set |  |
| `createBootLog` | string | if set |  |
| `createWarning` | string | if set |  |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `machine-busy` | Another operation on the machine is in progress; try again. |
| 503 | `create-failed` | The host could not create the machine (image, start command or port). The sentence says which. |
| 503 | `guest-exited` | The machine's process ended during the start. |
| 503 | `host-refused` | The host refused the action. |
| 503 | `host-unreachable` | The host did not answer. |
| 503 | `no-capacity` | No host in the region has room for the machine right now; try again. |
| 503 | `port-timeout` | The machine did not answer on its port in time. |
| 503 | `start-interrupted` | The start was interrupted on the host. |

## POST /v1/machines/:id/migrate

Moves the machine to another host.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/machines/<id>/migrate" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object and the fields of the object the handler builds.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `conflict` | The request conflicts with the current state. |
| 409 | `create-failed` | The host could not create the machine (image, start command or port). The sentence says which. |
| 409 | `ephemeral` |  |
| 503 | `no-capacity` | No host in the region has room for the machine right now; try again. |

## GET /v1/apps/:name/logs

The console output of the app's machines, with a cursor per machine for the next call.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app, or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Query parameters

| Name | Description |
| --- | --- |
| `machine` | Only this machine. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/logs" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/machines/:id/checkpoints

Takes a named snapshot of the machine: its disk, and with `memory: true` its running memory too.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Request body

JSON, the shape `CreateCheckpointRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | required | A name for the snapshot: letters, digits, `.`, `-` and `_`, starting with a letter or digit. `auto-` is reserved. |
| `comment` | string | optional | A note kept with the snapshot. at most 500 characters. |
| `memory` | boolean | optional | `true` snapshots the running memory as well, so a restore resumes the very processes. default `false`. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/machines/<id>/checkpoints" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"before-migration"}'
```

### Response

`201` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/machines/:id/checkpoints

The machine's named snapshots. Add `?auto=1` to include the automatic ones.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Query parameters

| Name | Description |
| --- | --- |
| `includeAuto` |  |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/machines/<id>/checkpoints" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/machines/:id/checkpoints/:label

Forgets a snapshot.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |
| `label` | The snapshot's label. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/machines/<id>/checkpoints/<label>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/machines/:id/checkpoints/:label/restore

Brings the machine back to that snapshot. With `keepCurrent: true` (the default) the current state is saved first.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |
| `label` | The snapshot's label. |

### Request body

JSON, the shape `RestoreCheckpointRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `keepCurrent` | boolean | optional | Save the current state as a snapshot before restoring (default `true`). default `true`. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/machines/<id>/checkpoints/<label>/restore" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keepCurrent":true}'
```

### Response

`200` with a JSON object carrying `machineId`, `restored`, `manifest`, `memory`, `savedAs`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/machines/:id/files

Reads one file of the machine (`?path=`), as raw bytes.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/machines/<id>/files" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 502 | `transport` |  |

## PUT /v1/machines/:id/files

Writes one file of the machine (`?path=`); the body is the file's bytes.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Query parameters

| Name | Description |
| --- | --- |
| `mode` | The file mode, default `0644`. |
| `mkdirs` | `1` creates missing directories. |

### Request body

The raw bytes of the file.

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/machines/<id>/files" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @hello.txt
```

### Response

`200` with a JSON object carrying `path`, `bytes`, `sha256`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 413 | `too-large` | The body is larger than the route accepts. |
| 502 | `transport` |  |

## GET /v1/machines/:id/files/list

Lists a directory of the machine (`?path=`).

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/machines/<id>/files/list" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `path`, `entries`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 502 | `transport` |  |

## GET /v1/machines/:id/screenshot

A screenshot of the machine's desktop, for a machine that has one.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Query parameters

| Name | Description |
| --- | --- |
| `display` |  |

### Request body

JSON, the shape `ExecScreenshot` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `display` | string | optional | default `":0"`. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/machines/<id>/screenshot" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"display":"<display>"}'
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/machines/:id/exec

Opens a shell session over a WebSocket. This is what `ry exec` and `ry ssh` use; it is not a plain JSON call.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/machines/<id>/exec" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

A JSON body on success.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 426 | `upgrade-required` | The route needs a WebSocket upgrade; use the CLI. |

## GET /v1/machines/:id/exec-sessions

The shell sessions open on the machine.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | How many entries, at most. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/machines/<id>/exec-sessions" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/computers/ -->

# Computers

> Watch or take over a computer's desktop, and see who had control.

A computer is an app with one machine that runs the computer image, a home volume mounted at `/data`, and a secret `COMPUTER_VIEW_KEY` that the viewer routes below use. The console and `ry computer create` build one in that order: the app (with `"computer": true`, so the organization's computer limit is judged first), the home volume, the key, the deploy. There is no separate computer object in the API: read it through [Apps](https://docs.rytiv.com/reference/api/apps.md) and [Machines](https://docs.rytiv.com/reference/api/machines.md), and run commands in it with `ry exec` or the MCP tool `computer_exec`.

See the guide [Computers](https://docs.rytiv.com/computers.md) for sizes, idle shutdown and how to connect a coding agent.

## Endpoints

- [`POST /v1/machines/:id/viewer`](#post-v1machinesidviewer): A link to watch the computer's desktop (`mode: "view"`), or to take keyboard and mouse (`mode: "control"`). One control holder per machine
- [`POST /v1/machines/:id/control/release`](#post-v1machinesidcontrolrelease): Ends the control lease
- [`GET /v1/machines/:id/control-audit`](#get-v1machinesidcontrol-audit): Who got which link on this machine, from when to when, and how control ended
- [`GET /v1/apps/:name/control-audit`](#get-v1appsnamecontrol-audit): The same audit across all machines the app had

## POST /v1/machines/:id/viewer

A link to watch the computer's desktop (`mode: "view"`), or to take keyboard and mouse (`mode: "control"`). One control holder per machine.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Request body

JSON, the shape `ViewerRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `view` \| `control` | required | `view` to watch, `control` to take keyboard and mouse. |
| `ttlS` | integer | optional | How long the link opens a connection, in seconds. 60 to 3600, default `900`. |
| `who` | string | optional | Who the link is for; shown in the audit. 1 to 64 characters. |
| `force` | boolean | optional | Take control from the current holder; their connection ends. default `false`. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/machines/<id>/viewer" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"view"}'
```

### Response

A JSON body on success.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `computer-control-missing` | The machine runs a computer image from before control leases; deploy it again. |
| 409 | `control-busy` | Another change of control is in progress; try again after `Retry-After`. |
| 409 | `control-held` | Somebody else holds control; the body names `heldBy`, `until` and `leaseId`. Use `force` to take it. |
| 409 | `guest-agent-absent` | The machine has no guest channel; it was created before shell sessions existed. Deploy it again. |
| 409 | `machine-stopped` | The machine is stopped; start it first. |
| 409 | `managed-service` | A managed database; its machine is not opened to a shell. |
| 409 | `not-a-computer` | The machine is not a computer (it has no `COMPUTER_VIEW_KEY`), or it is a console or job machine. |
| 409 | `several-machines` | Control needs exactly one machine; the app has several. |
| 409 | `view-key-too-short` | The computer's key is too short; the image would refuse to start with it. |
| 429 | `rate-limited` | Too many requests; wait for `Retry-After` and try again. |
| 502 | `guest-failed` | The control tool in the machine ran and failed. |
| 503 | `guest-channel-off` | The guest channel is switched off on the machine's host. |
| 503 | `guest-unreachable` | The guest did not answer; try again after `Retry-After`. |
| 503 | `not-placed` | The machine has no host yet. |
| 503 | `resource-check-failed` | Could not tell whether the machine backs a managed database; try again. |
| 503 | `view-key-unreadable` | The computer's key cannot be decrypted right now. |

## POST /v1/machines/:id/control/release

Ends the control lease.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/machines/<id>/control/release" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

A JSON body on success.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `machine-stopped` | The machine is stopped; start it first. |
| 409 | `not-a-computer` | The machine is not a computer (it has no `COMPUTER_VIEW_KEY`), or it is a console or job machine. |
| 502 | `guest-failed` | The control tool in the machine ran and failed. |
| 503 | `guest-unreachable` | The guest did not answer; try again after `Retry-After`. |

## GET /v1/machines/:id/control-audit

Who got which link on this machine, from when to when, and how control ended.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/machines/<id>/control-audit" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/apps/:name/control-audit

The same audit across all machines the app had.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/control-audit" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/sandboxes/ -->

# Sandboxes

> Short-lived machines with a deadline: create from a template, run commands, read and write files, extend, end.

A sandbox is a machine with a deadline. It boots the image of a template you already have (`app:<name>` or `build:<id>`), runs commands, holds files, and is removed at its deadline together with everything on its disk. Each sandbox has an id like `sbx-1a2b3c4d5e6f` and its own address `https://<id>.rytiv.app`. See [Sandboxes](https://docs.rytiv.com/sandboxes.md) for the full description.

## Endpoints

- [`POST /v1/sandboxes`](#post-v1sandboxes): Creates a sandbox from a template and answers when its machine runs
- [`GET /v1/sandboxes`](#get-v1sandboxes): Running sandboxes, newest first. `?state=all` adds the ones that ended in the last 14 days
- [`GET /v1/sandboxes/:id`](#get-v1sandboxesid): One sandbox
- [`DELETE /v1/sandboxes/:id`](#delete-v1sandboxesid): Ends the sandbox now. Its machine and disk are gone
- [`POST /v1/sandboxes/:id/timeout`](#post-v1sandboxesidtimeout): Sets a new deadline: now plus `ttlSeconds`
- [`POST /v1/sandboxes/:id/exec`](#post-v1sandboxesidexec): Runs one command in the sandbox and answers with its exit code and output
- [`GET /v1/sandboxes/:id/files`](#get-v1sandboxesidfiles): Reads one file (`?path=`), as raw bytes
- [`PUT /v1/sandboxes/:id/files`](#put-v1sandboxesidfiles): Writes one file (`?path=`, optional `mode` and `mkdirs=1`); the body is the file's bytes
- [`GET /v1/sandboxes/:id/files/list`](#get-v1sandboxesidfileslist): Lists a directory (`?path=`)

## POST /v1/sandboxes

Creates a sandbox from a template and answers when its machine runs.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Request body

JSON, the shape `CreateSandboxRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `template` | string | required | `app:<name>` boots the image an app of yours runs now; `build:<id>` a build of yours. |
| `ttlSeconds` | integer | optional | Lifetime from now, in seconds. 10 to 86400, default `300`. |
| `vcpus` | integer | optional | Virtual CPUs. 1 to 16. |
| `memoryMb` | integer | optional | Memory in MB. 128 to 16384. |
| `diskMb` | integer | optional | The machine's disk in MB. Without it, the image's size plus headroom. 512 to 131072. |
| `env` | object of string | optional | Plain environment variables. Use secrets for credentials. |
| `ports` | array of integer | optional | More ports to reach from outside, each at `https://<port>-<id>.rytiv.app`. 0 to 8 items. |
| `internalPort` | integer | optional | The port the app listens on. 1 to 65535. |
| `readiness` | `boot` \| `port` | optional | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. default `"boot"`. |
| `access` | `signed` \| `public` | optional | `signed`: the sandbox's URLs need the access token from the create answer. `public`: anyone with the URL. default `"signed"`. |
| `idleSeconds` | integer | optional | Seconds without activity before the sandbox sleeps. 10 to 86400. |
| `metadata` | object of string | optional | Key/value pairs for your own bookkeeping. |
| `egress` | object | optional | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `egress.mode` | `allow-all` \| `deny-all` \| `allowlist` | required | `view` to watch, `control` to take keyboard and mouse. |
| `egress.domains` | array of string | optional | 0 to 100 items. |
| `egress.cidrs` | array of string | optional | 0 to 10 items. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/sandboxes" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template":"app:my-app"}'
```

### Response

`201` with the sandbox:

```json
{
  "id": "<id>",
  "template": "app:my-app",
  "state": "starting",
  "createdAt": "2026-10-21T09:00:00Z",
  "expiresAt": "2026-10-21T09:00:00Z",
  "endedAt": "2026-10-21T09:00:00Z",
  "endReason": "expired",
  "machineId": "<machineId>",
  "vcpus": -9007199254740991,
  "memoryMb": -9007199254740991,
  "readiness": "boot",
  "access": "signed",
  "url": "<url>",
  "ports": [
    {
      "port": -9007199254740991,
      "url": "<url>"
    }
  ],
  "metadata": {
    "<key>": "<value>"
  },
  "egress": {
    "mode": "allow-all",
    "domains": [
      "www.example.com"
    ],
    "cidrs": [
      "<cidr>"
    ]
  },
  "createMs": -9007199254740991
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always |  |
| `template` | string | always | `app:<name>` boots the image an app of yours runs now; `build:<id>` a build of yours. |
| `state` | `starting` \| `running` \| `sleeping` \| `ended` | always |  |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `expiresAt` | string (ISO 8601) | always | When the copy is deleted (a moment). Not together with `ttlSeconds`. |
| `endedAt` | string (ISO 8601) or null | always |  |
| `endReason` | `expired` \| `killed` \| `failed` \| `app-deleted` or null | always |  |
| `machineId` | string or null | always |  |
| `vcpus` | integer | always | Virtual CPUs. -9007199254740991 to 9007199254740991. |
| `memoryMb` | integer | always | Memory in MB. -9007199254740991 to 9007199254740991. |
| `readiness` | `boot` \| `port` | always | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. |
| `access` | `signed` \| `public` | always | `signed`: the sandbox's URLs need the access token from the create answer. `public`: anyone with the URL. |
| `url` | string | always |  |
| `ports` | array of object | always | More ports to reach from outside, each at `https://<port>-<id>.rytiv.app`. |
| `metadata` | object of string | always | Key/value pairs for your own bookkeeping. |
| `egress` | object | always | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `egress.mode` | `allow-all` \| `deny-all` \| `allowlist` | always | `view` to watch, `control` to take keyboard and mouse. |
| `egress.domains` | array of string | always |  |
| `egress.cidrs` | array of string | always |  |
| `createMs` | integer | always | -9007199254740991 to 9007199254740991. |
| `accessToken` | object | if set | With `access: "signed"`: the token the sandbox's URLs need, the header to send it in, and its expiry. |
| `accessToken.token` | string | always |  |
| `accessToken.expiresAt` | string (ISO 8601) | always | When the copy is deleted (a moment). Not together with `ttlSeconds`. |
| `accessToken.header` | string | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `build-not-found` | `build:<id>` is not a build of your organization. |
| 404 | `template-not-found` | No such app or build in your organization. |
| 409 | `conflict` | The request conflicts with the current state. |
| 409 | `template-not-runnable` | The build is a static site, or the app runs no machine. |
| 429 | `too-many-sandboxes` | The organization's sandbox limit is reached. |
| 503 | `no-capacity` | No host in the region has room for the machine right now; try again. |

## GET /v1/sandboxes

Running sandboxes, newest first. `?state=all` adds the ones that ended in the last 14 days.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Query parameters

| Name | Description |
| --- | --- |
| `state` | `all` adds the sandboxes that ended in the last 14 days. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/sandboxes" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of sandboxes, each:

```json
[
  {
    "id": "<id>",
    "template": "app:my-app",
    "state": "starting",
    "createdAt": "2026-10-21T09:00:00Z",
    "expiresAt": "2026-10-21T09:00:00Z",
    "endedAt": "2026-10-21T09:00:00Z",
    "endReason": "expired",
    "machineId": "<machineId>",
    "vcpus": -9007199254740991,
    "memoryMb": -9007199254740991,
    "readiness": "boot",
    "access": "signed",
    "url": "<url>",
    "ports": [
      {
        "port": -9007199254740991,
        "url": "<url>"
      }
    ],
    "metadata": {
      "<key>": "<value>"
    },
    "egress": {
      "mode": "allow-all",
      "domains": [
        "www.example.com"
      ],
      "cidrs": [
        "<cidr>"
      ]
    }
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | `sbx-` and 12 hex digits. |
| `template` | string | always | `app:<name>` boots the image an app of yours runs now; `build:<id>` a build of yours. |
| `state` | `starting` \| `running` \| `sleeping` \| `ended` | always | `starting`, `running`, `sleeping` or `ended`. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `expiresAt` | string (ISO 8601) | always | The deadline. |
| `endedAt` | string (ISO 8601) or null | always | When it ended. |
| `endReason` | `expired` \| `killed` \| `failed` \| `app-deleted` or null | always | `expired`, `killed`, `failed` or `app-deleted`. |
| `machineId` | string or null | always | The machine behind it. |
| `vcpus` | integer | always | Virtual CPUs. -9007199254740991 to 9007199254740991. |
| `memoryMb` | integer | always | Memory in MB. -9007199254740991 to 9007199254740991. |
| `readiness` | `boot` \| `port` | always | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. |
| `access` | `signed` \| `public` | always | `signed`: the sandbox's URLs need the access token from the create answer. `public`: anyone with the URL. |
| `url` | string | always | `https://<id>.rytiv.app`. |
| `ports` | array of object | always | More ports to reach from outside, each at `https://<port>-<id>.rytiv.app`. |
| `metadata` | object of string | always | Key/value pairs for your own bookkeeping. |
| `egress` | object | always | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `egress.mode` | `allow-all` \| `deny-all` \| `allowlist` | always | `view` to watch, `control` to take keyboard and mouse. |
| `egress.domains` | array of string | always |  |
| `egress.cidrs` | array of string | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/sandboxes/:id

One sandbox.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The sandbox's id (`sbx-...`). |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/sandboxes/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the sandbox:

```json
{
  "id": "<id>",
  "template": "app:my-app",
  "state": "starting",
  "createdAt": "2026-10-21T09:00:00Z",
  "expiresAt": "2026-10-21T09:00:00Z",
  "endedAt": "2026-10-21T09:00:00Z",
  "endReason": "expired",
  "machineId": "<machineId>",
  "vcpus": -9007199254740991,
  "memoryMb": -9007199254740991,
  "readiness": "boot",
  "access": "signed",
  "url": "<url>",
  "ports": [
    {
      "port": -9007199254740991,
      "url": "<url>"
    }
  ],
  "metadata": {
    "<key>": "<value>"
  },
  "egress": {
    "mode": "allow-all",
    "domains": [
      "www.example.com"
    ],
    "cidrs": [
      "<cidr>"
    ]
  }
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | `sbx-` and 12 hex digits. |
| `template` | string | always | `app:<name>` boots the image an app of yours runs now; `build:<id>` a build of yours. |
| `state` | `starting` \| `running` \| `sleeping` \| `ended` | always | `starting`, `running`, `sleeping` or `ended`. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `expiresAt` | string (ISO 8601) | always | The deadline. |
| `endedAt` | string (ISO 8601) or null | always | When it ended. |
| `endReason` | `expired` \| `killed` \| `failed` \| `app-deleted` or null | always | `expired`, `killed`, `failed` or `app-deleted`. |
| `machineId` | string or null | always | The machine behind it. |
| `vcpus` | integer | always | Virtual CPUs. -9007199254740991 to 9007199254740991. |
| `memoryMb` | integer | always | Memory in MB. -9007199254740991 to 9007199254740991. |
| `readiness` | `boot` \| `port` | always | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. |
| `access` | `signed` \| `public` | always | `signed`: the sandbox's URLs need the access token from the create answer. `public`: anyone with the URL. |
| `url` | string | always | `https://<id>.rytiv.app`. |
| `ports` | array of object | always | More ports to reach from outside, each at `https://<port>-<id>.rytiv.app`. |
| `metadata` | object of string | always | Key/value pairs for your own bookkeeping. |
| `egress` | object | always | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `egress.mode` | `allow-all` \| `deny-all` \| `allowlist` | always | `view` to watch, `control` to take keyboard and mouse. |
| `egress.domains` | array of string | always |  |
| `egress.cidrs` | array of string | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 404 | `sandbox-not-found` | No such sandbox in your organization. |

## DELETE /v1/sandboxes/:id

Ends the sandbox now. Its machine and disk are gone.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The sandbox's id (`sbx-...`). |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/sandboxes/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`202` with a JSON object carrying `id`, `state`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 404 | `sandbox-not-found` | No such sandbox in your organization. |
| 409 | `sandbox-ended` | The sandbox has ended. |

## POST /v1/sandboxes/:id/timeout

Sets a new deadline: now plus `ttlSeconds`.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The sandbox's id. |

### Request body

JSON, the shape `SetSandboxTimeoutRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ttlSeconds` | integer | required | Lifetime from now, in seconds. 10 to 86400. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/sandboxes/<id>/timeout" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":10}'
```

### Response

`200` with the sandbox with its new deadline:

```json
{
  "id": "<id>",
  "template": "app:my-app",
  "state": "starting",
  "createdAt": "2026-10-21T09:00:00Z",
  "expiresAt": "2026-10-21T09:00:00Z",
  "endedAt": "2026-10-21T09:00:00Z",
  "endReason": "expired",
  "machineId": "<machineId>",
  "vcpus": -9007199254740991,
  "memoryMb": -9007199254740991,
  "readiness": "boot",
  "access": "signed",
  "url": "<url>",
  "ports": [
    {
      "port": -9007199254740991,
      "url": "<url>"
    }
  ],
  "metadata": {
    "<key>": "<value>"
  },
  "egress": {
    "mode": "allow-all",
    "domains": [
      "www.example.com"
    ],
    "cidrs": [
      "<cidr>"
    ]
  }
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | `sbx-` and 12 hex digits. |
| `template` | string | always | `app:<name>` boots the image an app of yours runs now; `build:<id>` a build of yours. |
| `state` | `starting` \| `running` \| `sleeping` \| `ended` | always | `starting`, `running`, `sleeping` or `ended`. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `expiresAt` | string (ISO 8601) | always | The deadline. |
| `endedAt` | string (ISO 8601) or null | always | When it ended. |
| `endReason` | `expired` \| `killed` \| `failed` \| `app-deleted` or null | always | `expired`, `killed`, `failed` or `app-deleted`. |
| `machineId` | string or null | always | The machine behind it. |
| `vcpus` | integer | always | Virtual CPUs. -9007199254740991 to 9007199254740991. |
| `memoryMb` | integer | always | Memory in MB. -9007199254740991 to 9007199254740991. |
| `readiness` | `boot` \| `port` | always | `boot`: ready when the machine boots. `port`: ready when `internalPort` answers. |
| `access` | `signed` \| `public` | always | `signed`: the sandbox's URLs need the access token from the create answer. `public`: anyone with the URL. |
| `url` | string | always | `https://<id>.rytiv.app`. |
| `ports` | array of object | always | More ports to reach from outside, each at `https://<port>-<id>.rytiv.app`. |
| `metadata` | object of string | always | Key/value pairs for your own bookkeeping. |
| `egress` | object | always | Outbound network: `allow-all`, `deny-all`, or `allowlist` with `domains` and `cidrs`. |
| `egress.mode` | `allow-all` \| `deny-all` \| `allowlist` | always | `view` to watch, `control` to take keyboard and mouse. |
| `egress.domains` | array of string | always |  |
| `egress.cidrs` | array of string | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 404 | `sandbox-not-found` | No such sandbox in your organization. |
| 409 | `sandbox-ended` | The sandbox has ended. |

## POST /v1/sandboxes/:id/exec

Runs one command in the sandbox and answers with its exit code and output.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The sandbox's id. |

### Request body

JSON, the shape `SandboxExecRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cmd` | string or array of string | required | A string runs through `/bin/sh -c`; an array is the argument list, no shell. |
| `cwd` | string | optional | The working directory, an absolute path. at most 4096 characters. |
| `env` | object of string | optional | Plain environment variables. Use secrets for credentials. |
| `timeoutMs` | integer | optional | How long the command may run. 1000 to 600000, default `60000`. |
| `stdin` | string | optional | Text handed to the command's standard input. at most 1048576 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/sandboxes/<id>/exec" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"<cmd>"}'
```

### Response

`200` with the result:

```json
{
  "exitCode": -9007199254740991,
  "signal": "<signal>",
  "timedOut": true,
  "durationMs": -9007199254740991,
  "stdout": "<stdout>",
  "stderr": "<stderr>",
  "stdoutTruncated": true,
  "stderrTruncated": true
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `exitCode` | integer or null | always | The command's exit code. |
| `signal` | string or null | always | The signal that ended it, if one did. |
| `timedOut` | boolean | always | Whether `timeoutMs` ended it. |
| `durationMs` | integer | always | How long it ran. -9007199254740991 to 9007199254740991. |
| `stdout` | string | always |  |
| `stderr` | string | always |  |
| `stdoutTruncated` | boolean | always | Whether `stdout` was cut at 1 MiB. |
| `stderrTruncated` | boolean | always | Whether `stderr` was cut at 1 MiB. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 404 | `sandbox-not-found` | No such sandbox in your organization. |
| 409 | `sandbox-ended` | The sandbox has ended. |
| 409 | `sandbox-starting` | The sandbox is not running yet. |
| 503 | `audit-unavailable` | The audit record of the session could not be written, so it was not opened. |

## GET /v1/sandboxes/:id/files

Reads one file (`?path=`), as raw bytes.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The sandbox's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/sandboxes/<id>/files" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 404 | `sandbox-not-found` | No such sandbox in your organization. |
| 409 | `sandbox-ended` | The sandbox has ended. |
| 409 | `sandbox-starting` | The sandbox is not running yet. |
| 502 | `transport` |  |
| 503 | `audit-unavailable` | The audit record of the session could not be written, so it was not opened. |

## PUT /v1/sandboxes/:id/files

Writes one file (`?path=`, optional `mode` and `mkdirs=1`); the body is the file's bytes.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The sandbox's id. |

### Query parameters

| Name | Description |
| --- | --- |
| `mode` | The file mode, default `0644`. |
| `mkdirs` | `1` creates missing directories. |

### Request body

The raw bytes of the file.

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/sandboxes/<id>/files" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @hello.txt
```

### Response

`200` with a JSON object carrying `path`, `bytes`, `sha256`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 404 | `sandbox-not-found` | No such sandbox in your organization. |
| 409 | `sandbox-ended` | The sandbox has ended. |
| 409 | `sandbox-starting` | The sandbox is not running yet. |
| 413 | `too-large` | The body is larger than the route accepts. |
| 502 | `transport` |  |
| 503 | `audit-unavailable` | The audit record of the session could not be written, so it was not opened. |

## GET /v1/sandboxes/:id/files/list

Lists a directory (`?path=`).

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The sandbox's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/sandboxes/<id>/files/list" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `path`, `entries`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 404 | `sandbox-not-found` | No such sandbox in your organization. |
| 409 | `sandbox-ended` | The sandbox has ended. |
| 409 | `sandbox-starting` | The sandbox is not running yet. |
| 502 | `transport` |  |
| 503 | `audit-unavailable` | The audit record of the session could not be written, so it was not opened. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/postgres/ -->

# Postgres

> Databases Rytiv runs for you: create, branch, fork, restore, expire, fetch a copy's connection URL, delete.

A database is a resource of kind `postgres`: PostgreSQL on a machine of its own with its data on a volume, reachable only from the apps you attach it to, always over TLS. Every database can be branched (a copy-on-write copy on the same host, ready in seconds) or forked (a full copy from its archive, on any host, optionally from a moment in the past). See the guide [Postgres](https://docs.rytiv.com/postgres.md).

The resource routes also accept `kind: "redis"`; the fields that only apply to Postgres say so.

## Endpoints

- [`POST /v1/resources`](#post-v1resources): Creates a database. The answer carries the connection URL with its password, and only this answer does
- [`GET /v1/resources`](#get-v1resources): The organization's databases, never a URL
- [`GET /v1/resources/:name`](#get-v1resourcesname): One database with its state
- [`PATCH /v1/resources/:name`](#patch-v1resourcesname): Changes what can change later: the expiry of a copy, and the sleep policy
- [`DELETE /v1/resources/:name`](#delete-v1resourcesname): Deletes the database, its machine and its volume, and detaches it from every app. It cannot be undone
- [`POST /v1/resources/:name/branch`](#post-v1resourcesnamebranch): Creates a copy-on-write branch of the database as it is now. Answers `202` with the branch in state `restoring`
- [`POST /v1/resources/:name/fork`](#post-v1resourcesnamefork): Creates a full copy from the database's archive, optionally as of a moment in the past. Answers `202`
- [`POST /v1/resources/:name/restore`](#post-v1resourcesnamerestore): Puts the database back to a moment in time in place; the state before is kept as a branch
- [`POST /v1/resources/:name/url`](#post-v1resourcesnameurl): Hands out the connection URL of a branch or fork exactly once

## POST /v1/resources

Creates a database. The answer carries the connection URL with its password, and only this answer does.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Request body

JSON, the shape `CreateResourceRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | required | The database's name, like an app name. Unique across Rytiv. |
| `kind` | `redis` \| `postgres` | required | `postgres` or `redis`. |
| `memoryMb` | integer | optional | Memory of the database's machine. 128 to 16384. |
| `persistent` | boolean | optional | Whether the data lives on a volume. Default: yes for Postgres. |
| `sizeGb` | integer | optional | Size of the data volume in GB. 1 to 500. |
| `flushIntervalS` | integer | optional | How often the volume is copied to durable storage. 15 to 86400. |
| `durability` | `standard` \| `host-redundant` \| `zone-redundant` | optional | `standard`: one machine. `host-redundant`: a standby on a second host. Postgres only; `zone-redundant` is in the shape but refused at creation. |
| `locale` | string | optional | The ICU locale for sorting and comparing text. Fixed once the database exists. Postgres only. |
| `suspendPolicy` | object | optional | When the database sleeps. Postgres only; `{"mode": "off"}` keeps it always on. |
| `suspendPolicy.mode` | `suspend` \| `stop` \| `off` | optional | `suspend` keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), `stop` shuts down, `off` never sleeps. default `"suspend"`. |
| `suspendPolicy.idleSeconds` | integer | optional | Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default `300`. |
| `suspendPolicy.stopAfterSeconds` | integer | optional | Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with `mode: "suspend"`, and greater than `idleSeconds`. 10 to 604800. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/resources" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-db","kind":"postgres"}'
```

### Response

`201` with a JSON object of these fields:

| Field | Type | Description |
| --- | --- | --- |
| `name` | string |  |
| `kind` | string |  |
| `port` | integer |  |
| `secretKey` | string | the name of the secret an attached app gets, `DATABASE_URL` |
| `url` | string | the connection URL with its password; returned here only |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 400 | `name-reserved` | The platform keeps this name (for example `api`, `console`, `docs`, `www`, and every name that is `rytiv` or starts with `rytiv-`). |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 409 | `conflict` | The request conflicts with the current state. |
| 409 | `name-taken` | The name is used somewhere on Rytiv (an app, a database, a volume or a bucket). |
| 503 | `no-capacity` | No host in the region has room for the machine right now; try again. |

## GET /v1/resources

The organization's databases, never a URL.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/resources" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of databases, each:

```json
[
  {
    "name": "my-db",
    "orgId": "<orgId>",
    "kind": "postgres",
    "port": -9007199254740991,
    "secretKey": "<secretKey>",
    "durability": "standard",
    "createdAt": "2026-10-21T09:00:00Z",
    "state": "restoring"
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `name` | string | always | The database's name. |
| `orgId` | string | always | The organization that owns it. |
| `kind` | `redis` \| `postgres` | always | `postgres` or `redis`. |
| `port` | integer | always | The port the database listens on. -9007199254740991 to 9007199254740991. |
| `secretKey` | string | always | The name of the secret an attached app gets, `DATABASE_URL`. |
| `durability` | `standard` \| `host-redundant` \| `zone-redundant` | always | `standard`: one machine. `host-redundant`: a standby on a second host. default `"standard"`. |
| `primaryMachineId` | string | if set | Redundant databases: the machine that is primary now. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `state` | `restoring` \| `ready` \| `failed` | always | `ready`, or for a copy `restoring` until it is, or `failed`. default `"ready"`. |
| `stateReason` | string | if set | Why a copy ended `failed`. |
| `sourceName` | string | if set | Copies: the database it was made from. |
| `sourceAsOf` | string (ISO 8601) | if set | Copies: the moment of the source's data. |
| `copyKind` | `fork` \| `branch` | if set | `fork` or `branch`. |
| `ephemeral` | `true` | if set | Ephemeral branches only: `true`. |
| `ephemeralNote` | string | if set | The same, as a sentence. |
| `suspendPolicy` | object | if set | When the database sleeps. |
| `suspendPolicy.mode` | `suspend` \| `stop` \| `off` | always | `suspend` keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), `stop` shuts down, `off` never sleeps. default `"suspend"`. |
| `suspendPolicy.idleSeconds` | integer | always | Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default `300`. |
| `suspendPolicy.stopAfterSeconds` | integer | if set | Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with `mode: "suspend"`, and greater than `idleSeconds`. 10 to 604800. |
| `expiresAt` | string (ISO 8601) | if set | Copies: when the platform deletes it. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/resources/:name

One database with its state.

**Auth:** API key with full access (a key with scopes cannot call this route). Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The database's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/resources/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the database:

```json
{
  "name": "my-db",
  "orgId": "<orgId>",
  "kind": "postgres",
  "port": -9007199254740991,
  "secretKey": "<secretKey>",
  "durability": "standard",
  "createdAt": "2026-10-21T09:00:00Z",
  "state": "restoring"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `name` | string | always | The database's name. |
| `orgId` | string | always | The organization that owns it. |
| `kind` | `redis` \| `postgres` | always | `postgres` or `redis`. |
| `port` | integer | always | The port the database listens on. -9007199254740991 to 9007199254740991. |
| `secretKey` | string | always | The name of the secret an attached app gets, `DATABASE_URL`. |
| `durability` | `standard` \| `host-redundant` \| `zone-redundant` | always | `standard`: one machine. `host-redundant`: a standby on a second host. default `"standard"`. |
| `primaryMachineId` | string | if set | Redundant databases: the machine that is primary now. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `state` | `restoring` \| `ready` \| `failed` | always | `ready`, or for a copy `restoring` until it is, or `failed`. default `"ready"`. |
| `stateReason` | string | if set | Why a copy ended `failed`. |
| `sourceName` | string | if set | Copies: the database it was made from. |
| `sourceAsOf` | string (ISO 8601) | if set | Copies: the moment of the source's data. |
| `copyKind` | `fork` \| `branch` | if set | `fork` or `branch`. |
| `ephemeral` | `true` | if set | Ephemeral branches only: `true`. |
| `ephemeralNote` | string | if set | The same, as a sentence. |
| `suspendPolicy` | object | if set | When the database sleeps. |
| `suspendPolicy.mode` | `suspend` \| `stop` \| `off` | always | `suspend` keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), `stop` shuts down, `off` never sleeps. default `"suspend"`. |
| `suspendPolicy.idleSeconds` | integer | always | Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default `300`. |
| `suspendPolicy.stopAfterSeconds` | integer | if set | Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with `mode: "suspend"`, and greater than `idleSeconds`. 10 to 604800. |
| `expiresAt` | string (ISO 8601) | if set | Copies: when the platform deletes it. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## PATCH /v1/resources/:name

Changes what can change later: the expiry of a copy, and the sleep policy.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The database's name. |

### Request body

JSON, the shape `UpdateResourceRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `suspendPolicy` | object | optional | When the machine sleeps. Without it, a new app never sleeps; a deploy without it keeps the app's rule. |
| `suspendPolicy.mode` | `suspend` \| `stop` \| `off` | optional | `suspend` keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), `stop` shuts down, `off` never sleeps. default `"suspend"`. |
| `suspendPolicy.idleSeconds` | integer | optional | Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default `300`. |
| `suspendPolicy.stopAfterSeconds` | integer | optional | Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with `mode: "suspend"`, and greater than `idleSeconds`. 10 to 604800. |
| `expiresAt` | string (ISO 8601) or null | optional | When the copy is deleted (a moment). Not together with `ttlSeconds`. |
| `ttlSeconds` | integer | optional | Lifetime from now, in seconds. 60 to 2592000. |

### Example request

```bash
curl -X PATCH "https://api.rytiv.app/v1/resources/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"suspendPolicy":{"mode":"suspend"}}'
```

### Response

`200` with the database:

```json
{
  "name": "my-db",
  "orgId": "<orgId>",
  "kind": "postgres",
  "port": -9007199254740991,
  "secretKey": "<secretKey>",
  "durability": "standard",
  "createdAt": "2026-10-21T09:00:00Z",
  "state": "restoring"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `name` | string | always | The database's name. |
| `orgId` | string | always | The organization that owns it. |
| `kind` | `redis` \| `postgres` | always | `postgres` or `redis`. |
| `port` | integer | always | The port the database listens on. -9007199254740991 to 9007199254740991. |
| `secretKey` | string | always | The name of the secret an attached app gets, `DATABASE_URL`. |
| `durability` | `standard` \| `host-redundant` \| `zone-redundant` | always | `standard`: one machine. `host-redundant`: a standby on a second host. default `"standard"`. |
| `primaryMachineId` | string | if set | Redundant databases: the machine that is primary now. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `state` | `restoring` \| `ready` \| `failed` | always | `ready`, or for a copy `restoring` until it is, or `failed`. default `"ready"`. |
| `stateReason` | string | if set | Why a copy ended `failed`. |
| `sourceName` | string | if set | Copies: the database it was made from. |
| `sourceAsOf` | string (ISO 8601) | if set | Copies: the moment of the source's data. |
| `copyKind` | `fork` \| `branch` | if set | `fork` or `branch`. |
| `ephemeral` | `true` | if set | Ephemeral branches only: `true`. |
| `ephemeralNote` | string | if set | The same, as a sentence. |
| `suspendPolicy` | object | if set | When the database sleeps. |
| `suspendPolicy.mode` | `suspend` \| `stop` \| `off` | always | `suspend` keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), `stop` shuts down, `off` never sleeps. default `"suspend"`. |
| `suspendPolicy.idleSeconds` | integer | always | Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default `300`. |
| `suspendPolicy.stopAfterSeconds` | integer | if set | Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with `mode: "suspend"`, and greater than `idleSeconds`. 10 to 604800. |
| `expiresAt` | string (ISO 8601) | if set | Copies: when the platform deletes it. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/resources/:name

Deletes the database, its machine and its volume, and detaches it from every app. It cannot be undone.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The database's name. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/resources/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/resources/:name/branch

Creates a copy-on-write branch of the database as it is now. Answers `202` with the branch in state `restoring`.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The database's name. |

### Request body

JSON, the shape `BranchResourceRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | required | The name of the new branch. |
| `ephemeral` | boolean | optional | Ready faster, without an archive of its own; lost if its host fails. |
| `expiresAt` | string (ISO 8601) | optional | When the copy is deleted (a moment). Not together with `ttlSeconds`. |
| `ttlSeconds` | integer | optional | When the copy is deleted, as seconds from now. 60 to 2592000. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/resources/<name>/branch" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-db-try"}'
```

### Response

`202` with the branch, in state `restoring`:

```json
{
  "name": "my-db",
  "orgId": "<orgId>",
  "kind": "postgres",
  "port": -9007199254740991,
  "secretKey": "<secretKey>",
  "durability": "standard",
  "createdAt": "2026-10-21T09:00:00Z",
  "state": "restoring"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `name` | string | always | The database's name. |
| `orgId` | string | always | The organization that owns it. |
| `kind` | `redis` \| `postgres` | always | `postgres` or `redis`. |
| `port` | integer | always | The port the database listens on. -9007199254740991 to 9007199254740991. |
| `secretKey` | string | always | The name of the secret an attached app gets, `DATABASE_URL`. |
| `durability` | `standard` \| `host-redundant` \| `zone-redundant` | always | `standard`: one machine. `host-redundant`: a standby on a second host. default `"standard"`. |
| `primaryMachineId` | string | if set | Redundant databases: the machine that is primary now. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `state` | `restoring` \| `ready` \| `failed` | always | `ready`, or for a copy `restoring` until it is, or `failed`. default `"ready"`. |
| `stateReason` | string | if set | Why a copy ended `failed`. |
| `sourceName` | string | if set | Copies: the database it was made from. |
| `sourceAsOf` | string (ISO 8601) | if set | Copies: the moment of the source's data. |
| `copyKind` | `fork` \| `branch` | if set | `fork` or `branch`. |
| `ephemeral` | `true` | if set | Ephemeral branches only: `true`. |
| `ephemeralNote` | string | if set | The same, as a sentence. |
| `suspendPolicy` | object | if set | When the database sleeps. |
| `suspendPolicy.mode` | `suspend` \| `stop` \| `off` | always | `suspend` keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), `stop` shuts down, `off` never sleeps. default `"suspend"`. |
| `suspendPolicy.idleSeconds` | integer | always | Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default `300`. |
| `suspendPolicy.stopAfterSeconds` | integer | if set | Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with `mode: "suspend"`, and greater than `idleSeconds`. 10 to 604800. |
| `expiresAt` | string (ISO 8601) | if set | Copies: when the platform deletes it. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `name-taken` | The name is used somewhere on Rytiv (an app, a database, a volume or a bucket). |

## POST /v1/resources/:name/fork

Creates a full copy from the database's archive, optionally as of a moment in the past. Answers `202`.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The database's name. |

### Request body

JSON, the shape `ForkResourceRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | required | The name of the new fork. |
| `asOf` | string (ISO 8601) | optional | A moment in the past to copy or restore from (ISO 8601). Without it, now. |
| `expiresAt` | string (ISO 8601) | optional | When the copy is deleted (a moment). Not together with `ttlSeconds`. |
| `ttlSeconds` | integer | optional | When the copy is deleted, as seconds from now. 60 to 2592000. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/resources/<name>/fork" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-db-yesterday"}'
```

### Response

`202` with the fork, in state `restoring`:

```json
{
  "name": "my-db",
  "orgId": "<orgId>",
  "kind": "postgres",
  "port": -9007199254740991,
  "secretKey": "<secretKey>",
  "durability": "standard",
  "createdAt": "2026-10-21T09:00:00Z",
  "state": "restoring"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `name` | string | always | The database's name. |
| `orgId` | string | always | The organization that owns it. |
| `kind` | `redis` \| `postgres` | always | `postgres` or `redis`. |
| `port` | integer | always | The port the database listens on. -9007199254740991 to 9007199254740991. |
| `secretKey` | string | always | The name of the secret an attached app gets, `DATABASE_URL`. |
| `durability` | `standard` \| `host-redundant` \| `zone-redundant` | always | `standard`: one machine. `host-redundant`: a standby on a second host. default `"standard"`. |
| `primaryMachineId` | string | if set | Redundant databases: the machine that is primary now. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `state` | `restoring` \| `ready` \| `failed` | always | `ready`, or for a copy `restoring` until it is, or `failed`. default `"ready"`. |
| `stateReason` | string | if set | Why a copy ended `failed`. |
| `sourceName` | string | if set | Copies: the database it was made from. |
| `sourceAsOf` | string (ISO 8601) | if set | Copies: the moment of the source's data. |
| `copyKind` | `fork` \| `branch` | if set | `fork` or `branch`. |
| `ephemeral` | `true` | if set | Ephemeral branches only: `true`. |
| `ephemeralNote` | string | if set | The same, as a sentence. |
| `suspendPolicy` | object | if set | When the database sleeps. |
| `suspendPolicy.mode` | `suspend` \| `stop` \| `off` | always | `suspend` keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), `stop` shuts down, `off` never sleeps. default `"suspend"`. |
| `suspendPolicy.idleSeconds` | integer | always | Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default `300`. |
| `suspendPolicy.stopAfterSeconds` | integer | if set | Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with `mode: "suspend"`, and greater than `idleSeconds`. 10 to 604800. |
| `expiresAt` | string (ISO 8601) | if set | Copies: when the platform deletes it. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `name-taken` | The name is used somewhere on Rytiv (an app, a database, a volume or a bucket). |

## POST /v1/resources/:name/restore

Puts the database back to a moment in time in place; the state before is kept as a branch.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The database's name. |

### Request body

JSON, the shape `RestoreResourceRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `asOf` | string (ISO 8601) | required | A moment in the past to copy or restore from (ISO 8601). Without it, now. |
| `backupName` | string | optional | The name of the branch that keeps the state before the restore. Default: `<name>-old-<timestamp>`. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/resources/<name>/restore" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"asOf":"2026-10-21T09:00:00Z"}'
```

### Response

A JSON body on success.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/resources/:name/url

Hands out the connection URL of a branch or fork exactly once.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The name of the branch or fork. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/resources/<name>/url" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the connection URL:

```json
{
  "name": "my-app",
  "url": "<url>"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `name` | string | always |  |
| `url` | string | always | The connection URL with its password. Handed out once. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `not-a-copy` | The database is neither a fork nor a branch; its URL came with its create answer. |
| 409 | `not-ready` | The copy is still restoring, or failed; there is nothing to hand out yet. |
| 409 | `url-handed-out` | The URL of this copy was handed out already. It leaves the platform exactly once. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/volumes/ -->

# Volumes

> Persistent disks: create, list, resize, attach to an app, detach, delete.

A volume is a disk that outlives the machine it is attached to. An app with a volume runs exactly one machine; a deploy stops that machine before the new one starts. A computer's home is a volume named `<computer>-home`.

## Endpoints

- [`POST /v1/volumes`](#post-v1volumes): Creates a volume
- [`GET /v1/volumes`](#get-v1volumes): The organization's volumes
- [`PATCH /v1/volumes/:id`](#patch-v1volumesid): Resizes a volume or changes its settings
- [`DELETE /v1/volumes/:id`](#delete-v1volumesid): Deletes a volume that is not attached
- [`DELETE /v1/volumes/:id/attachment`](#delete-v1volumesidattachment): Detaches the volume from its app

## POST /v1/volumes

Creates a volume.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Request body

JSON, the shape `CreateVolumeRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | required |  |
| `sizeGb` | integer | optional | Size in GB. 1 to 500, default `10`. |
| `mountPath` | string | optional | default `"/data"`. |
| `class` | `standard` \| `durable` | optional | A named size instead of `vcpus`; the two must not contradict each other. default `"standard"`. |
| `flushIntervalS` | integer | optional | 15 to 86400. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/volumes" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"data"}'
```

### Response

`201` with the volume:

```json
{
  "id": "<id>",
  "name": "data",
  "orgId": "<orgId>",
  "sizeGb": 1,
  "mountPath": "<mountPath>",
  "class": "standard",
  "flushIntervalS": 86400,
  "leaseGen": 0,
  "durableGen": 0,
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The volume's id. |
| `name` | string | always |  |
| `orgId` | string | always | The organization that owns it. |
| `sizeGb` | integer | always | Its size. 1 to 500. |
| `mountPath` | string | always |  |
| `class` | `standard` \| `durable` | always | A named size instead of `vcpus`; the two must not contradict each other. default `"standard"`. |
| `flushIntervalS` | integer | always | 2 to 86400, default `86400`. |
| `machineId` | string | if set |  |
| `appName` | string | if set |  |
| `leaseHost` | string | if set |  |
| `leaseGen` | integer | always | 0 to 9007199254740991, default `0`. |
| `durableGen` | integer | always | 0 to 9007199254740991, default `0`. |
| `durableAt` | string (ISO 8601) | if set | When the last copy to durable storage completed. |
| `walDurableAt` | string (ISO 8601) | if set |  |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 409 | `name-taken` | The name is used somewhere on Rytiv (an app, a database, a volume or a bucket). |

## GET /v1/volumes

The organization's volumes.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/volumes" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of volumes, each:

```json
[
  {
    "id": "<id>",
    "name": "data",
    "orgId": "<orgId>",
    "sizeGb": 1,
    "mountPath": "<mountPath>",
    "class": "standard",
    "flushIntervalS": 86400,
    "leaseGen": 0,
    "durableGen": 0,
    "createdAt": "2026-10-21T09:00:00Z"
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The volume's id. |
| `name` | string | always |  |
| `orgId` | string | always | The organization that owns it. |
| `sizeGb` | integer | always | Its size. 1 to 500. |
| `mountPath` | string | always |  |
| `class` | `standard` \| `durable` | always | A named size instead of `vcpus`; the two must not contradict each other. default `"standard"`. |
| `flushIntervalS` | integer | always | 2 to 86400, default `86400`. |
| `machineId` | string | if set |  |
| `appName` | string | if set |  |
| `leaseHost` | string | if set |  |
| `leaseGen` | integer | always | 0 to 9007199254740991, default `0`. |
| `durableGen` | integer | always | 0 to 9007199254740991, default `0`. |
| `durableAt` | string (ISO 8601) | if set | When the last copy to durable storage completed. |
| `walDurableAt` | string (ISO 8601) | if set |  |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## PATCH /v1/volumes/:id

Resizes a volume or changes its settings.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The volume's id. |

### Request body

JSON, the shape `UpdateVolumeRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sizeGb` | integer | optional | Size in GB. 1 to 500. |
| `flushIntervalS` | integer | optional | 15 to 86400. |

### Example request

```bash
curl -X PATCH "https://api.rytiv.app/v1/volumes/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sizeGb":1}'
```

### Response

`200` with the volume:

```json
{
  "id": "<id>",
  "name": "data",
  "orgId": "<orgId>",
  "sizeGb": 1,
  "mountPath": "<mountPath>",
  "class": "standard",
  "flushIntervalS": 86400,
  "leaseGen": 0,
  "durableGen": 0,
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The volume's id. |
| `name` | string | always |  |
| `orgId` | string | always | The organization that owns it. |
| `sizeGb` | integer | always | Its size. 1 to 500. |
| `mountPath` | string | always |  |
| `class` | `standard` \| `durable` | always | A named size instead of `vcpus`; the two must not contradict each other. default `"standard"`. |
| `flushIntervalS` | integer | always | 2 to 86400, default `86400`. |
| `machineId` | string | if set |  |
| `appName` | string | if set |  |
| `leaseHost` | string | if set |  |
| `leaseGen` | integer | always | 0 to 9007199254740991, default `0`. |
| `durableGen` | integer | always | 0 to 9007199254740991, default `0`. |
| `durableAt` | string (ISO 8601) | if set | When the last copy to durable storage completed. |
| `walDurableAt` | string (ISO 8601) | if set |  |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/volumes/:id

Deletes a volume that is not attached.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The volume's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/volumes/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `volume-attached` |  |

## DELETE /v1/volumes/:id/attachment

Detaches the volume from its app.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/volumes/<id>/attachment" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/buckets/ -->

# Buckets

> S3-compatible object storage: create buckets, presign object URLs, list and delete objects, set CORS, attach to apps.

A bucket holds objects and speaks the S3 protocol. Your app reaches it in two ways: ask this API for a presigned URL per object, or attach the bucket to the app, which gives the app a key scoped to that bucket and the `S3_*` environment variables to use it directly. See the guide [Buckets](https://docs.rytiv.com/guides/buckets.md).

Attaching and detaching a bucket go through the app's `attach` and `detach` routes (see [Apps](https://docs.rytiv.com/reference/api/apps.md)) with a body of `{"bucket": "<name>", "as": "<prefix>"}`.

## Endpoints

- [`POST /v1/buckets`](#post-v1buckets): Creates a bucket. Names are unique across Rytiv
- [`GET /v1/buckets`](#get-v1buckets): The organization's buckets
- [`GET /v1/bucket-names/:name`](#get-v1bucket-namesname): Whether a bucket name is still available, and if not, why
- [`GET /v1/buckets/:name`](#get-v1bucketsname): One bucket
- [`DELETE /v1/buckets/:name`](#delete-v1bucketsname): Deletes a bucket
- [`POST /v1/buckets/:name/presign`](#post-v1bucketsnamepresign): A time-limited URL for one object and one method (`get` or `put`)
- [`GET /v1/buckets/:name/objects`](#get-v1bucketsnameobjects): Lists objects, with a cursor for the next page
- [`DELETE /v1/buckets/:name/objects`](#delete-v1bucketsnameobjects): Deletes objects by key
- [`GET /v1/buckets/:name/cors`](#get-v1bucketsnamecors): The bucket's CORS rules
- [`PUT /v1/buckets/:name/cors`](#put-v1bucketsnamecors): Replaces the bucket's CORS rules. An empty list removes them
- [`GET /v1/bucket-attachments`](#get-v1bucket-attachments): Which bucket is attached to which app, and the environment it injected

## POST /v1/buckets

Creates a bucket. Names are unique across Rytiv.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Request body

JSON, the shape `CreateBucketRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | required | The bucket's name. Unique across Rytiv. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/buckets" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-bucket"}'
```

### Response

`201` with the bucket:

```json
{
  "id": "<id>",
  "name": "my-bucket",
  "orgId": "<orgId>",
  "backendRef": "<backendRef>",
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The bucket's id. |
| `name` | string | always |  |
| `orgId` | string | always | The organization that owns it. |
| `backendRef` | string | always | Where the objects live, in the storage layer's own words; opaque. |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/buckets

The organization's buckets.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/buckets" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of buckets, each:

```json
[
  {
    "id": "<id>",
    "name": "my-bucket",
    "orgId": "<orgId>",
    "backendRef": "<backendRef>",
    "createdAt": "2026-10-21T09:00:00Z"
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The bucket's id. |
| `name` | string | always |  |
| `orgId` | string | always | The organization that owns it. |
| `backendRef` | string | always | Where the objects live, in the storage layer's own words; opaque. |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/bucket-names/:name

Whether a bucket name is still available, and if not, why.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The name to check. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/bucket-names/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the answer:

```json
{
  "name": "my-app",
  "available": true
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `name` | string | always |  |
| `available` | boolean | always | Whether you can have the name. |
| `reason` | `taken` \| `taken-by-you` \| `reserved` \| `invalid` | if set | If not: `taken`, `taken-by-you`, `reserved` or `invalid`. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/buckets/:name

One bucket.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The bucket's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/buckets/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the bucket:

```json
{
  "id": "<id>",
  "name": "my-bucket",
  "orgId": "<orgId>",
  "backendRef": "<backendRef>",
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The bucket's id. |
| `name` | string | always |  |
| `orgId` | string | always | The organization that owns it. |
| `backendRef` | string | always | Where the objects live, in the storage layer's own words; opaque. |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/buckets/:name

Deletes a bucket.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The bucket's name. |

### Query parameters

| Name | Description |
| --- | --- |
| `force` |  |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/buckets/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `destroyed`, `deletedObjects`, `detached`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/buckets/:name/presign

A time-limited URL for one object and one method (`get` or `put`).

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The bucket's name. |

### Request body

JSON, the shape `PresignRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `op` | `get` \| `put` | optional | `get` for a download URL, `put` for an upload URL. default `"get"`. |
| `key` | string | required | The object's key. 1 to 1024 characters. |
| `expiresInS` | integer | optional | How long the URL stays valid, in seconds. 1 to 604800, default `900`. |
| `contentType` | string | optional | `put` only: the Content-Type the upload must send. It is part of the signature. 1 to 255 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/buckets/<name>/presign" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"uploads/report.pdf"}'
```

### Response

`200` with the presigned URL:

```json
{
  "url": "<url>",
  "method": "GET",
  "key": "uploads/report.pdf",
  "expiresAt": "2026-10-21T09:00:00Z",
  "requiredHeaders": {
    "<key>": "<value>"
  }
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `url` | string | always | The URL to call with `method`. |
| `method` | `GET` \| `PUT` | always | With `path`: `GET` (default) or `POST`. |
| `key` | string | always | The object's key. |
| `expiresAt` | string (ISO 8601) | always | When the copy is deleted (a moment). Not together with `ttlSeconds`. |
| `requiredHeaders` | object of string | always | Headers the call must send exactly; a missing one breaks the signature. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/buckets/:name/objects

Lists objects, with a cursor for the next page.

**Auth:** API key with full access or the scope `read`. An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The bucket's name. |

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | How many objects per page. |
| `prefix` | Only keys that start with this. |
| `cursor` | The `nextCursor` of the previous page. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/buckets/<name>/objects" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the page of objects:

```json
{
  "bucket": "my-bucket",
  "objects": [
    {
      "key": "uploads/report.pdf",
      "sizeBytes": 0,
      "lastModified": "<lastModified>"
    }
  ]
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `bucket` | string | always |  |
| `objects` | array of object | always |  |
| `nextCursor` | string | if set | Hand it back as `cursor` to get the next page. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/buckets/:name/objects

Deletes objects by key.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The bucket's name. |

### Query parameters

| Name | Description |
| --- | --- |
| `key` |  |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/buckets/<name>/objects" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `bucket`, `deleted`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/buckets/:name/cors

The bucket's CORS rules.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The bucket's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/buckets/<name>/cors" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the rules:

```json
{
  "rules": [
    {
      "allowedMethods": [
        "GET"
      ],
      "allowedOrigins": [
        "<allowedOrigin>"
      ]
    }
  ]
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `rules` | array of object | always | The whole CORS configuration; a `PUT` replaces it. |
| `warnings` | array of string | if set |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## PUT /v1/buckets/:name/cors

Replaces the bucket's CORS rules. An empty list removes them.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The bucket's name. |

### Request body

JSON, the shape `PutBucketCorsRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rules` | array of object | required | The whole CORS configuration; a `PUT` replaces it. 0 to 100 items. |

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/buckets/<name>/cors" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"allowedMethods":["GET"],"allowedOrigins":["<allowedOrigin>"]}]}'
```

### Response

`200` with the rules as stored:

```json
{
  "rules": [
    {
      "allowedMethods": [
        "GET"
      ],
      "allowedOrigins": [
        "<allowedOrigin>"
      ]
    }
  ]
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `rules` | array of object | always | The whole CORS configuration; a `PUT` replaces it. |
| `warnings` | array of string | if set |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/bucket-attachments

Which bucket is attached to which app, and the environment it injected.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/bucket-attachments" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of attachments, each:

```json
[
  {
    "appName": "my-app",
    "bucketName": "<bucketName>",
    "injected": [
      "<injected>"
    ]
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `appName` | string | always |  |
| `bucketName` | string | always |  |
| `injected` | array of string | always | The environment variables the attachment gave the app. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/secrets/ -->

# Secrets

> Encrypted environment variables of an app: set, list names, remove, and choose which ones a build may see.

Secrets are environment variables stored encrypted. The API lists their names and never their values. A secret reaches the app's machines at their next start; with `"staged": false` Rytiv rolls the app right away. Each secret carries a `build` choice: whether the next source build sees it as environment, or only the running machines do.

Secrets that Rytiv manages for you (the `DATABASE_URL` of an attached database, the `S3_*` keys of an attached bucket) cannot be changed or removed here; detach the resource instead.

## Endpoints

- [`GET /v1/apps/:name/secrets`](#get-v1appsnamesecrets): The app's secrets: names, when they changed, whether Rytiv manages them, and whether a build sees them. Never a value
- [`PUT /v1/apps/:name/secrets`](#put-v1appsnamesecrets): Sets secrets. `staged: true` (the default) applies them at the next deploy; `staged: false` rolls the app now. `build` chooses per key whether the next build sees it
- [`DELETE /v1/apps/:name/secrets/:key`](#delete-v1appsnamesecretskey): Removes one secret

## GET /v1/apps/:name/secrets

The app's secrets: names, when they changed, whether Rytiv manages them, and whether a build sees them. Never a value.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app, or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/secrets" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of secrets, each:

```json
[
  {
    "name": "my-app",
    "updatedAt": "2026-10-21T09:00:00Z",
    "managed": true
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `name` | string | always | The secret's name. |
| `updatedAt` | string (ISO 8601) | always | When it last changed. |
| `managed` | boolean | always | Whether Rytiv manages it (an attachment or a database password); then it cannot be changed here. |
| `managedReason` | `attachment` \| `resource-password` | if set | `attachment` or `resource-password`. |
| `build` | boolean | if set | Whether the next source build sees it. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## PUT /v1/apps/:name/secrets

Sets secrets. `staged: true` (the default) applies them at the next deploy; `staged: false` rolls the app now. `build` chooses per key whether the next build sees it.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app. An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `SetSecretsRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `secrets` | object of string | optional | Names and values to set. Names like `MY_SECRET`; the platform's own `RYTIV_` names are refused. |
| `staged` | boolean | optional | `true` (default): the values apply at the next deploy. `false`: Rytiv rolls the app now if a machine lacks a new value. default `true`. |
| `build` | object of boolean | optional | Per secret name, whether the next source build sees it as environment. |

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/apps/<name>/secrets" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secrets":{"<key>":"<value>"}}'
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `org-limit-computers` | The organization has as many computers as it may have. The body carries `limit` and `current`. Delete one, or contact us for more. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/apps/:name/secrets/:key

Removes one secret.

**Auth:** API key with full access or the scope `deploy` or `deploy:<app>` for this app. An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `key` | The secret's name. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/apps/<name>/secrets/<key>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/tokens/ -->

# Tokens and keys

> API keys with scopes and expiry, agent tokens with a class, the audit of agent actions, SSH keys and the device login.

An API key belongs to an organization and is sent as a bearer token. Without `scopes` it is the whole organization; with scopes it can only do less (`read`, `deploy`, `deploy:<app>`, `mail:send`, `mail:send:<domain>`). An `agent` block makes it an agent token with a class (`sandbox`, `twin` or `production`) and an optional list of apps; the platform enforces both. See the guide [Agents and tokens](https://docs.rytiv.com/guides/agents-and-tokens.md).

A key is shown exactly once, in the answer that creates it. Rytiv stores only a hash.

## Endpoints

- [`POST /v1/tokens`](#post-v1tokens): Creates an API key. The value is in this answer only
- [`GET /v1/tokens`](#get-v1tokens): The organization's keys, without their values
- [`DELETE /v1/tokens/:id`](#delete-v1tokensid): Revokes a key. Requests already using it are rejected right away
- [`GET /v1/agent-actions`](#get-v1agent-actions): The audit of what agent tokens did: every judged request with its verdict. `?token=` narrows to one key, `?limit=` bounds the page
- [`GET /v1/ssh`](#get-v1ssh): The SSH gateway's address and host key
- [`GET /v1/ssh-keys`](#get-v1ssh-keys): The public keys that may open an SSH session
- [`POST /v1/ssh-keys`](#post-v1ssh-keys): Adds a public key
- [`DELETE /v1/ssh-keys/:id`](#delete-v1ssh-keysid): Removes a public key
- [`GET /v1/ssh/tokens`](#get-v1sshtokens): The short-lived SSH tokens of the organization
- [`POST /v1/ssh/tokens`](#post-v1sshtokens): Creates a short-lived SSH token
- [`DELETE /v1/ssh/tokens/:id`](#delete-v1sshtokensid): Revokes an SSH token
- [`POST /v1/device/lookup`](#post-v1devicelookup): Looks up a device login by its user code, for the console's confirmation page
- [`POST /v1/device/approve`](#post-v1deviceapprove): Approves a device login; the waiting CLI then receives a key for this organization

## POST /v1/tokens

Creates an API key. The value is in this answer only.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `CreateTokenRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | required | A name for the key, shown in lists. 1 to 120 characters. |
| `scopes` | array of string | optional | What the key may do: `read`, `deploy`, `deploy:<app>`, `mail:send`, `mail:send:<domain>`. Omitted: full access. 0 to 20 items. |
| `expiresAt` | string (ISO 8601) | optional | When the key stops working (a moment). Not together with `ttlSeconds`. |
| `ttlSeconds` | integer | optional | When the key stops working, as seconds from now. Never later than the key that creates it. 60 to 31536000. |
| `agent` | object | optional | Makes it an agent token. |
| `agent.class` | `sandbox` \| `twin` \| `production` | required | `sandbox` and `twin` may do what the key may do; `production` may only read. |
| `agent.apps` | array of string | optional | The apps the token may touch. Omitted: the whole organization. 1 to 50 items. |
| `agent.prodDataRead` | boolean | optional | Class `production` only: may the agent read what production holds (files, a shell, query results), not only what it says about itself. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/tokens" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-deploy"}'
```

### Response

`201` with a JSON object of these fields:

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `prefix` | string | the first characters, shown in lists |
| `token` | string | the key itself; shown here only |
| `scopes` | array of string | if the key has scopes |
| `expiresAt` | string (ISO 8601) | if the key expires |
| `agent` | object | if it is an agent token: `class`, `apps`, `prodDataRead` |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/tokens

The organization's keys, without their values.

**Auth:** API key with full access (a key with scopes cannot call this route). Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/tokens" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of keys, each:

```json
[
  {
    "id": "<id>",
    "orgId": "<orgId>",
    "name": "my-app",
    "prefix": "UPLOADS",
    "createdAt": "2026-10-21T09:00:00Z"
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The key's id. |
| `orgId` | string | always | The organization that owns it. |
| `userId` | string | if set | The person who created it, if a person did. |
| `name` | string | always | Its name. |
| `prefix` | string | always | The first characters, to recognise it. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `lastUsedAt` | string (ISO 8601) | if set | When it was last used. |
| `agent` | object | if set | Agent tokens: class, apps and `prodDataRead`. |
| `agent.class` | `sandbox` \| `twin` \| `production` | always | `sandbox` and `twin` may do what the key may do; `production` may only read. |
| `agent.apps` | array of string | if set | The apps the token may touch. Omitted: the whole organization. |
| `agent.prodDataRead` | boolean | always | Class `production` only: may the agent read what production holds (files, a shell, query results), not only what it says about itself. |
| `scopes` | array of string | if set | The key's scopes; absent means full access. |
| `expiresAt` | string (ISO 8601) | if set | When it stops working; absent means never. |
| `expired` | boolean | if set | Whether it has, as of this answer. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## DELETE /v1/tokens/:id

Revokes a key. Requests already using it are rejected right away.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The key's id (`tok-...`). |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/tokens/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/agent-actions

The audit of what agent tokens did: every judged request with its verdict. `?token=` narrows to one key, `?limit=` bounds the page.

**Auth:** API key with full access (a key with scopes cannot call this route). Every class of agent token may call it.

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | How many entries, at most. |
| `token` | Only the actions of this key. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/agent-actions" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/ssh

The SSH gateway's address and host key.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/ssh" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/ssh-keys

The public keys that may open an SSH session.

**Auth:** API key with full access (a key with scopes cannot call this route). Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/ssh-keys" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## POST /v1/ssh-keys

Adds a public key.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `SshKeyCreate` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `publicKey` | string | required | 1 to 16384 characters. |
| `name` | string | optional | 1 to 100 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/ssh-keys" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"publicKey":"<publicKey>"}'
```

### Response

`201` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid-key` |  |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 409 | `duplicate` |  |
| 409 | `limit` |  |

## DELETE /v1/ssh-keys/:id

Removes a public key.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/ssh-keys/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/ssh/tokens

The short-lived SSH tokens of the organization.

**Auth:** API key with full access (a key with scopes cannot call this route). Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/ssh/tokens" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## POST /v1/ssh/tokens

Creates a short-lived SSH token.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `SshTokenCreate` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `app` | string | required | 1 to 63 characters. |
| `machine` | string | optional | 1 to 64 characters. |
| `ttlS` | integer | optional | How long the link opens a connection, in seconds. 60 to 259200. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/ssh/tokens" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app":"<app>"}'
```

### Response

`201` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## DELETE /v1/ssh/tokens/:id

Revokes an SSH token.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/ssh/tokens/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/device/lookup

Looks up a device login by its user code, for the console's confirmation page.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/device/lookup" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userCode":"BCDF-GHJK"}'
```

### Response

`200` with a JSON object carrying `client`, `version`, `requestedFrom`, `requestedAt`, `expiresAt`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## POST /v1/device/approve

Approves a device login; the waiting CLI then receives a key for this organization.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `DeviceApproveRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `userCode` | string | required | 1 to 40 characters. |
| `approve` | boolean | optional | default `true`. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/device/approve" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userCode":"<userCode>"}'
```

### Response

`200` with a JSON object carrying `ok`, `approved`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/organization/ -->

# Organization

> Your organization, its wake page and signed-access keys, organizations you manage for others, and deleting your own.

Every key acts as one organization. `GET /v1/org` is the probe the CLI uses to prove an endpoint and a key; it answers the key's own organization and nothing else. An organization that manages others can act inside them with the header `X-Rytiv-Org: <org id>` (see [REST API basics](https://docs.rytiv.com/reference/api-basics.md)).

## Endpoints

- [`GET /v1/org`](#get-v1org): The key's own organization, and who manages it, if anyone
- [`DELETE /v1/org`](#delete-v1org): Deletes your own organization. It must be empty
- [`GET /v1/org/wake-page`](#get-v1orgwake-page): The page shown while a sleeping app wakes
- [`PUT /v1/org/wake-page`](#put-v1orgwake-page): Sets that page (HTML)
- [`DELETE /v1/org/wake-page`](#delete-v1orgwake-page): Restores the default wake page
- [`GET /v1/org/signed-access`](#get-v1orgsigned-access): The organization's settings for signed links
- [`PUT /v1/org/signed-access`](#put-v1orgsigned-access): Changes those settings
- [`POST /v1/org/signed-access/keys`](#post-v1orgsigned-accesskeys): Adds a signing key
- [`DELETE /v1/org/signed-access/keys/:id`](#delete-v1orgsigned-accesskeysid): Removes a signing key
- [`POST /v1/orgs/managed`](#post-v1orgsmanaged): Creates an organization that yours manages
- [`GET /v1/orgs/managed`](#get-v1orgsmanaged): The organizations yours manages
- [`POST /v1/orgs/managed/:id/release`](#post-v1orgsmanagedidrelease): Hands a managed organization over to itself; your keys stop acting in it

## GET /v1/org

The key's own organization, and who manages it, if anyone.

**Auth:** Any API key, whatever its scopes. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/org" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the organization:

```json
{
  "id": "<id>",
  "name": "my-app",
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The organization's id. |
| `name` | string | always | Its name. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `managedBy` | string or null | if set | The id of the organization that manages this one, or null. |
| `managedByName` | string or null | if set | That organization's name, or null. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |

## DELETE /v1/org

Deletes your own organization. It must be empty.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `OrgSelfDeleteRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `confirmName` | string | required | 1 to 120 characters. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/org" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirmName":"<confirmName>"}'
```

### Response

`200` with a JSON object carrying `ok`, `deleted`, `removed`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/org/wake-page

The page shown while a sleeping app wakes.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/org/wake-page" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `digest`, `bytes`, `updatedAt`, `html`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## PUT /v1/org/wake-page

Sets that page (HTML).

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Request body

JSON, the shape `SetWakePageRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `html` | string | required | The page as HTML. |

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/org/wake-page" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"html":"<html>"}'
```

### Response

`200` with a JSON object carrying `digest`, `bytes`, `updatedAt`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## DELETE /v1/org/wake-page

Restores the default wake page.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/org/wake-page" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/org/signed-access

The organization's settings for signed links.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/org/signed-access" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## PUT /v1/org/signed-access

Changes those settings.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `PutSignedAccessRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cookieTtlSeconds` | integer | optional | 60 to 86400. |
| `frameAncestors` | array of string | optional | 0 to 8 items. |

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/org/signed-access" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cookieTtlSeconds":60}'
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## POST /v1/org/signed-access/keys

Adds a signing key.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `CreateAccessKeyRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | required | 1 to 64 characters. |
| `publicKey` | string | required | 1 to 1024 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/org/signed-access/keys" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"before-migration","publicKey":"<publicKey>"}'
```

### Response

`201` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-public-key` |  |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 400 | `private-key` |  |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 409 | `duplicate-key` |  |
| 409 | `too-many-keys` |  |

## DELETE /v1/org/signed-access/keys/:id

Removes a signing key.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/org/signed-access/keys/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/orgs/managed

Creates an organization that yours manages.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `CreateManagedOrgRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | required | 1 to 120 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/orgs/managed" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-app"}'
```

### Response

`200` or `201` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/orgs/managed

The organizations yours manages.

**Auth:** API key with full access or the scope `read`. Refused for every agent token (`agent-token-credential`).

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/orgs/managed" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the list:

```json
{
  "quota": -9007199254740991,
  "used": -9007199254740991,
  "remaining": -9007199254740991,
  "orgs": [
    {
      "id": "<id>",
      "name": "my-app"
    }
  ]
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `quota` | integer | always | -9007199254740991 to 9007199254740991. |
| `used` | integer | always | -9007199254740991 to 9007199254740991. |
| `remaining` | integer | always | -9007199254740991 to 9007199254740991. |
| `orgs` | array of object | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## POST /v1/orgs/managed/:id/release

Hands a managed organization over to itself; your keys stop acting in it.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/orgs/managed/<id>/release" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `id`, `managedBy`, `revokedTokens`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/billing/ -->

# Billing and usage

> Prepaid credit in euro: balance, ledger, top-ups, auto-recharge, the payment portal, the billing preview and metered usage.

Rytiv bills from prepaid credit in euro. Usage is metered per machine and booked against the balance; at zero, machines are stopped (not deleted), nothing new starts and reads stay open. Top-ups and the auto-recharge rule are set in the console by an admin; the routes for them refuse a plain API key. See the guide [Credit and prices](https://docs.rytiv.com/billing.md).

## Endpoints

- [`GET /v1/billing/credits`](#get-v1billingcredits): The credit account: balance, whether it is blocked at zero, the warning line and the auto-recharge rule
- [`GET /v1/billing/ledger`](#get-v1billingledger): The credit ledger: top-ups, usage bookings, grants, refunds and adjustments, newest first
- [`POST /v1/billing/topups`](#post-v1billingtopups): Starts a top-up and answers the payment page to open. The card is typed there; no card data crosses this API
- [`PUT /v1/billing/auto-recharge`](#put-v1billingauto-recharge): Sets the auto-recharge rule: when the balance falls below `thresholdCents`, charge `amountCents`, never more than `capCents` in total
- [`POST /v1/billing/portal`](#post-v1billingportal): A link to the payment portal, where a saved card is changed
- [`GET /v1/billing/preview`](#get-v1billingpreview): What a period cost, line by line, from the metered usage
- [`GET /v1/usage`](#get-v1usage): The metered usage events of the organization

## GET /v1/billing/credits

The credit account: balance, whether it is blocked at zero, the warning line and the auto-recharge rule.

**Auth:** API key with full access (a key with scopes cannot call this route). Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/billing/credits" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the credit account:

```json
{
  "orgId": "<orgId>",
  "currency": "EUR",
  "prepaid": true,
  "balanceMicros": "<balanceMicros>",
  "balanceCents": -9007199254740991,
  "blocked": true,
  "blockedAt": "2026-10-21T09:00:00Z",
  "warned": true,
  "warnAtPercent": 0,
  "minTopupCents": 1,
  "priced": [
    "<priced>"
  ],
  "autoRecharge": {
    "enabled": true,
    "thresholdCents": 0,
    "amountCents": 0,
    "capCents": 0,
    "pending": true,
    "failedAt": "2026-10-21T09:00:00Z",
    "hasPaymentMethod": true
  }
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `orgId` | string | always | The organization that owns it. |
| `currency` | `"EUR"` | always |  |
| `prepaid` | boolean | always | Whether the organization is on prepaid credit. |
| `balanceMicros` | string | always | The exact balance in micro-cents, as a decimal string. |
| `balanceCents` | integer | always | The balance in whole cents, rounded down. -9007199254740991 to 9007199254740991. |
| `blocked` | boolean | always | The balance reached zero: machines stopped, nothing new starts, reads stay open. |
| `blockedAt` | string (ISO 8601) or null | always | When that happened. |
| `warned` | boolean | always | The balance fell below the warning line. |
| `warnAtPercent` | integer | always | The warning line as a percentage of the reference top-up. 0 to 100. |
| `minTopupCents` | integer | always | The smallest top-up. at most 9007199254740991. |
| `priced` | array of string | always | The usage kinds that carry a price right now. |
| `autoRecharge` | object | always | The auto-recharge rule and its state. |
| `autoRecharge.enabled` | boolean | always | `false` creates the schedule paused. |
| `autoRecharge.thresholdCents` | integer | always | Charge when the balance falls below this. 0 to 9007199254740991. |
| `autoRecharge.amountCents` | integer | always | Whole cents. 0 to 9007199254740991. |
| `autoRecharge.capCents` | integer | always | Never charge more than this in total through the rule. 0 to 9007199254740991. |
| `autoRecharge.pending` | boolean | always |  |
| `autoRecharge.failedAt` | string (ISO 8601) or null | always |  |
| `autoRecharge.hasPaymentMethod` | boolean | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/billing/ledger

The credit ledger: top-ups, usage bookings, grants, refunds and adjustments, newest first.

**Auth:** API key with full access (a key with scopes cannot call this route). Every class of agent token may call it.

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | How many entries, at most. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/billing/ledger" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the ledger:

```json
{
  "orgId": "<orgId>",
  "currency": "EUR",
  "limit": 1,
  "entries": [
    {
      "id": "<id>",
      "kind": "topup",
      "amountMicros": "<amountMicros>",
      "amountCents": -9007199254740991,
      "reference": "goodwill-2026-10",
      "windowFrom": "2026-10-21T09:00:00Z",
      "windowTo": "2026-10-21T09:00:00Z",
      "detail": "<detail>",
      "at": "2026-10-21T09:00:00Z"
    }
  ]
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `orgId` | string | always | The organization that owns it. |
| `currency` | `"EUR"` | always |  |
| `limit` | integer | always | at most 9007199254740991. |
| `entries` | array of object | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## POST /v1/billing/topups

Starts a top-up and answers the payment page to open. The card is typed there; no card data crosses this API.

**Auth:** API key with full access, and only through the console as an admin (a plain API key answers `403` with `billing-console-only`). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `CreditTopupRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amountCents` | integer | required | Whole cents. at most 9007199254740991. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/billing/topups" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amountCents":1}'
```

### Response

`201` with the top-up:

```json
{
  "topupId": "<topupId>",
  "amountCents": 1,
  "checkoutUrl": "<checkoutUrl>",
  "sessionId": "<sessionId>"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `topupId` | string | always |  |
| `amountCents` | integer | always | Whole cents. at most 9007199254740991. |
| `checkoutUrl` | string | always | The payment page to open. The card is typed there. |
| `sessionId` | string | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `billing-console-only` | A billing change is made in the console by an admin, not with an API key. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 409 | `not-prepaid` | The organization has no credit account; only org creation or an operator's grant starts prepaid credit. |

## PUT /v1/billing/auto-recharge

Sets the auto-recharge rule: when the balance falls below `thresholdCents`, charge `amountCents`, never more than `capCents` in total.

**Auth:** API key with full access, and only through the console as an admin (a plain API key answers `403` with `billing-console-only`). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `CreditAutoRechargeRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | required | `false` creates the schedule paused. |
| `thresholdCents` | integer | optional | Charge when the balance falls below this. 0 to 9007199254740991, default `0`. |
| `amountCents` | integer | optional | Whole cents. 0 to 9007199254740991, default `0`. |
| `capCents` | integer | optional | Never charge more than this in total through the rule. 0 to 9007199254740991, default `0`. |

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/billing/auto-recharge" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'
```

### Response

`200` with the credit account with the new rule:

```json
{
  "orgId": "<orgId>",
  "currency": "EUR",
  "prepaid": true,
  "balanceMicros": "<balanceMicros>",
  "balanceCents": -9007199254740991,
  "blocked": true,
  "blockedAt": "2026-10-21T09:00:00Z",
  "warned": true,
  "warnAtPercent": 0,
  "minTopupCents": 1,
  "priced": [
    "<priced>"
  ],
  "autoRecharge": {
    "enabled": true,
    "thresholdCents": 0,
    "amountCents": 0,
    "capCents": 0,
    "pending": true,
    "failedAt": "2026-10-21T09:00:00Z",
    "hasPaymentMethod": true
  }
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `orgId` | string | always | The organization that owns it. |
| `currency` | `"EUR"` | always |  |
| `prepaid` | boolean | always | Whether the organization is on prepaid credit. |
| `balanceMicros` | string | always | The exact balance in micro-cents, as a decimal string. |
| `balanceCents` | integer | always | The balance in whole cents, rounded down. -9007199254740991 to 9007199254740991. |
| `blocked` | boolean | always | The balance reached zero: machines stopped, nothing new starts, reads stay open. |
| `blockedAt` | string (ISO 8601) or null | always | When that happened. |
| `warned` | boolean | always | The balance fell below the warning line. |
| `warnAtPercent` | integer | always | The warning line as a percentage of the reference top-up. 0 to 100. |
| `minTopupCents` | integer | always | The smallest top-up. at most 9007199254740991. |
| `priced` | array of string | always | The usage kinds that carry a price right now. |
| `autoRecharge` | object | always | The auto-recharge rule and its state. |
| `autoRecharge.enabled` | boolean | always | `false` creates the schedule paused. |
| `autoRecharge.thresholdCents` | integer | always | Charge when the balance falls below this. 0 to 9007199254740991. |
| `autoRecharge.amountCents` | integer | always | Whole cents. 0 to 9007199254740991. |
| `autoRecharge.capCents` | integer | always | Never charge more than this in total through the rule. 0 to 9007199254740991. |
| `autoRecharge.pending` | boolean | always |  |
| `autoRecharge.failedAt` | string (ISO 8601) or null | always |  |
| `autoRecharge.hasPaymentMethod` | boolean | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `billing-console-only` | A billing change is made in the console by an admin, not with an API key. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 409 | `not-prepaid` | The organization has no credit account; only org creation or an operator's grant starts prepaid credit. |

## POST /v1/billing/portal

A link to the payment portal, where a saved card is changed.

**Auth:** API key with full access, and only through the console as an admin (a plain API key answers `403` with `billing-console-only`). Refused for every agent token (`agent-token-credential`).

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/billing/portal" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the link:

```json
{
  "url": "<url>"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `url` | string | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `billing-console-only` | A billing change is made in the console by an admin, not with an API key. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 409 | `no-customer` | No payment relationship yet; a first top-up creates it. |

## GET /v1/billing/preview

What a period cost, line by line, from the metered usage.

**Auth:** API key with full access (a key with scopes cannot call this route). Every class of agent token may call it.

### Query parameters

| Name | Description |
| --- | --- |
| `from` | Start of the period (ISO 8601). |
| `to` | End of the period (ISO 8601). |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/billing/preview" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the preview:

```json
{
  "orgId": "<orgId>",
  "currency": "EUR",
  "from": "2026-10-21T09:00:00Z",
  "to": "www.example.com",
  "lines": [
    {
      "kind": "machine_running_seconds",
      "unit": "<unit>",
      "quantity": 0,
      "priced": true
    }
  ],
  "pricesDecided": true
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `orgId` | string | always | The organization that owns it. |
| `currency` | `"EUR"` | always |  |
| `from` | string (ISO 8601) | always |  |
| `to` | string (ISO 8601) | always | Another hostname of the same app to redirect to, or `null` to clear the redirect. |
| `lines` | array of object | always | One line per usage kind: quantity, unit, and the amount where a price is set. |
| `total` | number | if set | The sum of the priced lines. at least 0. |
| `pricesDecided` | boolean | always | Whether this answer carries amounts. |
| `pricedFrom` | string (ISO 8601) | if set |  |
| `unpricedReason` | `no-price-list` \| `no-credit-account` \| `before-credit` | if set | If not, why: `no-price-list`, `no-credit-account` or `before-credit`. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/usage

The metered usage events of the organization.

**Auth:** API key with full access (a key with scopes cannot call this route). Every class of agent token may call it.

### Query parameters

| Name | Description |
| --- | --- |
| `from` | Start of the period (ISO 8601). |
| `to` | End of the period (ISO 8601). |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/usage" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the usage list:

```json
{
  "period": {
    "from": "2026-10-21T09:00:00Z",
    "to": "www.example.com"
  },
  "events": [
    {
      "id": "<id>",
      "orgId": "<orgId>",
      "kind": "machine_running_seconds",
      "quantity": 0,
      "at": "2026-10-21T09:00:00Z"
    }
  ],
  "truncated": true,
  "limit": 1
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `period` | object | always |  |
| `period.from` | string (ISO 8601) | always |  |
| `period.to` | string (ISO 8601) | always | Another hostname of the same app to redirect to, or `null` to clear the redirect. |
| `events` | array of object | always |  |
| `truncated` | boolean | always |  |
| `limit` | integer | always | at most 9007199254740991. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/domains/ -->

# Custom domains

> Your own domains on an app: add, check, redirect, remove; prove a whole zone once.

An app answers on `https://<app>.rytiv.app` from the start. A custom domain is added to an app, proven by a DNS record, pointed at Rytiv, and gets its certificate from Rytiv. The answer of every domain route carries the DNS records to set. A zone proven once (`/v1/domains/zones`) covers every name below it without a record of its own. See the guide [Custom domains and TLS](https://docs.rytiv.com/guides/custom-domains.md).

## Endpoints

- [`POST /v1/apps/:name/domains`](#post-v1appsnamedomains): Adds a custom domain to the app and answers the DNS records to set
- [`GET /v1/apps/:name/domains`](#get-v1appsnamedomains): The app's custom domains with their status
- [`POST /v1/apps/:name/domains/:domain/check`](#post-v1appsnamedomainsdomaincheck): Checks the DNS records now instead of waiting for the next automatic check
- [`PUT /v1/apps/:name/domains/:domain/redirect`](#put-v1appsnamedomainsdomainredirect): Redirects this domain (`308`) to another hostname of the same app, or clears the redirect with `to: null`
- [`DELETE /v1/apps/:name/domains/:domain`](#delete-v1appsnamedomainsdomain): Removes the domain from the app
- [`POST /v1/domains/zones`](#post-v1domainszones): Claims a whole zone: proven once, every name below it is yours without a record of its own
- [`GET /v1/domains/zones`](#get-v1domainszones): Your zones
- [`GET /v1/domains/zones/:zone`](#get-v1domainszoneszone): One zone with its status and the records to set
- [`POST /v1/domains/zones/:zone/check`](#post-v1domainszoneszonecheck): Checks the zone's records now
- [`DELETE /v1/domains/zones/:zone`](#delete-v1domainszoneszone): Releases the zone

## POST /v1/apps/:name/domains

Adds a custom domain to the app and answers the DNS records to set.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `AddDomainRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | required | The domain, for example `www.example.com`. Wildcards are not accepted. 1 to 253 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/domains" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"www.example.com"}'
```

### Response

`201` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `mail-domain` | The name is a sending domain and cannot become an app domain. |
| 409 | `shadows-default-address` | The domain is the default address of an app and cannot be a custom domain. |

## GET /v1/apps/:name/domains

The app's custom domains with their status.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/domains" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/apps/:name/domains/:domain/check

Checks the DNS records now instead of waiting for the next automatic check.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `domain` | The domain, as added. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/domains/<domain>/check" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `queued` and the fields of the object the handler builds.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## PUT /v1/apps/:name/domains/:domain/redirect

Redirects this domain (`308`) to another hostname of the same app, or clears the redirect with `to: null`.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `domain` | The domain, as added. |

### Request body

JSON, the shape `SetDomainRedirectRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `to` | string or null | required | Another hostname of the same app to redirect to, or `null` to clear the redirect. |

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/apps/<name>/domains/<domain>/redirect" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"www.example.com"}'
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/apps/:name/domains/:domain

Removes the domain from the app.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `domain` | The domain, as added. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/apps/<name>/domains/<domain>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/domains/zones

Claims a whole zone: proven once, every name below it is yours without a record of its own.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Request body

JSON, the shape `AddZoneRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `zone` | string | required | The zone, for example `example.com`. 1 to 253 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/domains/zones" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com"}'
```

### Response

`200` or `201` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 503 | `zones-unavailable` |  |

## GET /v1/domains/zones

Your zones.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/domains/zones" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of zones, each:

```json
[
  {
    "zone": "example.com",
    "orgId": "<orgId>",
    "status": "pending_dns",
    "acmeLabel": "<acmeLabel>",
    "attempts": 0,
    "createdAt": "2026-10-21T09:00:00Z"
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `zone` | string | always | The zone, for example `example.com`. |
| `orgId` | string | always | The organization that owns it. |
| `status` | `pending_dns` \| `verified` \| `cert_issued` \| `error` | always |  |
| `error` | string or null | if set |  |
| `acmeLabel` | string | always |  |
| `certNotAfter` | string (ISO 8601) | if set |  |
| `certIssuedAt` | string (ISO 8601) | if set |  |
| `verifiedAt` | string (ISO 8601) | if set |  |
| `lastCheckedAt` | string (ISO 8601) | if set |  |
| `attempts` | integer | always | 0 to 9007199254740991, default `0`. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `dns` | object | if set |  |
| `dns.acme` | object | always |  |
| `dns.point` | object | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/domains/zones/:zone

One zone with its status and the records to set.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `zone` | The zone, as claimed. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/domains/zones/<zone>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the zone:

```json
{
  "zone": "example.com",
  "orgId": "<orgId>",
  "status": "pending_dns",
  "acmeLabel": "<acmeLabel>",
  "attempts": 0,
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `zone` | string | always | The zone, for example `example.com`. |
| `orgId` | string | always | The organization that owns it. |
| `status` | `pending_dns` \| `verified` \| `cert_issued` \| `error` | always |  |
| `error` | string or null | if set |  |
| `acmeLabel` | string | always |  |
| `certNotAfter` | string (ISO 8601) | if set |  |
| `certIssuedAt` | string (ISO 8601) | if set |  |
| `verifiedAt` | string (ISO 8601) | if set |  |
| `lastCheckedAt` | string (ISO 8601) | if set |  |
| `attempts` | integer | always | 0 to 9007199254740991, default `0`. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `dns` | object | if set |  |
| `dns.acme` | object | always |  |
| `dns.point` | object | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/domains/zones/:zone/check

Checks the zone's records now.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `zone` | The zone, as claimed. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/domains/zones/<zone>/check" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `queued` and the fields of the object the handler builds.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/domains/zones/:zone

Releases the zone.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `zone` | The zone, as claimed. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/domains/zones/<zone>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `zone-in-use` |  |

---

<!-- API reference: https://docs.rytiv.com/reference/api/cron-and-jobs/ -->

# Cron and jobs

> Schedules that call a path of an app or run a command on a machine of their own, their run history, and one-off jobs.

A schedule runs something of an app on a cron expression: either it wakes the app and calls a path (signed, so the app can verify the call), or it runs a command on a machine of its own, sized as you say. A job is the same machine without a schedule: one command, run once, with its exit code and output kept. See the guide [Cron and jobs](https://docs.rytiv.com/guides/cron-and-jobs.md).

## Endpoints

- [`POST /v1/apps/:name/schedules`](#post-v1appsnameschedules): Adds a schedule: a cron expression and either a `path` the app is woken for, or a `command` run on a machine of its own
- [`GET /v1/apps/:name/schedules`](#get-v1appsnameschedules): The app's schedules with their next slot and last run
- [`GET /v1/apps/:name/schedules/:id`](#get-v1appsnameschedulesid): One schedule
- [`PATCH /v1/apps/:name/schedules/:id`](#patch-v1appsnameschedulesid): Changes a schedule. The kind of target (path or command) stays
- [`DELETE /v1/apps/:name/schedules/:id`](#delete-v1appsnameschedulesid): Removes the schedule and its run history
- [`GET /v1/apps/:name/schedules/:id/runs`](#get-v1appsnameschedulesidruns): The schedule's runs, newest first
- [`POST /v1/apps/:name/schedules/:id/runs`](#post-v1appsnameschedulesidruns): Runs the schedule now, outside its expression
- [`POST /v1/apps/:name/jobs`](#post-v1appsnamejobs): Runs one command on a machine of its own with the app's image and environment. Answers `202` with the job
- [`GET /v1/apps/:name/jobs`](#get-v1appsnamejobs): The app's jobs
- [`GET /v1/jobs/:id`](#get-v1jobsid): One job with its state, exit code and output
- [`DELETE /v1/jobs/:id`](#delete-v1jobsid): Cancels a job that still runs

## POST /v1/apps/:name/schedules

Adds a schedule: a cron expression and either a `path` the app is woken for, or a `command` run on a machine of its own.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `ScheduleCreate` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schedule` | string | required | A cron expression with five fields, or `@hourly`, `@daily` and the like. 1 to 200 characters. |
| `timezone` | string | optional | The IANA time zone the expression is read in. 1 to 64 characters, default `"UTC"`. |
| `path` | string | optional | The app is woken and this path is called. 1 to 2048 characters. |
| `method` | `GET` \| `POST` | optional | With `path`: `GET` (default) or `POST`. |
| `command` | array of string | optional | Runs on a machine of its own, as an argument list. 1 to 64 items. |
| `timeoutSec` | integer | optional | The deadline in seconds: per attempt for a path, for the whole run for a command. 1 to 9007199254740991. |
| `memoryMb` | integer | optional | Memory in MB. -9007199254740991 to 9007199254740991. |
| `vcpus` | integer | optional | Virtual CPUs. -9007199254740991 to 9007199254740991. |
| `enabled` | boolean | optional | `false` creates the schedule paused. default `true`. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/schedules" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"schedule":"*/15 * * * *"}'
```

### Response

`201` with the schedule:

```json
{
  "id": "<id>",
  "app": "<app>",
  "schedule": "*/15 * * * *",
  "timezone": "Europe/Berlin",
  "timeoutSec": -9007199254740991,
  "enabled": true,
  "createdAt": "2026-10-21T09:00:00Z",
  "updatedAt": "2026-10-21T09:00:00Z",
  "secretCreated": true
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always |  |
| `app` | string | always |  |
| `schedule` | string | always | A cron expression with five fields, or `@hourly`, `@daily` and the like. |
| `timezone` | string | always | The IANA time zone the expression is read in. |
| `path` | string | if set | The app is woken and this path is called. |
| `method` | `GET` \| `POST` | if set | With `path`: `GET` (default) or `POST`. |
| `command` | array of string | if set | Runs on a machine of its own, as an argument list. |
| `timeoutSec` | integer | always | The deadline in seconds: per attempt for a path, for the whole run for a command. -9007199254740991 to 9007199254740991. |
| `memoryMb` | integer | if set | Memory in MB. -9007199254740991 to 9007199254740991. |
| `vcpus` | integer | if set | Virtual CPUs. -9007199254740991 to 9007199254740991. |
| `enabled` | boolean | always | `false` creates the schedule paused. |
| `nextRunAt` | string (ISO 8601) | if set |  |
| `lastRun` | object | if set |  |
| `lastRun.id` | string | always |  |
| `lastRun.schedule` | string | always | A cron expression with five fields, or `@hourly`, `@daily` and the like. |
| `lastRun.app` | string | always |  |
| `lastRun.scheduledFor` | string (ISO 8601) | always |  |
| `lastRun.trigger` | `schedule` \| `manual` | always |  |
| `lastRun.state` | `running` \| `succeeded` \| `failed` \| `skipped` \| `missed` | always |  |
| `lastRun.attempts` | array of object | always |  |
| `lastRun.statusCode` | integer | if set | -9007199254740991 to 9007199254740991. |
| `lastRun.error` | string | if set |  |
| `lastRun.job` | string | if set |  |
| `lastRun.exitCode` | integer | if set | -9007199254740991 to 9007199254740991. |
| `lastRun.missedSlots` | integer | always | 0 to 9007199254740991. |
| `lastRun.startedAt` | string (ISO 8601) | if set |  |
| `lastRun.finishedAt` | string (ISO 8601) | if set |  |
| `lastRun.durationMs` | integer | if set | 0 to 9007199254740991. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `updatedAt` | string (ISO 8601) | always |  |
| `secretCreated` | boolean | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 410 | `gone` | The object existed and is gone. |

## GET /v1/apps/:name/schedules

The app's schedules with their next slot and last run.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/schedules" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of schedules, each:

```json
[
  {
    "id": "<id>",
    "app": "<app>",
    "schedule": "*/15 * * * *",
    "timezone": "Europe/Berlin",
    "timeoutSec": -9007199254740991,
    "enabled": true,
    "createdAt": "2026-10-21T09:00:00Z",
    "updatedAt": "2026-10-21T09:00:00Z"
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The schedule's id. |
| `app` | string | always |  |
| `schedule` | string | always | A cron expression with five fields, or `@hourly`, `@daily` and the like. |
| `timezone` | string | always | The IANA time zone the expression is read in. |
| `path` | string | if set | The app is woken and this path is called. |
| `method` | `GET` \| `POST` | if set | With `path`: `GET` (default) or `POST`. |
| `command` | array of string | if set | Runs on a machine of its own, as an argument list. |
| `timeoutSec` | integer | always | The deadline in seconds: per attempt for a path, for the whole run for a command. -9007199254740991 to 9007199254740991. |
| `memoryMb` | integer | if set | Memory in MB. -9007199254740991 to 9007199254740991. |
| `vcpus` | integer | if set | Virtual CPUs. -9007199254740991 to 9007199254740991. |
| `enabled` | boolean | always | `false` creates the schedule paused. |
| `nextRunAt` | string (ISO 8601) | if set | The next slot. |
| `lastRun` | object | if set | The last run, if any. |
| `lastRun.id` | string | always |  |
| `lastRun.schedule` | string | always | A cron expression with five fields, or `@hourly`, `@daily` and the like. |
| `lastRun.app` | string | always |  |
| `lastRun.scheduledFor` | string (ISO 8601) | always |  |
| `lastRun.trigger` | `schedule` \| `manual` | always |  |
| `lastRun.state` | `running` \| `succeeded` \| `failed` \| `skipped` \| `missed` | always |  |
| `lastRun.attempts` | array of object | always |  |
| `lastRun.statusCode` | integer | if set | -9007199254740991 to 9007199254740991. |
| `lastRun.error` | string | if set |  |
| `lastRun.job` | string | if set |  |
| `lastRun.exitCode` | integer | if set | -9007199254740991 to 9007199254740991. |
| `lastRun.missedSlots` | integer | always | 0 to 9007199254740991. |
| `lastRun.startedAt` | string (ISO 8601) | if set |  |
| `lastRun.finishedAt` | string (ISO 8601) | if set |  |
| `lastRun.durationMs` | integer | if set | 0 to 9007199254740991. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `updatedAt` | string (ISO 8601) | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/apps/:name/schedules/:id

One schedule.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `id` | The object's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/schedules/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the schedule:

```json
{
  "id": "<id>",
  "app": "<app>",
  "schedule": "*/15 * * * *",
  "timezone": "Europe/Berlin",
  "timeoutSec": -9007199254740991,
  "enabled": true,
  "createdAt": "2026-10-21T09:00:00Z",
  "updatedAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The schedule's id. |
| `app` | string | always |  |
| `schedule` | string | always | A cron expression with five fields, or `@hourly`, `@daily` and the like. |
| `timezone` | string | always | The IANA time zone the expression is read in. |
| `path` | string | if set | The app is woken and this path is called. |
| `method` | `GET` \| `POST` | if set | With `path`: `GET` (default) or `POST`. |
| `command` | array of string | if set | Runs on a machine of its own, as an argument list. |
| `timeoutSec` | integer | always | The deadline in seconds: per attempt for a path, for the whole run for a command. -9007199254740991 to 9007199254740991. |
| `memoryMb` | integer | if set | Memory in MB. -9007199254740991 to 9007199254740991. |
| `vcpus` | integer | if set | Virtual CPUs. -9007199254740991 to 9007199254740991. |
| `enabled` | boolean | always | `false` creates the schedule paused. |
| `nextRunAt` | string (ISO 8601) | if set | The next slot. |
| `lastRun` | object | if set | The last run, if any. |
| `lastRun.id` | string | always |  |
| `lastRun.schedule` | string | always | A cron expression with five fields, or `@hourly`, `@daily` and the like. |
| `lastRun.app` | string | always |  |
| `lastRun.scheduledFor` | string (ISO 8601) | always |  |
| `lastRun.trigger` | `schedule` \| `manual` | always |  |
| `lastRun.state` | `running` \| `succeeded` \| `failed` \| `skipped` \| `missed` | always |  |
| `lastRun.attempts` | array of object | always |  |
| `lastRun.statusCode` | integer | if set | -9007199254740991 to 9007199254740991. |
| `lastRun.error` | string | if set |  |
| `lastRun.job` | string | if set |  |
| `lastRun.exitCode` | integer | if set | -9007199254740991 to 9007199254740991. |
| `lastRun.missedSlots` | integer | always | 0 to 9007199254740991. |
| `lastRun.startedAt` | string (ISO 8601) | if set |  |
| `lastRun.finishedAt` | string (ISO 8601) | if set |  |
| `lastRun.durationMs` | integer | if set | 0 to 9007199254740991. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `updatedAt` | string (ISO 8601) | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## PATCH /v1/apps/:name/schedules/:id

Changes a schedule. The kind of target (path or command) stays.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `id` | The object's id. |

### Request body

JSON, the shape `SchedulePatch` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schedule` | string | optional | A cron expression with five fields, or `@hourly`, `@daily` and the like. 1 to 200 characters. |
| `timezone` | string | optional | The IANA time zone the expression is read in. 1 to 64 characters. |
| `path` | string | optional | The app is woken and this path is called. 1 to 2048 characters. |
| `method` | `GET` \| `POST` | optional | With `path`: `GET` (default) or `POST`. |
| `command` | array of string | optional | Runs on a machine of its own, as an argument list. 1 to 64 items. |
| `timeoutSec` | integer | optional | The deadline in seconds: per attempt for a path, for the whole run for a command. 1 to 9007199254740991. |
| `memoryMb` | integer or null | optional | Memory in MB. |
| `vcpus` | integer or null | optional | Virtual CPUs. |
| `enabled` | boolean | optional | `false` creates the schedule paused. |

### Example request

```bash
curl -X PATCH "https://api.rytiv.app/v1/apps/<name>/schedules/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"schedule":"*/15 * * * *"}'
```

### Response

`200` with the schedule:

```json
{
  "id": "<id>",
  "app": "<app>",
  "schedule": "*/15 * * * *",
  "timezone": "Europe/Berlin",
  "timeoutSec": -9007199254740991,
  "enabled": true,
  "createdAt": "2026-10-21T09:00:00Z",
  "updatedAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The schedule's id. |
| `app` | string | always |  |
| `schedule` | string | always | A cron expression with five fields, or `@hourly`, `@daily` and the like. |
| `timezone` | string | always | The IANA time zone the expression is read in. |
| `path` | string | if set | The app is woken and this path is called. |
| `method` | `GET` \| `POST` | if set | With `path`: `GET` (default) or `POST`. |
| `command` | array of string | if set | Runs on a machine of its own, as an argument list. |
| `timeoutSec` | integer | always | The deadline in seconds: per attempt for a path, for the whole run for a command. -9007199254740991 to 9007199254740991. |
| `memoryMb` | integer | if set | Memory in MB. -9007199254740991 to 9007199254740991. |
| `vcpus` | integer | if set | Virtual CPUs. -9007199254740991 to 9007199254740991. |
| `enabled` | boolean | always | `false` creates the schedule paused. |
| `nextRunAt` | string (ISO 8601) | if set | The next slot. |
| `lastRun` | object | if set | The last run, if any. |
| `lastRun.id` | string | always |  |
| `lastRun.schedule` | string | always | A cron expression with five fields, or `@hourly`, `@daily` and the like. |
| `lastRun.app` | string | always |  |
| `lastRun.scheduledFor` | string (ISO 8601) | always |  |
| `lastRun.trigger` | `schedule` \| `manual` | always |  |
| `lastRun.state` | `running` \| `succeeded` \| `failed` \| `skipped` \| `missed` | always |  |
| `lastRun.attempts` | array of object | always |  |
| `lastRun.statusCode` | integer | if set | -9007199254740991 to 9007199254740991. |
| `lastRun.error` | string | if set |  |
| `lastRun.job` | string | if set |  |
| `lastRun.exitCode` | integer | if set | -9007199254740991 to 9007199254740991. |
| `lastRun.missedSlots` | integer | always | 0 to 9007199254740991. |
| `lastRun.startedAt` | string (ISO 8601) | if set |  |
| `lastRun.finishedAt` | string (ISO 8601) | if set |  |
| `lastRun.durationMs` | integer | if set | 0 to 9007199254740991. |
| `createdAt` | string (ISO 8601) | always | When it was created. |
| `updatedAt` | string (ISO 8601) | always |  |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/apps/:name/schedules/:id

Removes the schedule and its run history.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `id` | The object's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/apps/<name>/schedules/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/apps/:name/schedules/:id/runs

The schedule's runs, newest first.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `id` | The object's id. |

### Query parameters

| Name | Description |
| --- | --- |
| `before` |  |
| `limit` | How many entries, at most. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/schedules/<id>/runs" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of runs, each:

```json
[
  {
    "id": "<id>",
    "schedule": "*/15 * * * *",
    "app": "<app>",
    "scheduledFor": "2026-10-21T09:00:00Z",
    "trigger": "schedule",
    "state": "running",
    "attempts": [
      {
        "attempt": 1,
        "startedAt": "2026-10-21T09:00:00Z",
        "durationMs": 0
      }
    ],
    "missedSlots": 0
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always |  |
| `schedule` | string | always | A cron expression with five fields, or `@hourly`, `@daily` and the like. |
| `app` | string | always |  |
| `scheduledFor` | string (ISO 8601) | always |  |
| `trigger` | `schedule` \| `manual` | always |  |
| `state` | `running` \| `succeeded` \| `failed` \| `skipped` \| `missed` | always | `running`, `succeeded`, `failed`, `skipped` (a slot that came while the previous run was still going) or `missed`. |
| `attempts` | array of object | always |  |
| `statusCode` | integer | if set | -9007199254740991 to 9007199254740991. |
| `error` | string | if set |  |
| `job` | string | if set |  |
| `exitCode` | integer | if set | -9007199254740991 to 9007199254740991. |
| `missedSlots` | integer | always | 0 to 9007199254740991. |
| `startedAt` | string (ISO 8601) | if set |  |
| `finishedAt` | string (ISO 8601) | if set |  |
| `durationMs` | integer | if set | 0 to 9007199254740991. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/apps/:name/schedules/:id/runs

Runs the schedule now, outside its expression.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `id` | The object's id. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/schedules/<id>/runs" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`202` (accepted, the work continues) with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `run-in-progress` |  |
| 410 | `gone` | The object existed and is gone. |

## POST /v1/apps/:name/jobs

Runs one command on a machine of its own with the app's image and environment. Answers `202` with the job.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `JobCreate` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `command` | array of string | required | The command as an argument list, run with the app's image and environment. 1 to 64 items. |
| `env` | object of string | optional | More environment for this job. |
| `timeoutSec` | integer | optional | Seconds before the job is ended. 1 to 3600, default `900`. |
| `links` | array of string | optional | Apps this job's machine may reach over the private network. 0 to 8 items. |
| `build` | string | optional | Run a specific build of the app instead of the one that is live. |
| `memoryMb` | integer | optional | Memory of the job's machine. Default: the app's. 128 to 16384. |
| `vcpus` | integer | optional | vCPUs of the job's machine. Default: the app's. 1 to 16. |
| `class` | any | optional | A named size instead of `vcpus`; the two must not contradict each other. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/jobs" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":["<command>"]}'
```

### Response

`202` with the job:

```json
{
  "id": "<id>",
  "app": "my-app",
  "state": "queued",
  "exitCode": 0,
  "output": "<output>",
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The job's id. |
| `app` | string | always |  |
| `state` | `queued` \| `running` \| `done` \| `failed` \| `timeout` | always | `queued`, `running`, `done` (it ran; see `exitCode`), `failed` (it did not run to the end) or `timeout`. |
| `exitCode` | integer or null | always | The command's exit code once it ran; `null` otherwise. |
| `output` | string | always | What it wrote, cut at 1 MiB. |
| `build` | string | if set | The build it ran. |
| `machine` | string | if set | The machine it ran on. |
| `command` | array of string | if set | The command as given. |
| `startedAt` | string (ISO 8601) | if set | When the command started. |
| `finishedAt` | string (ISO 8601) | if set | When it ended. |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/apps/:name/jobs

The app's jobs.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Query parameters

| Name | Description |
| --- | --- |
| `before` |  |
| `limit` | How many entries, at most. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/jobs" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a list of jobs, each:

```json
[
  {
    "id": "<id>",
    "app": "my-app",
    "state": "queued",
    "exitCode": 0,
    "output": "<output>",
    "createdAt": "2026-10-21T09:00:00Z"
  }
]
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The job's id. |
| `app` | string | always |  |
| `state` | `queued` \| `running` \| `done` \| `failed` \| `timeout` | always | `queued`, `running`, `done` (it ran; see `exitCode`), `failed` (it did not run to the end) or `timeout`. |
| `exitCode` | integer or null | always | The command's exit code once it ran; `null` otherwise. |
| `output` | string | always | What it wrote, cut at 1 MiB. |
| `build` | string | if set | The build it ran. |
| `machine` | string | if set | The machine it ran on. |
| `command` | array of string | if set | The command as given. |
| `startedAt` | string (ISO 8601) | if set | When the command started. |
| `finishedAt` | string (ISO 8601) | if set | When it ended. |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/jobs/:id

One job with its state, exit code and output.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The job's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/jobs/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with the job:

```json
{
  "id": "<id>",
  "app": "my-app",
  "state": "queued",
  "exitCode": 0,
  "output": "<output>",
  "createdAt": "2026-10-21T09:00:00Z"
}
```

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The job's id. |
| `app` | string | always |  |
| `state` | `queued` \| `running` \| `done` \| `failed` \| `timeout` | always | `queued`, `running`, `done` (it ran; see `exitCode`), `failed` (it did not run to the end) or `timeout`. |
| `exitCode` | integer or null | always | The command's exit code once it ran; `null` otherwise. |
| `output` | string | always | What it wrote, cut at 1 MiB. |
| `build` | string | if set | The build it ran. |
| `machine` | string | if set | The machine it ran on. |
| `command` | array of string | if set | The command as given. |
| `startedAt` | string (ISO 8601) | if set | When the command started. |
| `finishedAt` | string (ISO 8601) | if set | When it ended. |
| `createdAt` | string (ISO 8601) | always | When it was created. |

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/jobs/:id

Cancels a job that still runs.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The job's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/jobs/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/protection-and-network/ -->

# Protection and network

> Who may open an app (password, signed links), what its machines may reach, and public UDP endpoints.

By default an app is public. Protection puts it behind a password or behind signed links that you hand out; the network policy says what the app's machines may reach on the way out; a UDP endpoint gives one machine a public UDP port.

## Endpoints

- [`GET /v1/apps/:name/protection`](#get-v1appsnameprotection): How the app is protected: public, password, or signed links
- [`PUT /v1/apps/:name/protection`](#put-v1appsnameprotection): Sets the protection mode
- [`POST /v1/apps/:name/protection/rotate`](#post-v1appsnameprotectionrotate): Rotates the password or signing secret
- [`POST /v1/apps/:name/protection/links`](#post-v1appsnameprotectionlinks): Creates a signed link that opens the app for a while
- [`DELETE /v1/apps/:name/protection/links/:id`](#delete-v1appsnameprotectionlinksid): Revokes a signed link
- [`POST /v1/apps/:name/protection/tokens`](#post-v1appsnameprotectiontokens): Creates an access token for a protected app
- [`GET /v1/apps/:name/policy/network`](#get-v1appsnamepolicynetwork): What the app's machines may reach on the way out
- [`PUT /v1/apps/:name/policy/network`](#put-v1appsnamepolicynetwork): Sets that policy
- [`GET /v1/apps/:name/udp`](#get-v1appsnameudp): The app's public UDP endpoints
- [`POST /v1/apps/:name/udp`](#post-v1appsnameudp): Requests a public UDP port for the app. The port is assigned by the platform
- [`DELETE /v1/apps/:name/udp/:id`](#delete-v1appsnameudpid): Releases a UDP endpoint

## GET /v1/apps/:name/protection

How the app is protected: public, password, or signed links.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/protection" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## PUT /v1/apps/:name/protection

Sets the protection mode.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `SetProtectionRequest` of the contract.

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/apps/<name>/protection" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/apps/:name/protection/rotate

Rotates the password or signing secret.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/protection/rotate" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `not-protected` |  |

## POST /v1/apps/:name/protection/links

Creates a signed link that opens the app for a while.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `CreateAccessLinkRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | required | 1 to 64 characters. |
| `expiresAt` | string (ISO 8601) | optional | When the copy is deleted (a moment). Not together with `ttlSeconds`. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/protection/links" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"before-migration"}'
```

### Response

`201` with a JSON object carrying `url` and the fields of the object the handler builds.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `not-protected` |  |

## DELETE /v1/apps/:name/protection/links/:id

Revokes a signed link.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `id` | The object's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/apps/<name>/protection/links/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/apps/:name/protection/tokens

Creates an access token for a protected app.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `CreateAccessTokenRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ttlSeconds` | integer | optional | Lifetime from now, in seconds. 1 to 86400. |
| `sub` | string | optional | 1 to 256 characters. |
| `next` | string | optional | at most 512 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/protection/tokens" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":1}'
```

### Response

`201` with a JSON object carrying `token`, `expiresAt`, `url`, `header`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `not-signed` |  |

## GET /v1/apps/:name/policy/network

What the app's machines may reach on the way out.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/policy/network" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## PUT /v1/apps/:name/policy/network

Sets that policy.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `PutNetworkPolicyRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bandwidthMbit` | integer or null | required |  |
| `newConnectionsPerMinute` | integer or null | required |  |
| `reason` | string | optional | at most 500 characters. |

### Example request

```bash
curl -X PUT "https://api.rytiv.app/v1/apps/<name>/policy/network" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bandwidthMbit":1,"newConnectionsPerMinute":1}'
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/apps/:name/udp

The app's public UDP endpoints.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/apps/<name>/udp" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/apps/:name/udp

Requests a public UDP port for the app. The port is assigned by the platform.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |

### Request body

JSON, the shape `CreateUdpEndpointRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `targetPort` | integer | optional | 1 to 65535. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/apps/<name>/udp" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetPort":1}'
```

### Response

`201` with a JSON object carrying `host`, `address`, `note` and the fields of the object the handler builds.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/apps/:name/udp/:id

Releases a UDP endpoint.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `name` | The app's name. |
| `id` | The object's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/apps/<name>/udp/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/mail/ -->

# Mail

> Send mail from your own domains, read the delivery log, receive inbound mail, and manage suppressions.

Rytiv sends mail from domains you prove (SPF, DKIM and a verification record are shown by the domain routes) and keeps a log per message. A key with the scope `mail:send` or `mail:send:<domain>` may send and nothing else.

## Endpoints

- [`POST /v1/emails`](#post-v1emails): Sends a message from one of the organization's proven domains
- [`GET /v1/emails`](#get-v1emails): The delivery log
- [`GET /v1/emails/:id`](#get-v1emailsid): One message with its deliveries
- [`GET /v1/mail/domains`](#get-v1maildomains): The sending domains and their status
- [`POST /v1/mail/domains`](#post-v1maildomains): Adds a sending domain and answers the records to set
- [`GET /v1/mail/domains/:domain`](#get-v1maildomainsdomain): One sending domain
- [`POST /v1/mail/domains/:domain/verify`](#post-v1maildomainsdomainverify): Checks the domain's records now
- [`DELETE /v1/mail/domains/:domain`](#delete-v1maildomainsdomain): Removes a sending domain
- [`POST /v1/mail/domains/:domain/inbound/routes`](#post-v1maildomainsdomaininboundroutes): Routes inbound mail for an address of the domain
- [`DELETE /v1/mail/domains/:domain/inbound/routes/:id`](#delete-v1maildomainsdomaininboundroutesid): Removes an inbound route
- [`GET /v1/mail/inbound`](#get-v1mailinbound): Inbound messages
- [`GET /v1/mail/inbound/:id`](#get-v1mailinboundid): One inbound message
- [`GET /v1/mail/suppressions`](#get-v1mailsuppressions): Addresses Rytiv no longer sends to (bounces, complaints)
- [`DELETE /v1/mail/suppressions/:address`](#delete-v1mailsuppressionsaddress): Removes an address from the suppression list

## POST /v1/emails

Sends a message from one of the organization's proven domains.

**Auth:** API key with full access or the scope `mail:send` (or `mail:send:<domain>` for the sending domain). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Request body

JSON, the shape `SendEmailRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | required | 3 to 400 characters. |
| `to` | string | required | Another hostname of the same app to redirect to, or `null` to clear the redirect. 3 to 254 characters. |
| `subject` | string | required | 1 to 998 characters. |
| `text` | string | optional | at most 1000000 characters. |
| `html` | string | optional | The page as HTML. at most 1000000 characters. |
| `replyTo` | string | optional | 3 to 254 characters. |
| `headers` | object | optional |  |
| `headers.List-Unsubscribe` | string | optional |  |
| `headers.List-Unsubscribe-Post` | string | optional |  |
| `headers.In-Reply-To` | string | optional |  |
| `headers.References` | string | optional |  |
| `attachments` | array of object | optional | 0 to 10 items. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/emails" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"<from>","to":"www.example.com","subject":"<subject>"}'
```

### Response

`202` with a JSON object carrying `status`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/emails

The delivery log.

**Auth:** API key with full access or the scope `read`. An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | How many entries, at most. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/emails" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/emails/:id

One message with its deliveries.

**Auth:** API key with full access or the scope `read`. An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/emails/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `events` and the fields of the object the handler builds.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/mail/domains

The sending domains and their status.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/mail/domains" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## POST /v1/mail/domains

Adds a sending domain and answers the records to set.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Request body

JSON, the shape `AddMailDomainRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | required | The domain, for example `www.example.com`. Wildcards are not accepted. 1 to 253 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/mail/domains" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"www.example.com"}'
```

### Response

`201` with a JSON object carrying `appDomain`, `records` and the fields of the object the handler builds.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 400 | `name-reserved` | The platform keeps this name (for example `api`, `console`, `docs`, `www`, and every name that is `rytiv` or starts with `rytiv-`). |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 409 | `already-exists` | You already have it; an idempotent create may treat this as done. |
| 409 | `name-taken` | The name is used somewhere on Rytiv (an app, a database, a volume or a bucket). |
| 429 | `too-many-pending` |  |

## GET /v1/mail/domains/:domain

One sending domain.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `domain` | The domain, as added. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/mail/domains/<domain>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `appDomain`, `records`, `inbound` and the fields of the object the handler builds.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/mail/domains/:domain/verify

Checks the domain's records now.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `domain` | The domain, as added. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/mail/domains/<domain>/verify" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `domain`, `status`, `checks`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/mail/domains/:domain

Removes a sending domain.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `domain` | The domain, as added. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/mail/domains/<domain>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `domain`, `removed`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## POST /v1/mail/domains/:domain/inbound/routes

Routes inbound mail for an address of the domain.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `domain` | The domain, as added. |

### Request body

JSON, the shape `AddMailInboundRouteRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | string | required | 1 to 320 characters. |
| `action` | `store` | optional | default `"store"`. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/mail/domains/<domain>/inbound/routes" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address":"<address>"}'
```

### Response

`201` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/mail/domains/:domain/inbound/routes/:id

Removes an inbound route.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `domain` | The domain, as added. |
| `id` | The object's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/mail/domains/<domain>/inbound/routes/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/mail/inbound

Inbound messages.

**Auth:** API key with full access or the scope `read`. An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | How many entries, at most. |
| `domain` |  |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/mail/inbound" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/mail/inbound/:id

One inbound message.

**Auth:** API key with full access or the scope `read`. An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/mail/inbound/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON object carrying `raw`, `text` and the fields of the object the handler builds.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/mail/suppressions

Addresses Rytiv no longer sends to (bounces, complaints).

**Auth:** API key with full access or the scope `read`. An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/mail/suppressions" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## DELETE /v1/mail/suppressions/:address

Removes an address from the suppression list.

**Auth:** API key with full access (a key with scopes cannot call this route). An agent token of class `sandbox` or `twin` may call it; class `production` is refused (`agent-token-production-readonly`).

### Path parameters

| Name | Description |
| --- | --- |
| `address` | The e-mail address. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/mail/suppressions/<address>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/webhooks/ -->

# Webhooks

> Be called when something happens in your organization, and read the deliveries.

A webhook is a URL Rytiv calls for events of your organization. Each delivery is recorded and can be read back.

## Endpoints

- [`POST /v1/webhooks`](#post-v1webhooks): Registers a webhook URL
- [`GET /v1/webhooks`](#get-v1webhooks): The organization's webhooks
- [`GET /v1/webhooks/:id`](#get-v1webhooksid): One webhook
- [`GET /v1/webhooks/:id/deliveries`](#get-v1webhooksiddeliveries): Its deliveries with their status
- [`DELETE /v1/webhooks/:id`](#delete-v1webhooksid): Removes the webhook

## POST /v1/webhooks

Registers a webhook URL.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `CreateWebhookRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | required | 1 to 2048 characters. |
| `events` | array of `email.sent` \| `email.delivered` \| `email.delivery_delayed` \| `email.bounced` \| `email.complained` \| `email.failed` \| `email.received` | required | 1 to any number of items. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/webhooks" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"<url>","events":["email.sent"]}'
```

### Response

`201` with a JSON object carrying `secret` and the fields of the object the handler builds.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/webhooks

The organization's webhooks.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/webhooks" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/webhooks/:id

One webhook.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The webhook's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/webhooks/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/webhooks/:id/deliveries

Its deliveries with their status.

**Auth:** API key with full access or the scope `read`. An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | How many entries, at most. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/webhooks/<id>/deliveries" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/webhooks/:id

Removes the webhook.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The webhook's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/webhooks/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/mcp/ -->

# MCP

> The MCP server your coding agent talks to: one endpoint, JSON-RPC over HTTP, the same key as every other route.

`POST /v1/mcp` is the Model Context Protocol server of Rytiv (Streamable HTTP, protocol revision 2026-07-28). Every JSON-RPC message is its own POST; a request is answered with `application/json`, a notification with `202` and no body. There are no sessions. `GET`, `PUT`, `PATCH` and `DELETE` on the path answer `405`.

The tools it offers are on [MCP tools](https://docs.rytiv.com/reference/mcp-tools.md), generated from the server's own table. To connect an agent, see the [quickstart](https://docs.rytiv.com/quickstart.md); a client that cannot carry a key connects through [OAuth](https://docs.rytiv.com/reference/api/oauth.md).

## Endpoints

- [`POST /v1/mcp`](#post-v1mcp): The MCP endpoint: a JSON-RPC message in, its answer out

## POST /v1/mcp

The MCP endpoint: a JSON-RPC message in, its answer out.

**Auth:** API key with full access (a key with scopes cannot call this route). For an agent token, the tool inside the call decides.

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/mcp" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

### Response

`202` (accepted, the work continues) with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

---

<!-- API reference: https://docs.rytiv.com/reference/api/oauth/ -->

# OAuth and device login

> How a hosted MCP client connects without a pasted key, and how the CLI signs in with a code.

Two flows need no key to start. The OAuth 2.1 authorization server of `/v1/mcp` lets a hosted client register itself, send the person to the console to approve, and exchange a code (with PKCE) for an access token and a refresh token; the discovery documents are at `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource/v1/mcp`. The device login is what `ry login` does: it asks for a code, the person confirms it in the console, and the CLI receives a key.

Scopes of the OAuth server: `mcp` and `offline_access`. There are no client secrets; every client is a public client bound to PKCE.

## Endpoints

- [`POST /v1/oauth/register`](#post-v1oauthregister): Registers a public OAuth client (dynamic client registration) and answers its client id. No secret
- [`GET /v1/oauth/authorize`](#get-v1oauthauthorize): Starts an authorization: answers a redirect into the console, where the person approves
- [`POST /v1/oauth/token`](#post-v1oauthtoken): Exchanges an authorization code (with the PKCE verifier) for an access token and a refresh token, or rotates a refresh token
- [`POST /v1/oauth/consent/lookup`](#post-v1oauthconsentlookup): The console reads a pending authorization to show it
- [`POST /v1/oauth/consent/decide`](#post-v1oauthconsentdecide): The console records the person's decision
- [`POST /v1/device/code`](#post-v1devicecode): Starts a device login: answers a device code and a user code to confirm in the console
- [`POST /v1/device/token`](#post-v1devicetoken): The CLI polls here until the login was confirmed, then receives a key

## POST /v1/oauth/register

Registers a public OAuth client (dynamic client registration) and answers its client id. No secret.

**Auth:** No API key: this is an entrance of a login or OAuth flow.

### Request body

JSON, the shape `OAuthClientRegistration` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `redirect_uris` | array of string | required | 1 to 10 items. |
| `client_name` | string | optional | 1 to 120 characters. |
| `token_endpoint_auth_method` | string | optional | at most 40 characters. |
| `grant_types` | array of string | optional | 0 to 4 items. |
| `response_types` | array of string | optional | 0 to 4 items. |
| `scope` | string | optional | at most 200 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"redirect_uris":["<redirect_uri>"]}'
```

### Response

`201` with a JSON object carrying `client_id`, `client_name`, `redirect_uris`, `grant_types`, `response_types`, `token_endpoint_auth_method`, `client_id_issued_at`.

## GET /v1/oauth/authorize

Starts an authorization: answers a redirect into the console, where the person approves.

**Auth:** No API key: this is an entrance of a login or OAuth flow.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/oauth/authorize"
```

### Response

`302` with a JSON body.

## POST /v1/oauth/token

Exchanges an authorization code (with the PKCE verifier) for an access token and a refresh token, or rotates a refresh token.

**Auth:** No API key: this is an entrance of a login or OAuth flow.

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=<code>" \
  --data-urlencode "code_verifier=<verifier>" \
  --data-urlencode "client_id=<client id>" \
  --data-urlencode "redirect_uri=<redirect uri>"
```

### Response

A JSON body on success.

## POST /v1/oauth/consent/lookup

The console reads a pending authorization to show it.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `OAuthConsentLookupRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requestId` | string | required | 1 to 120 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/oauth/consent/lookup" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"<requestId>"}'
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `not-answerable` |  |

## POST /v1/oauth/consent/decide

The console records the person's decision.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `OAuthConsentDecideRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requestId` | string | required | 1 to 120 characters. |
| `approve` | boolean | required |  |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/oauth/consent/decide" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"<requestId>","approve":true}'
```

### Response

`200` with a JSON object carrying `redirectUrl`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |
| 409 | `not-answerable` |  |

## POST /v1/device/code

Starts a device login: answers a device code and a user code to confirm in the console.

**Auth:** No API key: this is an entrance of a login or OAuth flow.

### Request body

JSON, the shape `DeviceCodeRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `client` | string | optional | 1 to 120 characters. |
| `version` | string | optional | 1 to 40 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/device/code" \
  -H "Content-Type: application/json" \
  -d '{"client":"<client>"}'
```

### Response

`201` with a JSON object carrying `deviceCode`, `userCode`, `verificationUri`, `verificationUriComplete`, `expiresIn`, `interval`.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |

## POST /v1/device/token

The CLI polls here until the login was confirmed, then receives a key.

**Auth:** No API key: this is an entrance of a login or OAuth flow.

### Request body

JSON, the shape `DeviceTokenRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deviceCode` | string | required | 1 to 200 characters. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/device/token" \
  -H "Content-Type: application/json" \
  -d '{"deviceCode":"<deviceCode>"}'
```

### Response

`200` with a JSON object carrying `token`, `org`.

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/ -->

# CLI reference

> Every command of ry, the Rytiv CLI, generated from its source.

`ry` is the Rytiv command line. This reference is generated from the CLI's own command definitions, so it lists exactly what `ry --help` and the help of each subcommand show.

## Install

```bash
curl -fsSL https://get.rytiv.com/install.sh | sh
```

The CLI is a Node.js package and needs Node.js 22.6 or newer. The installer checks the published checksum before it installs anything.

## Sign in

```bash
ry login
```

`ry login` shows a code that you confirm in the console. Where nobody can open a browser (CI, a coding agent), use a token instead: `ry login --token <token>`, or set `RYTIV_TOKEN` in the environment. Create tokens with [`ry tokens create`](https://docs.rytiv.com/reference/cli/tokens.md).

## Global options

- `-v, --version`: Output the version number.
- `--json`: Output raw JSON (scripting).
- `-P, --profile <name>`: Which saved login to use for this call (does not change the default).

Every command accepts `--json` for machine-readable output, which is the form to use from scripts and agents.

## Environment

- `RYTIV_TOKEN`: the API token to use for this shell. It takes precedence over a saved login and is never written to disk.
- `RYTIV_ENDPOINT`: the API endpoint to talk to. Without it, the CLI uses `https://api.rytiv.app`.
- `RYTIV_PROFILE`: which saved login to use for this shell (see [`ry profile`](https://docs.rytiv.com/reference/cli/profile.md)).

## Commands

- [`ry apps`](https://docs.rytiv.com/reference/cli/apps.md): Manage apps.
- [`ry attach`](https://docs.rytiv.com/reference/cli/attach.md): Attach a resource to an app: injects the connection URL as a managed secret.
- [`ry billing`](https://docs.rytiv.com/reference/cli/billing.md): What the current usage costs.
- [`ry bucket`](https://docs.rytiv.com/reference/cli/bucket.md): Manage object storage buckets (files for your apps).
- [`ry computer`](https://docs.rytiv.com/reference/cli/computer.md): Links to watch or control a computer VM (images/computer), and who had control.
- [`ry config`](https://docs.rytiv.com/reference/cli/config.md): Manage the project file (rytiv.json).
- [`ry console`](https://docs.rytiv.com/reference/cli/console.md): Start a throwaway machine from this app's last image and get a shell in it.
- [`ry cron`](https://docs.rytiv.com/reference/cli/cron.md): Run something of an app on a schedule: call a path (the app is woken) or run a command on its own machine.
- [`ry deploy`](https://docs.rytiv.com/reference/cli/deploy.md): Deploy from a source directory (--source) or a prebuilt OCI image (--image); reads rytiv.json if present.
- [`ry deploys`](https://docs.rytiv.com/reference/cli/deploys.md): Deployment history of an app: which machines each deploy created and retired.
- [`ry detect`](https://docs.rytiv.com/reference/cli/detect.md): What this project is and what it needs - reads the directory, changes nothing.
- [`ry domains`](https://docs.rytiv.com/reference/cli/domains.md): Attach your own domains to an app.
- [`ry exec`](https://docs.rytiv.com/reference/cli/exec.md): Run a command in a running machine and exit with its exit code (the command goes after --).
- [`ry forward`](https://docs.rytiv.com/reference/cli/forward.md): Forward a local port to a port inside a machine, e.g. `ry forward shop 8080:3000` (no public port needed).
- [`ry git`](https://docs.rytiv.com/reference/cli/git.md): Deploy on push: connect an app to a GitHub repository and see what pushes did.
- [`ry job`](https://docs.rytiv.com/reference/cli/job.md): Run one command in an app's image on a throwaway machine, and get its result.
- [`ry link`](https://docs.rytiv.com/reference/cli/link.md): Let an app reach another app privately at `<target>.internal` (no public door needed).
- [`ry links`](https://docs.rytiv.com/reference/cli/links.md): Show the private app-to-app links in this workspace.
- [`ry login`](https://docs.rytiv.com/reference/cli/login.md): Sign in: shows a code to confirm in the console (--token stays for CI).
- [`ry logs`](https://docs.rytiv.com/reference/cli/logs.md): Stream the console output of an app's machines.
- [`ry machine`](https://docs.rytiv.com/reference/cli/machine.md): Act on a single machine.
- [`ry machines`](https://docs.rytiv.com/reference/cli/machines.md): List machines for an app.
- [`ry mail`](https://docs.rytiv.com/reference/cli/mail.md): Transactional email: sending domains, log, inbox, suppressions.
- [`ry maintenance`](https://docs.rytiv.com/reference/cli/maintenance.md): Switch an app's maintenance mode: the edge answers every request with 503, the machines keep running.
- [`ry new`](https://docs.rytiv.com/reference/cli/new.md): Start a new project from a template - scaffolder plus the part that makes it deploy here.
- [`ry postgres`](https://docs.rytiv.com/reference/cli/postgres.md): Managed Postgres: create, branch, fork, sleep policy (stored; not in force on every host).
- [`ry preview`](https://docs.rytiv.com/reference/cli/preview.md): One preview address per branch - opened by a push, closed by itself.
- [`ry profile`](https://docs.rytiv.com/reference/cli/profile.md): Saved logins for lab, prod, ...
- [`ry protect`](https://docs.rytiv.com/reference/cli/protect.md): Give an app a protected view (password or share link).
- [`ry proxy`](https://docs.rytiv.com/reference/cli/proxy.md): Forward a local port to a machine, e.g. `ry proxy my-db 15432:5432` then `psql -h 127.0.0.1 -p 15432`.
- [`ry releases`](https://docs.rytiv.com/reference/cli/releases.md): The releases of an app: what went out, which one runs, and which ones a rollback can bring back.
- [`ry resource`](https://docs.rytiv.com/reference/cli/resource.md): Manage attachable resources (redis, postgres).
- [`ry rollback`](https://docs.rytiv.com/reference/cli/rollback.md): Deploy an earlier release again, without a rebuild (default: the previous release that went live); secrets, settings, volumes and databases stay as they are.
- [`ry sandbox`](https://docs.rytiv.com/reference/cli/sandbox.md): Short-lived machines for one task each - created from a template, removed at their deadline.
- [`ry secrets`](https://docs.rytiv.com/reference/cli/secrets.md): Manage app secrets.
- [`ry ssh`](https://docs.rytiv.com/reference/cli/ssh.md): An interactive shell in a running machine (over the Rytiv API, no SSH needed); real SSH for IDEs: ry ssh config.
- [`ry ssh-keys`](https://docs.rytiv.com/reference/cli/ssh-keys.md): SSH public keys of this org (for ssh `<app>@ssh.<domain>`).
- [`ry status`](https://docs.rytiv.com/reference/cli/status.md): Overview of all apps and machine states.
- [`ry tokens`](https://docs.rytiv.com/reference/cli/tokens.md): API tokens for CI (org-scoped).
- [`ry unlink`](https://docs.rytiv.com/reference/cli/unlink.md): Remove a private link between two apps.
- [`ry usage`](https://docs.rytiv.com/reference/cli/usage.md): Show metered usage with prices and total.
- [`ry volume`](https://docs.rytiv.com/reference/cli/volume.md): Manage durable volumes (persistent block storage).
- [`ry webhooks`](https://docs.rytiv.com/reference/cli/webhooks.md): Endpoints we call when a message is sent, bounces, is complained about, fails or arrives.
- [`ry whoami`](https://docs.rytiv.com/reference/cli/whoami.md): Show the identity behind the configured token: an org (product token) or the system (operator token).

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/apps/ -->

# ry apps

> Manage apps.

```text
ry apps [options] [command]
```

## Subcommands

### `ry apps list`

List apps.

```text
ry apps list [options]
```

Options:

- `-l, --label <key=value...>`: Only apps carrying this label; repeat for AND, e.g. --label customer=acme --label role=db.

Example:

```bash
ry apps list
ry apps list --label role=api
```

### `ry apps create`

Create an app.

```text
ry apps create [options] <name>
```

Options:

- `-l, --label <key=value...>`: Attach labels right away, e.g. --label customer=acme role=agent (labels are visible in every listing - never put a secret in one - and do not reach the machine).

Example:

```bash
ry apps create web
```

### `ry apps label`

Show or change the labels of an app: key=value sets, key- removes (labels are visible in every listing - never put a secret in one - and do not reach the machine).

```text
ry apps label [options] <name> [changes...]
```

Example:

```bash
ry apps label web role=api team=core
```

### `ry apps protect`

Protect an app: a password, or --link for an invitation-only view.

```text
ry apps protect [options] <name>
```

Options:

- `--link`: No password - the app is reachable only through a share link.
- `--generate`: Generate the password instead of asking, and print it once.
- `--label <label>`: With --link: create the first share link right away.

Example:

```bash
ry apps protect web
```

### `ry apps unprotect`

Make an app public again (alias of `ry protect off`).

```text
ry apps unprotect [options] <name>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry apps unprotect web
```

### `ry apps destroy`

Destroy an app and all its machines.

```text
ry apps destroy [options] <name>
```

Options:

- `-y, --yes`: Confirm without asking (automation, and the way back after consent).

Example:

```bash
ry apps destroy web --yes
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/attach/ -->

# ry attach

> Attach a resource to an app: injects the connection URL as a managed secret.

```text
ry attach [options] <resource>
```

## Options

- `--to <app>`: The app to attach the resource to.

## Example

```bash
ry attach appdb --to web
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/billing/ -->

# ry billing

> What the current usage costs.

```text
ry billing [options] [command]
```

## Subcommands

### `ry billing preview`

Priced preview of the running billing period.

```text
ry billing preview [options]
```

Options:

- `--from <iso>`: Start of the period (default: start of the current UTC month).
- `--to <iso>`: End of the period, exclusive (default: now).

Example:

```bash
ry billing preview
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/bucket/ -->

# ry bucket

> Manage object storage buckets (files for your apps).

```text
ry bucket [options] [command]
```

## Subcommands

### `ry bucket create`

Create a bucket you can attach to an app.

```text
ry bucket create [options] <name>
```

Example:

```bash
ry bucket create my-uploads
```

### `ry bucket check`

Is this bucket name still available in this region?

```text
ry bucket check [options] <name>
```

Example:

```bash
ry bucket check my-uploads
```

### `ry bucket list`

List buckets.

```text
ry bucket list [options]
```

Example:

```bash
ry bucket list
```

### `ry bucket show`

Bucket detail with object count and size.

```text
ry bucket show [options] <name>
```

Example:

```bash
ry bucket show my-uploads
```

### `ry bucket ls`

List objects in a bucket.

```text
ry bucket ls [options] <name>
```

Options:

- `--prefix <prefix>`: Only keys starting with this prefix.
- `--limit <n>`: Objects per page (max 1000). Default: `100`.
- `--cursor <cursor>`: Continue from a previous page.

Example:

```bash
ry bucket ls my-uploads --prefix reports/
```

### `ry bucket rm`

Delete one object from a bucket (irreversible).

```text
ry bucket rm [options] <bucket> <key>
```

Options:

- `-y, --yes`: Skip confirmation (required in automation).

Example:

```bash
ry bucket rm my-uploads reports/2026-10.pdf --yes
```

### `ry bucket presign`

Get a time-limited URL for one object (GET by default, --put to upload).

```text
ry bucket presign [options] <bucket> <key>
```

Options:

- `--put`: Sign an upload (PUT) instead of a download (GET).
- `--expires <seconds>`: How long the URL stays valid. Default: `900`.
- `--content-type <type>`: PUT only: the Content-Type the uploader must then send.

Example:

```bash
ry bucket presign my-uploads reports/2026-10.pdf
ry bucket presign my-uploads reports/2026-10.pdf --put --content-type application/pdf
```

### `ry bucket attach`

Attach a bucket to an app (injects S3_* into its environment).

```text
ry bucket attach [options] <bucket>
```

Options:

- `--to <app>`: App that should get access.
- `--as <name>`: Name this attachment: `<NAME>_S3_BUCKET` etc. instead of S3_BUCKET (required from the second bucket of an app).
- `-y, --yes`: Skip the re-attach warning.

Example:

```bash
ry bucket attach my-uploads --to web
ry bucket attach my-uploads --to web --as uploads
```

### `ry bucket detach`

Detach a bucket from an app (removes S3_*, revokes its key; the files stay).

```text
ry bucket detach [options] <bucket>
```

Options:

- `--from <app>`: App that should lose access.

Example:

```bash
ry bucket detach my-uploads --from web
```

### `ry bucket cors`

Show the CORS rules of a bucket (browsers need them for direct uploads).

```text
ry bucket cors [options] <name>
```

Example:

```bash
ry bucket cors my-uploads
```

### `ry bucket cors-set`

Replace the CORS rules of a bucket (needed for direct browser uploads).

```text
ry bucket cors-set [options] <name>
```

Options:

- `--allow-origin <origins>`: Comma-separated, or '*'. Default: `*`.
- `--allow-method <methods>`: Comma-separated. Default: `GET,PUT,HEAD`.
- `--allow-header <headers>`: Comma-separated. Default: `*,authorization`.
- `--expose-header <headers>`: Comma-separated. Default: `ETag`.
- `--max-age <seconds>`: How long a browser may cache the preflight. Default: `3000`.
- `--clear`: Remove the configuration entirely.

Example:

```bash
ry bucket cors-set my-uploads --allow-origin https://www.example.com
```

### `ry bucket destroy`

Destroy a bucket and everything in it (irreversible).

```text
ry bucket destroy [options] <name>
```

Options:

- `-y, --yes`: Skip confirmation (required in automation).
- `--force`: Also destroy a bucket that still holds objects.

Example:

```bash
ry bucket destroy my-uploads --yes
ry bucket destroy my-uploads --force --yes
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/computer/ -->

# ry computer

> Links to watch or control a computer VM (images/computer), and who had control.

```text
ry computer [options] [command]
```

## Subcommands

### `ry computer create`

Create a computer: an app on the computer image with its own home disk (what the console's New computer does).

```text
ry computer create [options] <name>
```

Options:

- `-s, --size <size>`: small | base | large - the machine and the home disk (default: base).
- `-i, --image <ref>`: The computer image: an OCI reference, or a `build:<id>` of your team (default: $RYTIV_COMPUTER_IMAGE).

Example:

```bash
ry computer create dev-1 --image rytiv/computer:0.1.0
ry computer create dev-2 --size large --image rytiv/computer:0.1.0
```

### `ry computer view`

A link to watch the desktop (view only, any number of viewers).

```text
ry computer view [options] <app>
```

Options:

- `--ttl <seconds>`: How long the link opens a connection (60 to 3600, default 900).
- `--who <name>`: Who the link is for (audit; default: you).
- `-m, --machine <id>`: Which machine (default: the app's one machine).

Example:

```bash
ry computer view dev-1
```

### `ry computer control`

A link to take control (keyboard and mouse); one holder per machine, the agent in the VM pauses.

```text
ry computer control [options] <app>
```

Options:

- `--ttl <seconds>`: How long the control lease lasts (60 to 3600, default 900).
- `--who <name>`: Who takes control (audit, shown to the agent; default: you).
- `--force`: Take control from the current holder (their connection ends).
- `-m, --machine <id>`: Which machine (default: the app's one machine).

Example:

```bash
ry computer control dev-1 --ttl 1800
```

### `ry computer release`

End the control lease (the connection ends, the agent in the VM may continue).

```text
ry computer release [options] <app>
```

Options:

- `-m, --machine <id>`: Which machine (default: the app's one machine).

Example:

```bash
ry computer release dev-1
```

### `ry computer audit`

Who got which link, from when to when, and how control ended (all machines the app had).

```text
ry computer audit [options] <app>
```

Options:

- `-m, --machine <id>`: Only this machine.
- `--mode <mode>`: View, control or all (default all).
- `--limit <n>`: How many rows (default 50, at most 200).

Example:

```bash
ry computer audit dev-1
```

### `ry computer init`

Generate the link signing key (COMPUTER_VIEW_KEY) and store it as an app secret - never printed.

```text
ry computer init [options] <app>
```

Options:

- `--now`: Apply right away: rolling restart, and this command waits for it.
- `--rotate`: Replace an existing key (every link issued so far stops working after the restart).

Example:

```bash
ry computer init dev-1
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/config/ -->

# ry config

> Manage the project file (rytiv.json).

```text
ry config [options] [command]
```

## Subcommands

### `ry config init`

Write a rytiv.json in the current directory.

```text
ry config init [options] [app]
```

Options:

- `-s, --source <dir>`: Source directory. Default: `.`.
- `-p, --port <port>`: Internal port. Default: `3000`.

Example:

```bash
ry config init web --port 3000
```

### `ry config show`

Show the effective project file and where it was found.

```text
ry config show [options]
```

Example:

```bash
ry config show
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/console/ -->

# ry console

> Start a throwaway machine from this app's last image and get a shell in it.

```text
ry console [options] [app]
```

## Arguments

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

## Options

- `-m, --memory <mb>`: Memory in MB.

## Example

```bash
ry console web
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/cron/ -->

# ry cron

> Run something of an app on a schedule: call a path (the app is woken) or run a command on its own machine.

```text
ry cron [options] [command]
```

## Subcommands

### `ry cron list`

The app's schedules: when, what, the next slot and the last run.

```text
ry cron list [options] <app>
```

Alias: `ls`.

Example:

```bash
ry cron list web
```

### `ry cron add`

Add a schedule: ry cron add `<app>` `"<expr>"` --path /tick, or --command `"<shell>"` for a machine of its own.

```text
ry cron add [options] <app> <schedule> [command...]
```

Options:

- `--timezone <zone>`: IANA time zone the expression is read in (default UTC), e.g. Europe/Berlin.
- `--path <path>`: The app is woken and this path is called, e.g. /api/tick.
- `--method <method>`: With --path: GET (default) or POST.
- `--command <shell>`: Runs on a machine of its own, as /bin/sh -c `'<shell>'` (or give the argv after --).
- `-t, --timeout <seconds>`: Deadline (--path: per attempt, default 60, at most 240; --command: default 900, at most 3600).
- `-m, --memory <mb>`: With --command: memory of its machine in MB (default: the app's).
- `-c, --vcpus <n>`: With --command: vCPUs of its machine (default: the app's).
- `--paused`: Create it paused (ry cron resume starts it).

Example:

```bash
ry cron add web "*/15 * * * *" --path /api/tick
ry cron add web "0 3 * * *" --timezone Europe/Berlin --command "npm run cleanup"
```

From `ry cron add --help`:

```text
The expression has five fields (minute hour day-of-month month day-of-week) or is @hourly, @daily, ...

Examples:
  ry cron add shop "*/15 * * * *" --path /api/tick
  ry cron add shop "0 3 * * *" --timezone Europe/Berlin --command "npm run cleanup" --memory 8192
  ry cron add shop "@daily" -- node scripts/report.js --full

--path suits frequent, light work: down to every minute, the app does it in its own machine.
--command suits heavy, rare work: at most hourly, every run gets a machine of its own size.
A slot that comes while the previous run of the same schedule still runs is skipped, not queued.

A path is called signed: header Rytiv-Cron-Signature = v1=<hex HMAC-SHA256 of '<Rytiv-Cron-Timestamp>.<path>'>
under the app's secret RYTIV_CRON_SECRET (created with the app's first --path schedule; the app sees it from its next deploy).
```

### `ry cron rm`

Remove a schedule and its run history.

```text
ry cron rm [options] <app> <id>
```

Alias: `remove`.

Options:

- `-y, --yes`: Confirm without asking (automation).

Example:

```bash
ry cron rm web sch-1a2b3c4d --yes
```

### `ry cron pause`

Stop starting runs (the schedule and its run log stay).

```text
ry cron pause [options] <app> <id>
```

Example:

```bash
ry cron pause web sch-1a2b3c4d
```

### `ry cron resume`

Start running again, from the next slot on (nothing paused is caught up).

```text
ry cron resume [options] <app> <id>
```

Example:

```bash
ry cron resume web sch-1a2b3c4d
```

### `ry cron runs`

The newest runs of a schedule: slot, state, attempts, answer, duration, reason.

```text
ry cron runs [options] <app> <id>
```

Options:

- `-n, --limit <n>`: How many (default 20, at most 100).

Example:

```bash
ry cron runs web sch-1a2b3c4d
```

### `ry cron run`

Run a schedule once, now (to try the target without waiting for its slot).

```text
ry cron run [options] <app> <id>
```

Example:

```bash
ry cron run web sch-1a2b3c4d
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/deploy/ -->

# ry deploy

> Deploy from a source directory (--source) or a prebuilt OCI image (--image); reads rytiv.json if present.

```text
ry deploy [options] [app]
```

## Options

- `-s, --source <dir>`: Source directory to build and deploy.
- `-i, --image <image>`: Prebuilt OCI image, e.g. nginx:alpine.
- `-m, --memory <mb>`: Memory in MB (default: keep the app's current size; 512 for a new app).
- `-c, --vcpus <n>`: vCPUs (default: keep the app's current size; 1 for a new app).
- `--build-memory <mb>`: Memory for the BUILD machine in MB (default: by framework, 4096 / 8192 for next and dockerfile).
- `--disk <mb>`: Disk for the machine in MB (default: image size + headroom; raise it when the app installs or builds inside its own machine).
- `-p, --port <port>`: Internal port. Default: `3000`.
- `-n, --count <n>`: Number of machines (default: keep current, min 1).
- `--start <command>`: Start command, overriding what detection chose (one source, several process types).
- `--health-path <path>`: HTTP health-check path for app-level readiness, e.g. /health.
- `--health-timeout <seconds>`: How long a new instance may take to open its port (default 60, 120 with a volume).
- `--restart <policy>`: Never: a crashed guest stays down and a silent one is only reported; on-failure: also restart a guest that stops listening (3 tries, growing gap). Without it a crashed guest is restarted (10 in 5 min) and a silent one is reported.
- `--kill-signal <signal>`: Signal a stop, deploy replacement or migrate sends the app before it ends (SIGTERM, SIGINT, SIGQUIT, SIGHUP, SIGUSR1, SIGUSR2, SIGWINCH, SIGKILL; default: the image's STOPSIGNAL, else SIGTERM).
- `--kill-timeout <seconds>`: How long the app gets after that signal before SIGKILL (default 30, at most 300).
- `--sleep <off|duration>`: When the machines sleep: off (always on, e.g. a worker or cron) or after an idle time like 5m, 2h, 1d (10s to 1d) without requests and without CPU load; default: keep the app's current rule - an app whose rule was never chosen never sleeps.
- `-e, --env <pairs...>`: Plain (unencrypted) env vars, e.g. LOG_LEVEL=debug NODE_ENV=production.
- `--with <kinds...>`: Accept the suggestion: postgres | redis | bucket | all - creates and attaches BEFORE the build.

## Example

```bash
ry deploy web --source .
ry deploy web --image nginx:alpine --port 80
ry deploy web --sleep 5m
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/deploys/ -->

# ry deploys

> Deployment history of an app: which machines each deploy created and retired.

```text
ry deploys [options] [app]
```

## Arguments

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

## Options

- `-n, --limit <n>`: How many entries (control plane caps at 100). Default: `20`.

## Example

```bash
ry deploys web
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/detect/ -->

# ry detect

> What this project is and what it needs - reads the directory, changes nothing.

```text
ry detect [options] [dir]
```

## Options

- `-a, --app <app>`: Check against an existing app (default: from rytiv.json).

## Example

```bash
ry detect .
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/domains/ -->

# ry domains

> Attach your own domains to an app.

```text
ry domains [options] [command]
```

## Subcommands

### `ry domains add`

Claim a domain for an app and print the DNS records to set.

```text
ry domains add [options] <app> <domain>
```

Example:

```bash
ry domains add web www.example.com
```

### `ry domains list`

Show domains of an app with status and certificate expiry.

```text
ry domains list [options] [app]
```

Arguments:

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

Example:

```bash
ry domains list web
```

### `ry domains check`

Re-run verification now instead of waiting for the next scheduled check.

```text
ry domains check [options] <app> <domain>
```

Example:

```bash
ry domains check web www.example.com
```

### `ry domains zones`

Prove a whole zone once and get one wildcard certificate for every name below it.

```text
ry domains zones [options] [command]
```

#### `ry domains zones add`

Claim a zone and print the two DNS records to set.

```text
ry domains zones add [options] <zone>
```

Example:

```bash
ry domains zones add example.com
```

#### `ry domains zones list`

Show your zones with status and wildcard certificate expiry.

```text
ry domains zones list [options]
```

Example:

```bash
ry domains zones list
```

#### `ry domains zones check`

Re-run the zone proof or certificate order now.

```text
ry domains zones check [options] <zone>
```

Example:

```bash
ry domains zones check example.com
```

#### `ry domains zones remove`

Release a zone (refused while names below it are attached to apps).

```text
ry domains zones remove [options] <zone>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry domains zones remove example.com
```

### `ry domains remove`

Detach a domain from an app.

```text
ry domains remove [options] <app> <domain>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry domains remove web www.example.com --yes
```

### `ry domains redirect`

Answer 308 on `<domain>` and send visitors to `<to>` (another domain of the app); --off serves again.

```text
ry domains redirect [options] <app> <domain> [to]
```

Options:

- `--off`: Stop redirecting, serve the app on this domain again.

Example:

```bash
ry domains redirect web example.com www.example.com
ry domains redirect web example.com --off
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/exec/ -->

# ry exec

> Run a command in a running machine and exit with its exit code (the command goes after --).

```text
ry exec [options] [app] -- <command> [args...]
```

## Arguments

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

## Options

- `-m, --machine <id>`: Which machine (default: a running one of the app).
- `-i, --interactive`: Pass this terminal's stdin to the command.
- `-t, --tty`: Allocate a terminal in the machine (with -i: an interactive shell).
- `-e, --env <KEY=VALUE>`: Env for this command only (repeatable).
- `--dir <path>`: Working directory in the machine (absolute).
- `--timeout <seconds>`: Stop the command after this many seconds (exit code 124).
- `--no-wake`: Fail instead of waking a sleeping machine.

## Example

```bash
ry exec web -- ls -la /app
ry exec dev-1 --dir /data -- git status
```

From `ry exec --help`:

```text
Examples:
  ry exec shop -- ls -la /app
  ry exec -m m-1234 -e DEBUG=1 --dir /srv -- ./migrate.sh
  ry exec shop -it -- sh

Exit code: the command's own; 128+n if a signal ended it; 124 on --timeout; 127/126 if it
was not found / not executable; 255 for everything of ry's own (with a `ry:` line on stderr).
Ctrl-C sends SIGINT, a second one SIGTERM, a third SIGKILL.
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/forward/ -->

# ry forward

> Forward a local port to a port inside a machine, e.g. `ry forward shop 8080:3000` (no public port needed).

```text
ry forward [options] [app] <localPort>:<guestPort>
```

## Arguments

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

## Options

- `-m, --machine <id>`: Which machine (default: a running one of the app).

## Example

```bash
ry forward dev-1 3000:3000
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/git/ -->

# ry git

> Deploy on push: connect an app to a GitHub repository and see what pushes did.

```text
ry git [options] [command]
```

## Subcommands

### `ry git connect`

Deploy an app on every push to a branch of a GitHub repository.

```text
ry git connect [options] [app]
```

Arguments:

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

Options:

- `--repo <owner/repo>`: The repository (default: the GitHub remote 'origin' of this directory).
- `--branch <branch>`: The branch whose pushes deploy (default: main).
- `--subdirectory <dir>`: For a monorepo: the folder that gets built.
- `--account <login>`: The connected GitHub account to use (default: the repository's owner).
- `--auto-deploy`: Deploy on every push (the default for a new link).
- `--no-auto-deploy`: Keep the link but do not deploy on push.
- `--previews`: Open a preview for pushes to other branches (the default for a new link).
- `--no-previews`: No previews for other branches.
- `--wait`: Wait for the browser even without a terminal.
- `--no-wait`: Start the GitHub connection, print the link, and return.
- `--no-browser`: Do not open a browser, just print the link.

Example:

```bash
ry git connect web --repo acme/web --branch main
```

### `ry git status`

Which repository an app follows, and what its recent pushes did - exits 1 if the newest push failed.

```text
ry git status [options] [app]
```

Arguments:

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

Options:

- `-n, --limit <n>`: How many pushes (control plane caps at 100). Default: `10`.

Example:

```bash
ry git status web
```

### `ry git disconnect`

Stop deploying an app on push (its machines keep running; the GitHub account stays connected).

```text
ry git disconnect [options] <app>
```

Example:

```bash
ry git disconnect web
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/job/ -->

# ry job

> Run one command in an app's image on a throwaway machine, and get its result.

```text
ry job [options] [command]
```

## Subcommands

### `ry job run`

Run a command in the app's deployed image, stream its output, exit with its exit code (the command goes after --).

```text
ry job run [options] <app> <command...>
```

Options:

- `-e, --env <KEY=VALUE>`: Env for this job only, laid over the app's secrets (repeatable).
- `-t, --timeout <seconds>`: Stop the job after this many seconds (default 900, at most 3600).
- `-m, --memory <mb>`: Memory of the job's machine in MB (default: the app's).
- `-c, --vcpus <n>`: vCPUs of the job's machine (default: the app's).

Example:

```bash
ry job run web -- npm run migrate
ry job run web --memory 4096 --timeout 1800 -- node scripts/report.js
```

From `ry job run --help`:

```text
Example:
  ry job run shop --memory 4096 -- npm run migrate

Everything after -- is the command, passed on argument by argument. The job keeps running if
this command is interrupted; ry job cancel <id> stops it.
```

### `ry job list`

The app's jobs, newest first (20 per page).

```text
ry job list [options] <app>
```

Options:

- `-n, --limit <n>`: How many (at most 20).
- `--before <createdAt>`: Only jobs created before this - the createdAt of the last job of the previous page.

Example:

```bash
ry job list web
```

### `ry job get`

One job: state, exit code, timing and its recorded output.

```text
ry job get [options] <id>
```

Example:

```bash
ry job get job-1a2b3c4d
```

### `ry job cancel`

Abort a job that is queued or running (its machine is destroyed, the record stays).

```text
ry job cancel [options] <id>
```

Options:

- `-y, --yes`: Confirm without asking (automation, and the way back after consent).

Example:

```bash
ry job cancel job-1a2b3c4d --yes
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/link/ -->

# ry link

> Let an app reach another app privately at <target>.internal (no public door needed).

```text
ry link [options] <target>
```

## Options

- `--from <app>`: The app that will do the calling.

## Example

```bash
ry link api --from web
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/links/ -->

# ry links

> Show the private app-to-app links in this workspace.

```text
ry links [options]
```

## Example

```bash
ry links
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/login/ -->

# ry login

> Sign in: shows a code to confirm in the console (--token stays for CI).

```text
ry login [options]
```

## Options

- `-e, --endpoint <url>`: Control plane endpoint.
- `-t, --token <token>`: API token - the non-interactive way in (CI).
- `--no-browser`: Do not open a browser, just print the address.

## Example

```bash
ry login
ry login --token <token>
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/logs/ -->

# ry logs

> Stream the console output of an app's machines.

```text
ry logs [options] [app]
```

## Arguments

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

## Options

- `-m, --machine <id>`: Only this machine.
- `-n, --tail <lines>`: How many lines to show first (0 = all). Default: `200`.
- `-f, --follow`: Keep streaming new output.

## Example

```bash
ry logs web -f
ry logs web -n 500
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/machine/ -->

# ry machine

> Act on a single machine.

```text
ry machine [options] [command]
```

## Subcommands

### `ry machine suspend`

Suspend a machine.

```text
ry machine suspend [options] <id>
```

### `ry machine start`

Start a machine.

```text
ry machine start [options] <id>
```

### `ry machine stop`

Stop a machine.

```text
ry machine stop [options] <id>
```

### `ry machine destroy`

Destroy a machine.

```text
ry machine destroy [options] <id>
```

Options:

- `-y, --yes`: Confirm without asking (automation, and the way back after consent).

### `ry machine migrate`

Move a machine to another host (graceful, for planned maintenance).

```text
ry machine migrate [options] <id>
```

Example:

```bash
ry machine migrate m-1a2b3c4d
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/machines/ -->

# ry machines

> List machines for an app.

```text
ry machines [options] [app]
```

## Arguments

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

## Example

```bash
ry machines web
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/mail/ -->

# ry mail

> Transactional email: sending domains, log, inbox, suppressions.

```text
ry mail [options] [command]
```

## Subcommands

### `ry mail domains`

The domains you send from.

```text
ry mail domains [options] [command]
```

#### `ry mail domains list`

Show your sending domains with status.

```text
ry mail domains list [options]
```

Example:

```bash
ry mail domains list
```

#### `ry mail domains add`

Claim a sending domain and print the DNS records to set.

```text
ry mail domains add [options] <domain>
```

Example:

```bash
ry mail domains add mail.example.com
```

#### `ry mail domains show`

The records of a domain with what DNS shows, and the receiving side.

```text
ry mail domains show [options] <domain>
```

Example:

```bash
ry mail domains show mail.example.com
```

#### `ry mail domains check`

Look DNS up now and verify the domain if the required records are there.

```text
ry mail domains check [options] <domain>
```

Example:

```bash
ry mail domains check mail.example.com
```

#### `ry mail domains remove`

Give a sending domain back - waiting messages, its log and its inbox go with it (not within 14 days of its last send).

```text
ry mail domains remove [options] <domain>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry mail domains remove mail.example.com
```

### `ry mail log`

Your sent messages, newest first, with their delivery status.

```text
ry mail log [options]
```

Options:

- `-n, --limit <n>`: How many entries (control plane caps at 500). Default: `50`.

Example:

```bash
ry mail log
```

### `ry mail show`

One message and every event the deliverer recorded for it.

```text
ry mail show [options] <id>
```

Example:

```bash
ry mail show msg-1a2b3c4d
```

### `ry mail inbox`

What arrived at your receiving addresses.

```text
ry mail inbox [options] [command]
```

#### `ry mail inbox list`

Received messages, newest first.

```text
ry mail inbox list [options]
```

Options:

- `-n, --limit <n>`: How many entries. Default: `50`.
- `-d, --domain <domain>`: Only this receiving domain.

Example:

```bash
ry mail inbox list
```

#### `ry mail inbox show`

One received message: headers and the text part.

```text
ry mail inbox show [options] <id>
```

Options:

- `--raw`: Print the raw message instead of the text part.

Example:

```bash
ry mail inbox show inb-1a2b3c4d
```

### `ry mail suppressions`

Addresses you will not send to again.

```text
ry mail suppressions [options] [command]
```

#### `ry mail suppressions list`

Your suppression list.

```text
ry mail suppressions list [options]
```

Example:

```bash
ry mail suppressions list
```

#### `ry mail suppressions clear`

Remove an address from the list after a genuine re-signup (complaints cannot be cleared).

```text
ry mail suppressions clear [options] <address>
```

Example:

```bash
ry mail suppressions clear someone@example.com
```

### `ry mail routes`

The addresses a domain receives at.

```text
ry mail routes [options] [command]
```

#### `ry mail routes list`

Receiving addresses of a domain.

```text
ry mail routes list [options] <domain>
```

Example:

```bash
ry mail routes list mail.example.com
```

#### `ry mail routes add`

Receive mail at an address (a local part, a full address under the domain, or * for all).

```text
ry mail routes add [options] <domain> <address>
```

Example:

```bash
ry mail routes add mail.example.com support
```

#### `ry mail routes remove`

Stop receiving at an address (id, address or local part).

```text
ry mail routes remove [options] <domain> <route>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry mail routes remove mail.example.com rt-1a2b3c4d
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/maintenance/ -->

# ry maintenance

> Switch an app's maintenance mode: the edge answers every request with 503, the machines keep running.

```text
ry maintenance [options] [command]
```

## Subcommands

### `ry maintenance status`

Show whether an app is in maintenance mode.

```text
ry maintenance status [options] [app]
```

Arguments:

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

Example:

```bash
ry maintenance status web
```

### `ry maintenance on`

Put an app into maintenance: ALL requests get 503 from the edge until `ry maintenance off`.

```text
ry maintenance on [options] <app>
```

Example:

```bash
ry maintenance on web
```

### `ry maintenance off`

End maintenance: the app serves again with the next route poll (~2 s).

```text
ry maintenance off [options] <app>
```

Example:

```bash
ry maintenance off web
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/new/ -->

# ry new

> Start a new project from a template - scaffolder plus the part that makes it deploy here.

```text
ry new [options] [template] [name]
```

## Arguments

- `[template]`: One of: next, astro, sveltekit, static.
- `[name]`: Directory and app name (default: the template id).

## Example

```bash
ry new next my-site
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/postgres/ -->

# ry postgres

> Managed Postgres: create, branch, fork, sleep policy (stored; not in force on every host).

```text
ry postgres [options] [command]
```

Alias: `pg`.

## Subcommands

### `ry postgres create`

Create a Postgres database: the connection URL is in --json output only.

```text
ry postgres create [options] <name>
```

Options:

- `-m, --memory <mb>`: Memory in MB. Default: `1024`.
- `-s, --size <gb>`: Volume size in GB (minimum 4: the database keeps its write-ahead log on it). Default: `10`.
- `--locale <locale>`: Collation locale of the database, e.g. de-DE, fr-FR, de-DE-u-co-phonebk.
- `--always-on`: Store the policy 'always on' (never suspend) instead of the default policy 'suspend after 5m idle'.
- `--sleep-after <duration>`: Store the sleep policy 'suspend after this long without a query or traffic', e.g. 5m, 1h (10s to 1d).

Example:

```bash
ry postgres create appdb
ry postgres create appdb --size 20 --locale en-US
```

### `ry postgres list`

List Postgres databases with their sleep policy.

```text
ry postgres list [options]
```

Example:

```bash
ry postgres list
```

### `ry postgres expire`

When a copy (fork or branch) is deleted: --in `<duration>`, --at `<time>` or --never.

```text
ry postgres expire [options] <name>
```

Options:

- `--in <duration>`: Delete it after this long from now, e.g. 12h, 7d (60s to 30d).
- `--at <time>`: Delete it at this moment, ISO 8601 UTC (at most 30 days ahead).
- `--never`: Keep it until somebody deletes it.

Example:

```bash
ry postgres expire appdb-try --in 12h
```

### `ry postgres sleep`

Set the sleep policy of the database: --after `<duration>` (e.g. 5m) or --off (always on).

```text
ry postgres sleep [options] <name>
```

Options:

- `--after <duration>`: Store 'suspend after this long without a query or traffic', e.g. 5m, 1h (10s to 1d).
- `--off`: Store 'always on': never suspend.

Example:

```bash
ry postgres sleep appdb --after 10m
ry postgres sleep appdb --off
```

### `ry postgres branch`

Branch a database from NOW: a copy-on-write snapshot on the source's host, usable in seconds.

```text
ry postgres branch [options] <source> <name>
```

Options:

- `--ephemeral`: Throwaway branch for a test or a task: ready without its own backup, but lost with its host (never restarted empty).
- `--expires-in <duration>`: Delete the branch after this long, e.g. 12h, 7d (60s to 30d).
- `--expires-at <time>`: Delete the branch at this moment, ISO 8601 UTC (at most 30 days ahead).

Example:

```bash
ry postgres branch appdb appdb-try --expires-in 1d
```

### `ry postgres fork`

Fork a database from its archive onto any host: a full copy, minutes for large databases; --at for a point in time.

```text
ry postgres fork [options] <source> <name>
```

Options:

- `--at <time>`: Restore to this point in time instead of now, ISO 8601 UTC, e.g. 2026-10-04T09:30:00Z (within the archive's 7 days).
- `--expires-in <duration>`: Delete the fork after this long, e.g. 12h, 7d (60s to 30d).
- `--expires-at <time>`: Delete the fork at this moment, ISO 8601 UTC (at most 30 days ahead).

Example:

```bash
ry postgres fork appdb appdb-yesterday --at 2026-10-20T09:00:00Z
```

### `ry postgres restore`

Put a database back to a point in time IN PLACE: same name and URL, the old state is kept as a branch.

```text
ry postgres restore [options] <name>
```

Options:

- `--at <time>`: The point in time, ISO 8601 UTC, e.g. 2026-10-07T09:30:00Z (within the archive's 7 days).
- `--backup-name <name>`: Name of the branch that keeps the old state (default `<name>-old-<yyyymmddhhmmss>`).
- `-y, --yes`: Confirm without asking (automation, and the way back after consent).

Example:

```bash
ry postgres restore appdb --at 2026-10-20T09:00:00Z
```

### `ry postgres destroy`

Destroy a database, its machine and its volume (irreversible).

```text
ry postgres destroy [options] <name>
```

Options:

- `-y, --yes`: Confirm without asking (automation, and the way back after consent).

Example:

```bash
ry postgres destroy appdb-try --yes
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/preview/ -->

# ry preview

> One preview address per branch - opened by a push, closed by itself.

```text
ry preview [options] [command]
```

## Subcommands

### `ry preview list`

Show the previews of an app and when each one expires.

```text
ry preview list [options] [app]
```

Arguments:

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

Example:

```bash
ry preview list web
```

### `ry preview create`

Open a preview for a branch without waiting for a push.

```text
ry preview create [options] [app]
```

Arguments:

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

Options:

- `--branch <branch>`: The branch this preview follows.

Example:

```bash
ry preview create web --branch feature/login
```

### `ry preview destroy`

Close a preview now instead of waiting for the branch to go.

```text
ry preview destroy [options] <app> <branch>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry preview destroy web feature/login
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/profile/ -->

# ry profile

> Saved logins for lab, prod, ...

```text
ry profile [options] [command]
```

## Subcommands

### `ry profile list`

Show saved logins and which one is active.

```text
ry profile list [options]
```

Example:

```bash
ry profile list
```

### `ry profile use`

Make a saved login the default for new shells.

```text
ry profile use [options] <name>
```

Example:

```bash
ry profile use work
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/protect/ -->

# ry protect

> Give an app a protected view (password or share link).

```text
ry protect [options] [command]
```

## Subcommands

### `ry protect status`

Show whether an app is protected and which share links exist.

```text
ry protect status [options] [app]
```

Arguments:

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

Example:

```bash
ry protect status web
```

### `ry protect password`

Protect an app with a password (asked interactively, never as an argument).

```text
ry protect password [options] <app>
```

Options:

- `--generate`: Generate a password instead of asking, and print it once.

Example:

```bash
ry protect password web
```

### `ry protect link`

Create a share link - one address the customer opens once.

```text
ry protect link [options] <app>
```

Options:

- `--label <label>`: Who this link is for, e.g. "client Smith" - a revoke needs something to aim at.
- `--expires <when>`: 30d, 12h or an ISO date. Without it the link does not expire.

Example:

```bash
ry protect link web --label "client Smith"
```

### `ry protect links`

List the share links of an app.

```text
ry protect links [options] [app]
```

Arguments:

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

Example:

```bash
ry protect links web
```

### `ry protect revoke`

Revoke one share link - it stops working within ~2 seconds.

```text
ry protect revoke [options] <app> <link-id>
```

Example:

```bash
ry protect revoke web lnk-1a2b3c4d
```

### `ry protect rotate`

Sign everybody out immediately - the password and the links stay valid.

```text
ry protect rotate [options] <app>
```

Example:

```bash
ry protect rotate web
```

### `ry protect off`

Make an app public again.

```text
ry protect off [options] <app>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry protect off web
```

### `ry protect signed`

Only visitors with a token signed by your org get in - everybody else sees "no app with that name".

```text
ry protect signed [options] <app>
```

Example:

```bash
ry protect signed web
```

### `ry protect token`

Mint an access token for a signed app with your org's platform key.

```text
ry protect token [options] <app>
```

Options:

- `--ttl <duration>`: How long the token can be redeemed, e.g. 60s, 30m, 1d (default 60s, at most 1d).
- `--sub <id>`: Who it is for - goes into the token, for your own logs.
- `--next <path>`: Where the browser lands after redeeming the URL (default /).

Example:

```bash
ry protect token web
```

### `ry protect keys`

The public keys a partner signs access tokens with (org-wide).

```text
ry protect keys [options] [command]
```

#### `ry protect keys list`

List the org's partner keys.

```text
ry protect keys list [options]
```

Example:

```bash
ry protect keys list
```

#### `ry protect keys add`

Register an Ed25519 public key - tokens signed with its private half name it as kid.

```text
ry protect keys add [options]
```

Options:

- `--label <label>`: What signs with it, e.g. "portal" - a removal needs something to aim at.
- `--public-key <file-or-key>`: PEM file, or the raw 32 bytes as base64/base64url.

Example:

```bash
ry protect keys add --label portal --public-key ./portal.pub
```

#### `ry protect keys remove`

Remove a partner key - new sign-ins with it fail within ~2 seconds.

```text
ry protect keys remove [options] <id>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry protect keys remove key-1a2b3c4d
```

### `ry protect settings`

Show or set your org's settings for signed apps: cookie lifetime and who may frame them.

```text
ry protect settings [options]
```

Options:

- `--cookie-ttl <duration>`: How long a signed visitor stays signed in, e.g. 1h (60s to 1d).
- `--frame-ancestors <origins>`: Comma-separated origins that may frame the loading page, or none.

Example:

```bash
ry protect settings
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/proxy/ -->

# ry proxy

> Forward a local port to a machine, e.g. `ry proxy my-db 15432:5432` then `psql -h 127.0.0.1 -p 15432`.

```text
ry proxy [options] <app> [ports]
```

## Options

- `-m, --machine <id>`: Which machine (default: a running one).
- `--host <addr>`: Local bind address. Default: `127.0.0.1`.

## Example

```bash
ry proxy appdb 15432:5432
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/releases/ -->

# ry releases

> The releases of an app: what went out, which one runs, and which ones a rollback can bring back.

```text
ry releases [options] [app]
```

## Arguments

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

## Options

- `-n, --limit <n>`: How many releases (control plane caps at 100). Default: `20`.

## Example

```bash
ry releases web
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/resource/ -->

# ry resource

> Manage attachable resources (redis, postgres).

```text
ry resource [options] [command]
```

## Subcommands

### `ry resource create`

Create an org resource, e.g. a redis or postgres instance.

```text
ry resource create [options] <name>
```

Options:

- `-k, --kind <kind>`: Resource kind: redis | postgres. Default: `redis`.
- `-m, --memory <mb>`: Memory in MB. Default: `1024`.
- `-s, --size <gb>`: Durable volume size in GB (postgres gets one by default, and needs at least 4).
- `--ha`: High availability: primary + standby on separate hosts, automatic failover (durability host-redundant).
- `--durability <durability>`: Explicit durability level (standard | host-redundant).
- `--locale <locale>`: Collation locale of the database, e.g. de-DE, fr-FR, de-DE-u-co-phonebk (postgres only).
- `--always-on`: Store the policy 'always on' (never suspend) instead of the default policy 'suspend after 5m idle' (postgres only).
- `--sleep-after <duration>`: Store the sleep policy 'suspend after this long without a query or traffic', e.g. 5m, 1h (postgres only, 10s to 1d).

Example:

```bash
ry resource create cache --kind redis
```

### `ry resource sleep`

Set the sleep policy of a postgres resource: --after `<duration>` or --off (always on).

```text
ry resource sleep [options] <name>
```

Options:

- `--after <duration>`: Store 'suspend after this long without a query or traffic', e.g. 5m, 1h (10s to 1d).
- `--off`: Store 'always on': never suspend.

Example:

```bash
ry resource sleep cache --off
```

### `ry resource list`

List resources.

```text
ry resource list [options]
```

Example:

```bash
ry resource list
```

### `ry resource destroy`

Destroy a resource, its machines and its volumes (irreversible).

```text
ry resource destroy [options] <name>
```

Options:

- `-y, --yes`: Confirm without asking (automation, and the way back after consent).

Example:

```bash
ry resource destroy cache --yes
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/rollback/ -->

# ry rollback

> Deploy an earlier release again, without a rebuild (default: the previous release that went live); secrets, settings, volumes and databases stay as they are.

```text
ry rollback [options] <app> [release]
```

## Example

```bash
ry rollback web
ry rollback web 3
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/sandbox/ -->

# ry sandbox

> Short-lived machines for one task each - created from a template, removed at their deadline.

```text
ry sandbox [options] [command]
```

## Subcommands

### `ry sandbox create`

Create a sandbox from `build:<id>` or `app:<name>` and wait until it runs.

```text
ry sandbox create [options] <template>
```

Options:

- `--ttl <duration>`: How long it lives, e.g. 10m, 2h (default 5m, at most 24h).
- `--cpus <n>`: vCPUs (default 1).
- `--memory <mb>`: Memory in MB (default 512).
- `--port <port>`: A further port reachable as `https://<port>-<id>`... (repeatable, at most 8).
- `-e, --env <KEY=VALUE>`: Environment of the sandbox (repeatable) - nothing is inherited from the template app.
- `--public`: Make its URLs public (default: only with a token signed by your org).
- `--readiness <boot|port>`: Up when the VM boots (default) or when its port answers.
- `--idle <duration>`: Sleep after this much idle time (default 5m).
- `--egress <mode>`: Outbound network: allow-all (default), deny-all (nothing, not even DNS) or allowlist.
- `--allow <domain|cidr>`: With an allowlist: a domain (api.example.com, *.example.com) or IPv4 range reachable on 80/443 (repeatable, implies --egress allowlist).

Example:

```bash
ry sandbox create app:web --ttl 30m
```

### `ry sandbox list`

The org's sandboxes that run (with --all: also the ended ones of the last 14 days).

```text
ry sandbox list [options]
```

Options:

- `--all`: Include ended sandboxes.

Example:

```bash
ry sandbox list
ry sandbox list --all
```

### `ry sandbox show`

One sandbox: state, deadline, URLs, machine.

```text
ry sandbox show [options] <id>
```

Example:

```bash
ry sandbox show sbx-1a2b3c4d5e6f
```

### `ry sandbox exec`

Run one command in a sandbox and exit with its exit code (the command goes after --).

```text
ry sandbox exec [options] <id> -- <command> [args...]
```

Options:

- `--timeout <seconds>`: Stop the command after this many seconds (default 60, at most 290; exit code 124).
- `--dir <path>`: Working directory in the sandbox (absolute).
- `-e, --env <KEY=VALUE>`: Env for this command only (repeatable).

Example:

```bash
ry sandbox exec sbx-1a2b3c4d5e6f -- uname -a
```

### `ry sandbox timeout`

Set a sandbox's deadline to now + duration (e.g. 30m) - like E2B setTimeout.

```text
ry sandbox timeout [options] <id> <duration>
```

Example:

```bash
ry sandbox timeout sbx-1a2b3c4d5e6f 1h
```

### `ry sandbox kill`

End a sandbox now - its machine and everything on its disk are gone.

```text
ry sandbox kill [options] <id>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry sandbox kill sbx-1a2b3c4d5e6f
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/secrets/ -->

# ry secrets

> Manage app secrets.

```text
ry secrets [options] [command]
```

## Subcommands

### `ry secrets set`

Set secrets (KEY=VALUE ...), staged by default.

```text
ry secrets set [options] <app> <pairs...>
```

Options:

- `--now`: Apply right away: rolling restart, and this command waits for it.
- `--build`: Also give these secrets to the build (default: only NEXT_PUBLIC_*, VITE_*, PUBLIC_* and similar).
- `--no-build`: Keep these secrets out of the build, runtime only.

Example:

```bash
ry secrets set web API_KEY=example-value
ry secrets set web NEXT_PUBLIC_SITE_URL=https://www.example.com --build
ry secrets set web DATABASE_PASSWORD=example-value --now
```

### `ry secrets list`

List secret keys with metadata (never values).

```text
ry secrets list [options] [app]
```

Arguments:

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

Example:

```bash
ry secrets list web
```

### `ry secrets unset`

Remove a single secret (rejected for managed secrets, e.g. one an attachment injected).

```text
ry secrets unset [options] <app> <key>
```

Example:

```bash
ry secrets unset web API_KEY
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/ssh/ -->

# ry ssh

> An interactive shell in a running machine (over the Rytiv API, no SSH needed); real SSH for IDEs: ry ssh config.

```text
ry ssh [options] [command] [app]
```

## Arguments

- `[app]`: The app (default: "app" from rytiv.json in this directory or above).

## Options

- `-m, --machine <id>`: Which machine (default: a running one of the app).
- `--no-wake`: Fail instead of waking a sleeping machine.

## Example

```bash
ry ssh dev-1
```

From `ry ssh --help`:

```text
Real SSH (VS Code Remote-SSH, scp, sftp, ssh -L) goes through the SSH gateway:
  ry ssh-keys add                 register ~/.ssh/id_ed25519.pub
  ry ssh config >> ~/.ssh/config  Host entries rytiv-<app>, host key pinned
  ssh <app>@ssh.<domain>          or ssh <app>.<machine>@...
  ry ssh token <app> --ttl 1h     a short-lived user name for CI and agents
Commands without a terminal: ry exec <app> -- <command>.
```

## Subcommands

### `ry ssh token`

Mint a short-lived SSH token for agents and CI: `ssh <token>@ssh.<domain>` (shown once).

```text
ry ssh token [options] <app>
```

Options:

- `-m, --machine <id>`: Bind the token to this machine (default: a running one at login).
- `--ttl <duration>`: Lifetime, e.g. 30m, 2h, 1d (default 1h, at most 72h).

Example:

```bash
ry ssh token web
```

### `ry ssh tokens`

The SSH tokens of this org that still work.

```text
ry ssh tokens [options] [command]
```

#### `ry ssh tokens list`

Tokens that are neither expired nor revoked, without their value.

```text
ry ssh tokens list [options]
```

Example:

```bash
ry ssh tokens list
```

#### `ry ssh tokens revoke`

Revoke an SSH token; the next login or channel with it is refused.

```text
ry ssh tokens revoke [options] <id>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry ssh tokens revoke sst-1a2b3c4d
```

### `ry ssh config`

Print ~/.ssh/config entries (Host `rytiv-<app>`) for IDEs and pin the gateway's host key.

```text
ry ssh config [options] [apps...]
```

Options:

- `-i, --identity <file>`: The private key the entries should use (IdentityFile).

Example:

```bash
ry ssh config web
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/ssh-keys/ -->

# ry ssh-keys

> SSH public keys of this org (for ssh <app>@ssh.<domain>).

```text
ry ssh-keys [options] [command]
```

## Subcommands

### `ry ssh-keys list`

The registered keys.

```text
ry ssh-keys list [options]
```

Example:

```bash
ry ssh-keys list
```

### `ry ssh-keys add`

Register a public key (default: ~/.ssh/id_ed25519.pub, then id_ecdsa.pub, ... id_rsa.pub).

```text
ry ssh-keys add [options] [file]
```

Options:

- `-n, --name <name>`: A name for the key (default: its comment).

Example:

```bash
ry ssh-keys add ~/.ssh/id_ed25519.pub
```

### `ry ssh-keys remove`

Remove a key by id or fingerprint; channels of open connections with it are refused from then on.

```text
ry ssh-keys remove [options] <key>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry ssh-keys remove key-1a2b3c4d
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/status/ -->

# ry status

> Overview of all apps and machine states.

```text
ry status [options]
```

## Example

```bash
ry status
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/tokens/ -->

# ry tokens

> API tokens for CI (org-scoped).

```text
ry tokens [options] [command]
```

## Subcommands

### `ry tokens list`

Your tokens, without their value.

```text
ry tokens list [options]
```

Example:

```bash
ry tokens list
```

### `ry tokens create`

Create a token; prints its value exactly once.

```text
ry tokens create [options] <name>
```

Options:

- `--scope <scope>`: Narrow the token, repeatable: read | mail:send | `mail:send:<domain>` | deploy | `deploy:<app>` (without it: full access to the org).
- `--deploy <app>`: Short for --scope `deploy:<app>` (repeatable): deploy an existing app, nothing else.
- `--expires-in <duration>`: The token stops working after this long: 12h, 30d, up to 365d (default: never).
- `--expires-at <time>`: The token stops working at this moment, ISO 8601 UTC, e.g. 2027-01-31T00:00:00Z.
- `--agent <class>`: An agent token for a coding agent: sandbox, twin or production (production may only read).
- `--app <name>`: With --agent: an app the token may touch (repeatable; without it the whole org).
- `--read-prod-data`: With --agent production: may also read what production holds (database, files) - off by default.

Example:

```bash
ry tokens create ci-deploy --scope deploy:web --expires-in 30d
ry tokens create claude-code --agent sandbox --app web
```

### `ry tokens revoke`

Revoke a token; requests already using it are rejected right away.

```text
ry tokens revoke [options] <id>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry tokens revoke tok-1a2b3c4d
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/unlink/ -->

# ry unlink

> Remove a private link between two apps.

```text
ry unlink [options] <target>
```

## Options

- `--from <app>`: The app that was doing the calling.

## Example

```bash
ry unlink api --from web
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/usage/ -->

# ry usage

> Show metered usage with prices and total.

```text
ry usage [options]
```

## Options

- `--from <iso>`: Start of the period (default: start of the current UTC month).
- `--to <iso>`: End of the period, exclusive (default: now).

## Example

```bash
ry usage
ry usage --from 2026-10-01T00:00:00Z --to 2026-11-01T00:00:00Z
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/volume/ -->

# ry volume

> Manage durable volumes (persistent block storage).

```text
ry volume [options] [command]
```

## Subcommands

### `ry volume create`

Create a durable volume you can attach to an app.

```text
ry volume create [options] <name>
```

Options:

- `-s, --size <gb>`: Size in GB. Default: `10`.
- `-p, --path <mountPath>`: Guest mount path. Default: `/data`.
- `--class <class>`: Volume class: standard (object-backed) | durable (replicated, later). Default: `standard`.
- `--flush <seconds>`: How often to snapshot to object storage (default daily; minimum 15s, and at least 3s per GB).

Example:

```bash
ry volume create data --size 20
```

### `ry volume resize`

Grow a volume (only upwards) - takes effect at the next cold start of its app (stop and start is enough).

```text
ry volume resize [options] <name> <sizeGb>
```

Example:

```bash
ry volume resize data 50
```

### `ry volume attach`

Attach a volume to an app - its data survives deploys (app must run a single machine).

```text
ry volume attach [options] <name>
```

Options:

- `--to <app>`: The app that will mount it.

Example:

```bash
ry volume attach data --to web
```

### `ry volume detach`

Release a volume from its app - the DATA STAYS, only the binding goes (refused while a machine runs on it: 'ry apps destroy `<app>'` flushes and frees it).

```text
ry volume detach [options] <name>
```

Example:

```bash
ry volume detach data
```

### `ry volume list`

List volumes.

```text
ry volume list [options]
```

Example:

```bash
ry volume list
```

### `ry volume update`

Change the snapshot cadence of a volume - takes effect within seconds, no restart.

```text
ry volume update [options] <name>
```

Options:

- `--flush <seconds>`: How often to snapshot to object storage (e.g. 30m, 2h, daily as 86400; minimum 15s, and at least 3s per GB).

Example:

```bash
ry volume update data --flush 2h
```

### `ry volume destroy`

Destroy a durable volume (irreversible; it must already be detached from a machine).

```text
ry volume destroy [options] <id>
```

Options:

- `-y, --yes`: Confirm without asking (automation, and the way back after consent).

Example:

```bash
ry volume destroy vol-1a2b3c4d --yes
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/webhooks/ -->

# ry webhooks

> Endpoints we call when a message is sent, bounces, is complained about, fails or arrives.

```text
ry webhooks [options] [command]
```

## Subcommands

### `ry webhooks list`

Your webhooks with the answer of their last delivery.

```text
ry webhooks list [options]
```

Example:

```bash
ry webhooks list
```

### `ry webhooks add`

Register an https endpoint; prints the signing secret exactly once.

```text
ry webhooks add [options] <url>
```

Options:

- `-e, --events <list>`: Comma-separated events (sent, delivered, delivery_delayed, bounced, complained, failed, received), or all. Default: `all`.

Example:

```bash
ry webhooks add https://www.example.com/hooks/rytiv
```

### `ry webhooks deliveries`

The last deliveries to one endpoint, newest first.

```text
ry webhooks deliveries [options] <id>
```

Options:

- `-n, --limit <n>`: How many entries (control plane caps at 500). Default: `50`.

Example:

```bash
ry webhooks deliveries wh-1a2b3c4d
```

### `ry webhooks remove`

Delete a webhook; pending deliveries are dropped.

```text
ry webhooks remove [options] <id>
```

Options:

- `-y, --yes`: Skip confirmation (required for automation).

Example:

```bash
ry webhooks remove wh-1a2b3c4d
```

---

<!-- CLI reference: https://docs.rytiv.com/reference/cli/whoami/ -->

# ry whoami

> Show the identity behind the configured token: an org (product token) or the system (operator token).

```text
ry whoami [options]
```

## Example

```bash
ry whoami
```

---

<!-- SDK & MCP: https://docs.rytiv.com/reference/mcp-tools/ -->

# MCP tools

> The tools the Rytiv MCP server offers, with their parameters and annotations, generated from the server's tool table.

The Rytiv MCP server at `https://api.rytiv.app/v1/mcp` answers `tools/list` with these 11 tools. This page is generated from the same table, so names, parameters and limits are exactly what your agent sees. To connect an agent, see the [quickstart](https://docs.rytiv.com/quickstart.md).

Every tool acts as the organization of the token that signed the request. A name that belongs to another organization is answered exactly like a name that does not exist.

In Claude Code, with the server added under the name `rytiv`, every tool is called `mcp__rytiv__<tool>`, for example `mcp__rytiv__list_apps`.

| Tool | What it does | Effect |
| --- | --- | --- |
| `search_docs` | Search the Rytiv documentation | reads |
| `list_apps` | List apps | reads |
| `deploy_app` | Deploy an app | changes or replaces |
| `get_logs` | Read the logs of an app | reads |
| `set_env` | Set environment variables | changes or replaces |
| `create_postgres` | Create a Postgres database | creates |
| `create_branch` | Branch a Postgres database | creates |
| `execute_sql` | Run SQL against a Postgres database | changes or replaces |
| `computer_create` | Create a computer | creates |
| `computer_exec` | Run a command in a computer | changes or replaces |
| `computer_snapshot` | Snapshot a computer | creates |

> **Annotations are hints:** `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint` tell your client which calls to confirm with you. `openWorldHint` is `false` on every tool: none of them reaches outside your own organization on Rytiv.

## `search_docs`

**Search the Rytiv documentation.** Answers questions about how Rytiv works: apps, machines, deploys, Postgres and its branches, computers, secrets, limits, EU data residency. Use it before guessing a field name or a limit. Local knowledge base, no request leaves Rytiv.

### Input

- `query` (string, optional, at most 200 characters): What you want to know, in words. Empty returns the table of contents.
- `limit` (integer, optional, 1 to 20): How many entries to return (1 to 20, default 5).

### Output

- `entries` (array of object, always)
- `query` (string, if present)

### Annotations

`readOnlyHint`: `true`, `openWorldHint`: `false`

## `list_apps`

**List apps.** Lists the apps of your org with the URL each one answers on. This is the entry point: an app is what a machine, a database and a deploy belong to.

### Input

- `label` (array of string, optional, 0 to 8 items): Optional label filter, e.g. [`role=db`]. Several terms are ANDed.

### Output

- `apps` (array of object, always)

### Annotations

`readOnlyHint`: `true`, `openWorldHint`: `false`

## `deploy_app`

**Deploy an app.** Deploys an image to an app and answers with the URL it is reachable on. A rolling deploy: a new machine comes up before an old one goes. Use `list_apps` first if you do not know whether the app exists.

### Input

- `app` (string, required): Name of the app (or database) in your org, e.g. `web`. It must already exist unless the tool creates it.
- `image` (string, required): OCI reference of the image, e.g. `nginx:alpine`, or a platform build id (`build:<id>`).
- `internalPort` (integer, optional, 1 to 65535): Port the app listens on inside the machine (default 3000).
- `memoryMb` (integer, optional, 128 to 16384): Memory of each machine in MB (default 512).
- `count` (integer, optional, 1 to 20): How many machines (1 to 20, default 1).

### Output

- `app` (string, always)
- `url` (string, always)
- `deployId` (string, if present)
- `status` (string, if present)

### Annotations

`readOnlyHint`: `false`, `destructiveHint`: `true`, `idempotentHint`: `false`, `openWorldHint`: `false`

## `get_logs`

**Read the logs of an app.** Returns the last console output of the machines of an app, one entry per machine. The first place to look when a deploy went wrong or an app does not answer. Each entry names what its text does NOT carry: `skippedBytes` of earlier output that was left behind, and `restarted` when the machine booted or woke up and the stream starts over. A gap is never silently joined.

### Input

- `app` (string, required): Name of the app (or database) in your org, e.g. `web`. It must already exist unless the tool creates it.
- `machineId` (string, optional): Optional: only this machine of the app.

### Output

- `app` (string, always)
- `machines` (array of object, always): One entry per machine of the app.

### Annotations

`readOnlyHint`: `true`, `openWorldHint`: `false`

## `set_env`

**Set environment variables.** Sets environment variables (secrets) of an app. The VALUES you pass here become part of this conversation - never paste a credential a human did not hand you for this purpose. The answer names the keys only; no value is ever returned. With `staged: true` (the default) the change takes effect on the next deploy.

### Input

- `app` (string, required): Name of the app (or database) in your org, e.g. `web`. It must already exist unless the tool creates it.
- `values` (object of string, required): Variable name to value, e.g. {"DATABASE_URL": "postgres://..."}. Values are stored encrypted and never read back.
- `staged` (boolean, optional): True (default): apply on the next deploy. false: apply now, which restarts the app.

### Output

- `app` (string, always)
- `keys` (array of string, always)
- `staged` (boolean, if present)
- `deployId` (string, if present)

### Annotations

`readOnlyHint`: `false`, `destructiveHint`: `true`, `idempotentHint`: `true`, `openWorldHint`: `false`

## `create_postgres`

**Create a Postgres database.** Creates a managed Postgres database in your org and answers with its name. The password is NOT returned: it lives in the secrets of the app that runs the database, and it belongs in a machine's environment, not in a chat.

### Input

- `name` (string, required): Name of the database, and of the app that runs it, e.g. `appdb`.
- `memoryMb` (integer, optional, 128 to 16384): Memory of the database machine in MB (default 1024).
- `sizeGb` (integer, optional, 4 to 500): Size of the database disk in GB (4 to 500). A managed database keeps its write-ahead log on the same disk as its data, so the platform refuses a smaller one.
- `locale` (string, optional): Locale and collation of the cluster: a tag such as `de-DE`, `fr-FR` or `de-DE-u-co-phonebk`, letters, digits, hyphen and underscore, starting with a letter. Absent = the platform default `de-DE`.

### Output

- `name` (string, always)
- `kind` (string, always)
- `port` (integer, if present)

### Annotations

`readOnlyHint`: `false`, `destructiveHint`: `false`, `idempotentHint`: `false`, `openWorldHint`: `false`

## `create_branch`

**Branch a Postgres database.** Creates a copy-on-write branch of a Postgres database: an independent database with the same data at this moment. This is where an agent changes a schema or runs a migration - never on the database a human is using. The branch is a database of its own and can be dropped.

### Input

- `database` (string, required): Name of the database to branch from.
- `name` (string, required): Name of the new branch.
- `ttlSeconds` (integer, optional, 60 to 2592000): Optional lifetime in seconds (60 to 2592000, 30 days); the branch is removed after it. Absent = it stays until it is dropped.

### Output

- `name` (string, always)
- `kind` (string, always)
- `state` (string, if present)
- `sourceName` (string, if present)

### Annotations

`readOnlyHint`: `false`, `destructiveHint`: `false`, `idempotentHint`: `false`, `openWorldHint`: `false`

## `execute_sql`

**Run SQL against a Postgres database.** Runs one SQL statement against a managed Postgres database of your org. READ-ONLY unless `branch` names a branch: without it the session runs with `default_transaction_read_only`, so a write is refused by the database itself, not only by a rule of ours. To change data or a schema, branch first (`create_branch`) and pass the branch here.

### Input

- `database` (string, required): Name of the database (or of the branch) to run against.
- `sql` (string, required, at most 100000 characters): One SQL statement.
- `branch` (string, optional): Name of a branch of `database`. Only with it may the statement write.

### Output

- `database` (string, always)
- `readOnly` (boolean, always)
- `output` (string, if present)

### Annotations

`readOnlyHint`: `false`, `destructiveHint`: `true`, `idempotentHint`: `false`, `openWorldHint`: `false`

## `computer_create`

**Create a computer.** Creates a computer for an agent: an app with one machine whose checkpoints are stored outside the host, and that can be snapshotted. After a host failure it comes back from its last checkpoint, and whatever changed after that checkpoint is lost; without a checkpoint it starts fresh from the image. Use it when a task needs a place of its own to work, not a one-shot command.

### Input

- `name` (string, required): Name of the computer, e.g. `agent-1`.
- `image` (string, required): OCI reference of the image to run, e.g. an image with a shell and a coding agent in it.
- `memoryMb` (integer, optional, 256 to 16384): Memory in MB (256 to 16384, default 512).
- `volumeGb` (integer, optional, 1 to 500): Size of the durable disk in GB (1 to 500). Absent = the image's own disk, which does not survive a host failure.
- `internalPort` (integer, optional, 1 to 65535): Port the image listens on, if it serves one.

### Output

- `app` (string, always)
- `machineId` (string, always)
- `state` (string, if present)

### Annotations

`readOnlyHint`: `false`, `destructiveHint`: `false`, `idempotentHint`: `false`, `openWorldHint`: `false`

## `computer_exec`

**Run a command in a computer.** Runs one command in a machine of an app of your org and returns its output. This is a shell in someone's machine: treat every argument as untrusted input and never build a command line from text a user pasted without checking it. The command does not go through a shell - pass argv.

### Input

- `app` (string, required): Name of the app whose machine the command runs in.
- `command` (array of string, required, 1 to 64 items): The command and its arguments, e.g. [`git`, `status`]. Not a shell line.
- `machineId` (string, optional): Optional: run in this machine of the app instead of its first running one.
- `timeoutS` (integer, optional, 1 to 300): Deadline of the command in seconds (1 to 300, default 60).

### Output

- `machineId` (string, always)
- `exitCode` (integer or null, if present)
- `stdout` (string, always)
- `stderr` (string, if present)
- `truncated` (boolean, if present)

### Annotations

`readOnlyHint`: `false`, `destructiveHint`: `true`, `idempotentHint`: `false`, `openWorldHint`: `false`

## `computer_snapshot`

**Snapshot a computer.** Takes a named snapshot of a computer's disk (and, with `memory: true`, its running memory) that can be restored later, on any host. Without `memory` the snapshot holds the disk alone, and a restore from it boots cold. Use it before a risky step, so the state before it can be brought back.

### Input

- `app` (string, required): Name of the app the computer belongs to.
- `label` (string, required, at most 63 characters): Name of the snapshot, unique within the machine, e.g. `before-migration`. Letters, digits, dot, dash and underscore, starting with a letter or digit; `auto-` at the start is reserved for the platform's own snapshots.
- `machineId` (string, optional): Optional: snapshot this machine of the app instead of its first running one.
- `memory` (boolean, optional): True: include the running memory, so a restore resumes the processes (a long pause for a big machine). false (default): the disk alone, a restore boots cold.

### Output

- `machineId` (string, always)
- `label` (string, always)
- `id` (string, if present)

### Annotations

`readOnlyHint`: `false`, `destructiveHint`: `false`, `idempotentHint`: `true`, `openWorldHint`: `false`

---

<!-- SDK & MCP: https://docs.rytiv.com/sdk/typescript/ -->

# TypeScript SDK

> A typed client for Rytiv in TypeScript follows. Until it is published, the REST API is a few lines of fetch, and the MCP server gives your agent the same platform as tools.

> **Not published yet:** The TypeScript SDK is not published yet. This page will carry the install command and a quickstart once it is. Everything it will do is a plain HTTP call today, see below, and your coding agent already has the platform as [MCP tools](https://docs.rytiv.com/reference/mcp-tools.md).

## What it will do

A typed client for the same API the CLI and the MCP server use: computers, sandboxes, apps, machines, deploys, databases and buckets, with errors you can branch on (`code`). It will read your key from `RYTIV_TOKEN`, like the CLI.

## Until then: the REST API

Everything the SDK will do is a plain HTTP call today. A small helper is enough:

```ts
const API = process.env.RYTIV_ENDPOINT ?? "https://api.rytiv.app";

async function rytiv(path: string, init: RequestInit = {}) {
  const res = await fetch(`${API}/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.RYTIV_TOKEN}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  const body = res.status === 204 ? null : await res.json();
  if (!res.ok) throw new Error(`${body?.code ?? res.status}: ${body?.error ?? res.statusText}`);
  return body;
}

const sandbox = await rytiv("/sandboxes", {
  method: "POST",
  body: JSON.stringify({ template: "app:web", ttlSeconds: 600 }),
});
const result = await rytiv(`/sandboxes/${sandbox.id}/exec`, {
  method: "POST",
  body: JSON.stringify({ cmd: ["node", "--version"] }),
});
console.log(result.stdout);
await rytiv(`/sandboxes/${sandbox.id}`, { method: "DELETE" });
```

The same in Python:

```python
import os, requests

API = os.environ.get("RYTIV_ENDPOINT", "https://api.rytiv.app")
HEADERS = {"Authorization": f"Bearer {os.environ['RYTIV_TOKEN']}"}

def rytiv(method, path, **kwargs):
    res = requests.request(method, f"{API}/v1{path}", headers=HEADERS, **kwargs)
    if res.status_code == 204:
        return None
    body = res.json()
    if not res.ok:
        raise RuntimeError(f"{body.get('code', res.status_code)}: {body.get('error')}")
    return body

sandbox = rytiv("POST", "/sandboxes", json={"template": "app:web", "ttlSeconds": 600})
result = rytiv("POST", f"/sandboxes/{sandbox['id']}/exec", json={"cmd": ["node", "--version"]})
print(result["stdout"])
rytiv("DELETE", f"/sandboxes/{sandbox['id']}")
```

See [REST API basics](https://docs.rytiv.com/reference/api-basics.md) for the error format, and the [API reference](https://docs.rytiv.com/reference/api.md) for every route with its fields.

## MCP

The MCP server at `https://api.rytiv.app/v1/mcp` is the SDK your coding agent uses today: eleven tools for apps, logs, secrets, Postgres and computers, each with annotations your client can use to decide what to confirm. See [MCP tools](https://docs.rytiv.com/reference/mcp-tools.md) and the [quickstart](https://docs.rytiv.com/quickstart.md).