> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API key permissions

> What a restricted key can call, endpoint by endpoint, and what kinds of endpoint no restricted key can call.

Every API key has access, a scope and an expiry. This page covers access: which endpoints a key may call. Scope (all workspaces, one workspace or one computer) is described in [Key scopes and computer keys](https://docs.orgo.ai/api-reference/api-keys/computer-keys.md). Expiry is described in [Key expiry and rotation](https://docs.orgo.ai/api-reference/api-keys/expiry-and-rotation.md).

A key has full access, or it is restricted. A restricted key has a level in each of eleven permission groups. It can call only the endpoints listed for its groups, at their level, and nothing else.

Orgo checks this on every request, before the endpoint runs. The same table drives the check and this page. You can also download [the mapping as CSV](https://docs.orgo.ai/api-reference/api-keys/permissions.csv): one row per method and path a key may call, with its group, level, and whether a one-computer key may call it.

## Permission levels

Each group has one of three levels.

| Level | What the key can call in the group |
| - | - |
| `none` | Nothing. |
| `read` | The endpoints marked Read. |
| `write` | The endpoints marked Read and Write. Write includes read. |

Read is not harmless in every group. Control read takes screenshots of a computer's screen and reads files on it. Secrets read lists the names of your secrets, never their values.

## Presets

Settings, API keys offers three choices. The API takes the same three.

| Preset | What it means | Send as `permissions` | Answered as |
| - | - | - | - |
| **Full access** | Everything you can do, including managing keys. | Leave it out, or send `"full"` | `"permissions": null`, `"access": "full"` |
| **Read only** | Read in every group. Changes nothing. A few reads need write, as the tables below show, such as a computer's screen password, its live screen and terminal, and a workspace's share link. | `"read_only"` | Read in every group, `"access": "read_only"` |
| **Custom** | You pick a level for each group. | An object of group to level, such as `{ "computers": "write", "control": "write" }`. A group you leave out is `none`. | Every group listed, `"access": "custom"` |

Every key made before permissions existed has full access. So do the keys Orgo makes for its own apps, such as Bops for iPhone. A computer's own key is held to a fixed list instead, described in [What a computer key can call](https://docs.orgo.ai/api-reference/api-keys/computer-keys.md#what-a-computer-key-can-call).

> [!NOTE]
>
> Custom with Write in every group is still a restricted key, not full access. It cannot call the endpoints described in [Endpoints a restricted key never uses](#endpoints-a-restricted-key-never-uses), and it cannot make a full access key.

## Permission groups

The API names each group in lowercase. Settings shows the label.

| Group | Label in Settings | What it covers |
| - | - | - |
| `computers` | Computers | Create, start, stop, resize and delete computers. |
| `control` | Control | Screenshots, commands, mouse and keyboard on a computer. |
| `files` | Files | Files stored in Orgo. |
| `templates` | Templates | Templates and their builds. |
| `workspaces` | Workspaces | Workspaces, their names and settings. |
| `members` | Members | People, invites and share links. |
| `secrets` | Secrets | Secret names, and setting or using them. |
| `ai` | AI | Models, chats and agents. |
| `bops` | Bops | What the Bops app keeps in Orgo. |
| `billing` | Billing | Plan, credits and invoices. |
| `keys` | API keys | Make, change and revoke keys, never past the key's own access. |

## When a key lacks the permission

A restricted key that calls an endpoint outside its groups is refused before the endpoint runs. Every endpoint answers `403` with `code: "key_permission"`. The message names the call, and the group and level the key would need. [Execute bash](https://docs.orgo.ai/api-reference/computers/bash.md) without Control write answers:

```json theme={null}
{
  "error": "This key can’t run a shell command on the computer (it needs Control write access).",
  "code": "key_permission"
}
```

Make a key with the level the message names. An endpoint no restricted key may call says `(it needs full access)` instead: use a full access key or sign in, as described in [Endpoints a restricted key never uses](#endpoints-a-restricted-key-never-uses).

The [Computer Use API](https://docs.orgo.ai/api-reference/chat/completions.md) and [threads](https://docs.orgo.ai/api-reference/chat/threads.md) answer in their OpenAI style envelope, with the same status and code: `{ "error": { "type": "permission_error", "message": "…", "code": "key_permission" } }`.

Scope is checked as well. A restricted key for one workspace can call only its groups' endpoints, and only for that workspace.

A key for one workspace never manages people or deletes its workspace, whatever its permissions. Inviting, changing or removing members, share links (even listing them) and deleting the workspace answer `403` with `code: "workspace_scope_mismatch"`, or `key_permission` first when a restricted key lacks the level the endpoint needs, as described in [What a workspace-scoped key can do](https://docs.orgo.ai/api-reference/authentication.md#what-a-workspace-scoped-key-can-do). So Settings offers it Members at Read at most, and the API refuses Members write for it with `400` and `code: "invalid_permissions"`.

## Computers that hold their own key

A computer can hold its own Orgo key, a computer key, such as one that runs your Bops bots. That key has full access to its computer and never expires. Anything that controls the computer can read that key. So a restricted key, or one that expires, can't control such a computer: the Control and AI endpoints about it (its screen, files, commands, terminal and agent), the Desktop API proxy and its screen password answer `403`:

```json theme={null}
{
  "error": "This computer holds its own Orgo key, which has full access and never expires, and whatever acts on the computer can read it. A restricted or expiring key can’t control it, read its files or run its agent. Use a full access key that never expires, or the web app.",
  "code": "computer_key_held"
}
```

Its Computers endpoints, such as start, stop and get, still work. Use a full access key that never expires for such a computer. Computer keys are described in [Key scopes and computer keys](https://docs.orgo.ai/api-reference/api-keys/computer-keys.md#computer-keys-made-by-orgo).

## How to read the tables

* Paths are relative to `https://www.orgo.ai`. `{id}` and other braces are path parameters.
* Workspace paths are written `/api/projects/...`. `/api/workspaces/...` is the same endpoint and needs the same permission.
* `HEAD` needs what `GET` needs.
* `WebSocket` rows are connections such as `wss://www.orgo.ai/desktops/{id}/ws/websockify`.

This page lists the 510 endpoints a key may call. Every other endpoint is one of the kinds described in [Endpoints a restricted key never uses](#endpoints-a-restricted-key-never-uses).

## Computers group

Records and lifecycle of computers: list and read them; create, delete, start, stop, suspend, resume, resize, copy, back up, restore and move them.

27 read, 43 write.

| Method | Path | Level | What it does |
| - | - | - | - |
| POST | `/api/computers` | Write | Creates a computer in a workspace, on the plan or billed by the hour. |
| GET | `/api/computers/starred` | Read | Lists the ids of the computers the caller has starred. |
| POST | `/api/computers/usage` | Read | Reads CPU, memory and disk use for up to 100 computers at once. |
| GET | `/api/computers/{id}` | Read | Gets a computer with its status, hardware and connection details. |
| PATCH | `/api/computers/{id}` | Write | Renames a computer or changes its bot mascot. |
| DELETE | `/api/computers/{id}` | Write | Deletes a computer and everything on it. |
| GET | `/api/computers/{id}/auto-stop` | Read | Gets the computer's auto-stop setting. |
| PATCH | `/api/computers/{id}/auto-stop` | Write | Sets how many idle minutes pass before the computer stops by itself. |
| POST | `/api/computers/{id}/backup/restore` | Write | Restores a computer from a daily backup, as a new computer or in place. |
| GET | `/api/computers/{id}/backups` | Read | Lists the computer's daily backups and whether it can be restored now. |
| POST | `/api/computers/{id}/billing` | Write | Moves a computer billed by the hour onto the account's plan. |
| POST | `/api/computers/{id}/clone` | Write | Makes a new computer as a copy of this one's disk. |
| GET | `/api/computers/{id}/domains` | Read | Lists the computer's custom domains. |
| POST | `/api/computers/{id}/domains` | Write | Adds a custom domain to the computer and returns the DNS records to set. |
| GET | `/api/computers/{id}/domains/{domainId}` | Read | Gets one custom domain with its DNS records. |
| PATCH | `/api/computers/{id}/domains/{domainId}` | Write | Points a custom domain at another port on the computer. |
| DELETE | `/api/computers/{id}/domains/{domainId}` | Write | Removes a custom domain from the computer. |
| GET | `/api/computers/{id}/domains/{domainId}/dns-check` | Read | Shows what a custom domain's DNS has right now, record by record, without changing anything. |
| POST | `/api/computers/{id}/domains/{domainId}/verify` | Write | Checks a custom domain's DNS records and turns it on when they are right. |
| GET | `/api/computers/{id}/egress` | Read | Shows what the computer is allowed to reach on the internet. |
| GET | `/api/computers/{id}/egress/upstream` | Read | Shows which route the computer's browser traffic leaves through. |
| POST | `/api/computers/{id}/egress/upstream` | Write | Chooses which route the computer's browser traffic leaves through. |
| POST | `/api/computers/{id}/ensure-running` | Read | Returns the computer's status and connection details without starting it. |
| POST | `/api/computers/{id}/fork` | Write | Makes a live copy of a running computer, memory included. |
| POST | `/api/computers/{id}/freeze` | Write | Stops the computer and keeps its disk, the same as stop. |
| POST | `/api/computers/{id}/heal` | Write | Tries to fix a computer that is not answering, or restarts it when asked. |
| GET | `/api/computers/{id}/health` | Read | Runs health checks on the computer without changing anything. |
| GET | `/api/computers/{id}/mac-jobs/{jobId}` | Read | Gets one restore of a Mac computer: its phase, its step on the Mac and how far the copy is. |
| POST | `/api/computers/{id}/mac-jobs/{jobId}/cancel` | Write | Cancels a restore of a Mac computer before it changes the disk. |
| POST | `/api/computers/{id}/mac-jobs/{jobId}/retry` | Write | Tries a failed restore of a Mac computer again. |
| PATCH | `/api/computers/{id}/move` | Write | Moves the computer to another workspace. |
| GET | `/api/computers/{id}/operations/{operationId}` | Read | Gets the progress of a start, stop or restore on the computer. |
| GET | `/api/computers/{id}/public-urls` | Read | Lists the computer's public URLs. |
| POST | `/api/computers/{id}/public-urls` | Write | Makes a public URL that serves a port on the computer. |
| PATCH | `/api/computers/{id}/public-urls/{urlId}` | Write | Points a public URL at another port on the computer. |
| DELETE | `/api/computers/{id}/public-urls/{urlId}` | Write | Removes a public URL from the computer. |
| GET | `/api/computers/{id}/residential-proxy` | Read | Shows whether the computer's browser uses a residential IP and how much data is left. |
| POST | `/api/computers/{id}/residential-proxy` | Write | Turns the residential proxy on or off for the computer, or gets a new IP. |
| GET | `/api/computers/{id}/resize` | Read | Shows how far the computer can be resized on the current plan. |
| PATCH | `/api/computers/{id}/resize` | Write | Changes the computer's CPU, memory or disk size. |
| POST | `/api/computers/{id}/restart` | Write | Restarts the computer. |
| POST | `/api/computers/{id}/resume` | Write | Resumes a suspended computer where it left off. |
| GET | `/api/computers/{id}/runtime` | Read | Gets the computer's record of suspends, resumes and wipes. |
| GET | `/api/computers/{id}/snapshots` | Read | Lists the computer's snapshots. |
| DELETE | `/api/computers/{id}/snapshots/{snapId}` | Write | Deletes one of a Mac computer's snapshots. |
| POST | `/api/computers/{id}/snapshots/{snapId}/restore` | Write | Puts a Mac computer's disk back to one of its snapshots. |
| POST | `/api/computers/{id}/star` | Write | Stars or unstars the computer for the caller. |
| POST | `/api/computers/{id}/start` | Write | Starts a stopped computer. |
| POST | `/api/computers/{id}/stop` | Write | Stops the computer and keeps its disk. |
| POST | `/api/computers/{id}/suspend` | Write | Suspends the computer with its memory saved, so it resumes where it left off. |
| GET | `/api/computers/{id}/suspension` | Read | Gets the computer's status and the progress of a suspend or resume. |
| POST | `/api/computers/{id}/update-rootfs` | Write | Updates the computer's operating system image and keeps its data. |
| POST | `/api/computers/{id}/wake` | Write | Starts a stopped computer, the same as start. |
| POST | `/api/computers/{id}/webrtc` | Write | Turns UDP video streaming on or off for the computer. |
| GET | `/api/egress-devices` | Read | Lists the caller's own devices paired to carry computers' internet traffic. |
| POST | `/api/egress-devices` | Write | Pairs a device to carry computers' internet traffic and returns its setup commands. |
| DELETE | `/api/egress-devices/{id}` | Write | Removes a paired device and moves its computers back to direct internet. |
| GET | `/api/egress-ips` | Read | Lists the account's dedicated IP addresses and how many more it may hold. |
| POST | `/api/egress-ips` | Write | Gets a dedicated IP address and can route a computer through it. |
| GET | `/api/egress-ips/{id}` | Read | Shows one dedicated IP address and the computer it routes. |
| PATCH | `/api/egress-ips/{id}` | Write | Routes a dedicated IP address to a computer or detaches it. |
| DELETE | `/api/egress-ips/{id}` | Write | Gives back a dedicated IP address. |
| GET | `/api/fleet/devices` | Read | Lists the machines the caller brought in as their own computers. |
| POST | `/api/fleet/devices/enroll-tokens` | Write | Makes a one time token to bring the caller's own Mac or iPhone in as a computer. |
| POST | `/api/fleet/devices/{id}/revoke` | Write | Removes one of the caller's own devices and the computer that showed its screen. |
| GET | `/api/obs/{id}` | Read | Shows a computer's live CPU, memory and disk use. |
| GET | `/api/projects/by-name/{name}/computers` | Read | Lists the computers in a workspace found by its name. |
| POST | `/api/projects/by-name/{name}/computers` | Write | Creates a Linux computer in a workspace found by its name. |
| GET | `/api/user/trial` | Read | Shows the account's free trial computer and how long it has left. |
| POST | `/api/user/trial` | Write | Starts a free trial computer from a starter. |

## Control group

Using a running computer: screenshots and files on it (read); its live screen, commands, clicks, typing, a terminal, apps and deploys that run on it (write).

28 read, 51 write.

| Method | Path | Level | What it does |
| - | - | - | - |
| GET | `/api/bot/computers/{id}/files` | Read | Lists the files on a computer that the agent's file view shows. |
| GET | `/api/bot/computers/{id}/files/content` | Read | Downloads one file from a computer. |
| POST | `/api/computers/{id}/bash` | Write | Runs a shell command on the computer and returns its output. |
| POST | `/api/computers/{id}/click` | Write | Clicks at a point on the computer's screen. |
| GET | `/api/computers/{id}/clone` | Read | Shows a phone's iPhone clone settings, latest jobs and ready uploads. |
| GET | `/api/computers/{id}/clone/apps` | Read | Lists the apps queued or installing on the phone through iPhone clone. |
| POST | `/api/computers/{id}/clone/apps` | Write | Queues apps to install on the phone from the App Store. |
| GET | `/api/computers/{id}/clone/apps/catalog` | Read | Searches the App Store, or lists its top free apps, for the clone picker. |
| GET | `/api/computers/{id}/clone/apps/data` | Read | Lists the app data copied from the person's own iPhone for the phone. |
| POST | `/api/computers/{id}/clone/apps/data` | Write | Records which app a finished upload of app data belongs to. |
| GET | `/api/computers/{id}/clone/apps/inventory` | Read | Lists the apps found on the person's own iPhone, matched to the App Store. |
| PUT | `/api/computers/{id}/clone/apps/inventory` | Write | Replaces the list of apps reported from the person's own iPhone. |
| POST | `/api/computers/{id}/clone/apps/inventory/agent` | Write | Records a check in from the clone helper on the person's Mac and says whether a new app list is wanted. |
| POST | `/api/computers/{id}/clone/apps/inventory/refresh` | Write | Asks the person's Mac for a fresh list of the apps on their iPhone. |
| GET | `/api/computers/{id}/clone/apps/{jobId}` | Read | Gets the progress of one app installing on the phone. |
| POST | `/api/computers/{id}/clone/backup` | Write | Starts restoring an encrypted iPhone backup onto the phone. |
| GET | `/api/computers/{id}/clone/browser-sessions` | Read | Lists the websites the phone has saved browser sign-ins for. |
| POST | `/api/computers/{id}/clone/browser-sessions` | Write | Records a saved Safari sign-in store uploaded for the phone. |
| POST | `/api/computers/{id}/clone/icloud` | Write | Opens the iCloud restore checklist for the phone. |
| PUT | `/api/computers/{id}/clone/icloud/step` | Write | Ticks or unticks one step of the iCloud restore checklist. |
| GET | `/api/computers/{id}/clone/jobs/{jobId}` | Read | Gets the progress of one iPhone clone job. |
| POST | `/api/computers/{id}/clone/lite` | Write | Starts copying uploaded photos, files and contacts onto the phone. |
| PUT | `/api/computers/{id}/clone/settings` | Write | Turns one part of iPhone clone on or off for the phone. |
| GET | `/api/computers/{id}/clone/uploads` | Write | Lists the files uploaded for the phone with links to download them. |
| POST | `/api/computers/{id}/clone/uploads` | Write | Starts an upload for the phone and returns the links to send the file to storage. |
| POST | `/api/computers/{id}/clone/uploads/{uploadId}/complete` | Write | Marks an upload for the phone as finished once all its bytes are stored. |
| GET | `/api/computers/{id}/deploy-projects` | Read | Lists the computer's GitHub deploys and the linked GitHub accounts. |
| POST | `/api/computers/{id}/deploy-projects` | Write | Imports a GitHub repository to deploy on the computer and queues its first deploy. |
| GET | `/api/computers/{id}/deploy-projects/{projectId}` | Read | Gets one GitHub deploy with its recent deployments. |
| PATCH | `/api/computers/{id}/deploy-projects/{projectId}` | Write | Changes a GitHub deploy's settings, such as its branch, port and build commands. |
| DELETE | `/api/computers/{id}/deploy-projects/{projectId}` | Write | Removes a GitHub deploy with its app and deployments from the computer. |
| GET | `/api/computers/{id}/deploy-projects/{projectId}/deployments` | Read | Lists a deploy's newest deployments. |
| POST | `/api/computers/{id}/deploy-projects/{projectId}/deployments` | Write | Deploys the newest commit, or a chosen one, to the computer. |
| GET | `/api/computers/{id}/deploy-projects/{projectId}/env` | Read | Lists the names of a deploy's environment variables. |
| PATCH | `/api/computers/{id}/deploy-projects/{projectId}/env` | Write | Sets or removes a deploy's environment variables. |
| GET | `/api/computers/{id}/deployments/{deploymentId}` | Read | Gets one deployment's state, phase and commit. |
| POST | `/api/computers/{id}/deployments/{deploymentId}/cancel` | Write | Cancels a queued or running deployment. |
| GET | `/api/computers/{id}/deployments/{deploymentId}/logs` | Read | Reads a deployment's build log. |
| POST | `/api/computers/{id}/deployments/{deploymentId}/rollback` | Write | Puts an earlier deployment live again without building it. |
| POST | `/api/computers/{id}/drag` | Write | Drags the mouse from one point to another on the computer. |
| POST | `/api/computers/{id}/exec` | Write | Runs Python code on the computer and returns its output. |
| POST | `/api/computers/{id}/key` | Write | Presses a key or key combination on the computer. |
| POST | `/api/computers/{id}/mouse-move` | Write | Moves the pointer on the computer's screen without clicking. |
| GET | `/api/computers/{id}/screens` | Read | Lists the screens on the computer. |
| POST | `/api/computers/{id}/screens` | Write | Adds a screen to the computer. |
| GET | `/api/computers/{id}/screens/{screenId}` | Read | Gets one screen on the computer. |
| PATCH | `/api/computers/{id}/screens/{screenId}` | Write | Resizes one screen on the computer. |
| DELETE | `/api/computers/{id}/screens/{screenId}` | Write | Removes a screen from the computer. |
| GET | `/api/computers/{id}/screenshot` | Read | Takes a screenshot of the computer's screen. |
| POST | `/api/computers/{id}/scroll` | Write | Scrolls on the computer's screen. |
| GET | `/api/computers/{id}/services` | Read | Lists the apps that run on the computer and their state. |
| POST | `/api/computers/{id}/services` | Write | Adds an app that runs on the computer and starts it. |
| PATCH | `/api/computers/{id}/services/{serviceId}` | Write | Changes an app that runs on the computer. |
| DELETE | `/api/computers/{id}/services/{serviceId}` | Write | Removes an app that runs on the computer. |
| GET | `/api/computers/{id}/services/{serviceId}/logs` | Read | Reads the last lines of an app's log on the computer. |
| POST | `/api/computers/{id}/services/{serviceId}/restart` | Write | Restarts an app on the computer. |
| POST | `/api/computers/{id}/skills/install` | Write | Installs uploaded skill files onto the computer. |
| GET | `/api/computers/{id}/ssh` | Read | Shows the computer's SSH address and whether a key is set. |
| POST | `/api/computers/{id}/ssh` | Write | Sets the SSH public key for the computer. |
| DELETE | `/api/computers/{id}/ssh` | Write | Turns off SSH access to the computer and removes its keys. |
| POST | `/api/computers/{id}/type` | Write | Types text on the computer. |
| GET | `/api/computers/{id}/vnc-password` | Write | Gets the computer's VNC password and its Desktop API token. |
| POST | `/api/computers/{id}/wait` | Write | Waits a number of seconds on the computer. |
| GET | `/api/desktops/{id}/proxy/{...path}` | Read | Passes a read request through to the computer's Desktop API. |
| HEAD | `/api/desktops/{id}/proxy/{...path}` | Read | Passes a read request through to the computer's Desktop API. |
| POST | `/api/desktops/{id}/proxy/{...path}` | Write | Passes a request that acts on the computer through to its Desktop API. |
| PUT | `/api/desktops/{id}/proxy/{...path}` | Write | Passes a request that acts on the computer through to its Desktop API. |
| PATCH | `/api/desktops/{id}/proxy/{...path}` | Write | Passes a request that acts on the computer through to its Desktop API. |
| DELETE | `/api/desktops/{id}/proxy/{...path}` | Write | Passes a request that acts on the computer through to its Desktop API. |
| GET | `/api/projects/{id}/vnc-password` | Write | Returns the screen sharing password of a computer in the workspace, for its owner. |
| GET | `/api/screenshot` | Read | Takes a screenshot of a computer. |
| GET | `/api/trident/agent/files` | Read | Lists the files the Trident agent left on its computer, or shows one. |
| DELETE | `/api/trident/agent/files` | Write | Deletes a file the Trident agent left on its computer. |
| WebSocket | `/desktops/{id}/ws/audio` | Read | Streams the computer's sound. |
| WebSocket | `/desktops/{id}/ws/rtc` | Write | Streams the computer's screen over WebRTC, with its mouse and keyboard. |
| WebSocket | `/desktops/{id}/ws/stats` | Read | Streams the live statistics of a screen connection. |
| WebSocket | `/desktops/{id}/ws/terminal` | Write | Opens a terminal on the computer. |
| WebSocket | `/desktops/{id}/ws/websockify` | Write | Streams the computer's screen over VNC, with its mouse and keyboard. |
| WebSocket | `/desktops/{id}/ws/{...path}` | Write | Opens any other live connection to the computer. |

## Files group

Files stored in Orgo.

4 read, 5 write.

| Method | Path | Level | What it does |
| - | - | - | - |
| GET | `/api/files` | Read | Lists the files stored for a workspace. |
| DELETE | `/api/files/delete` | Write | Deletes a stored file. |
| GET | `/api/files/download` | Read | Returns a one hour download link for a stored file. |
| POST | `/api/files/export` | Write | Copies a file off a computer into file storage and returns a download link. |
| POST | `/api/files/upload` | Write | Uploads a file of up to 10 MB to a workspace and can place it on a computer. |
| POST | `/api/files/uploads` | Write | Starts a large file upload to a computer and returns an upload link. |
| POST | `/api/files/uploads/complete` | Write | Finishes a large upload by having the computer pull the file into its folder. |
| GET | `/api/me/storage` | Read | Shows where the caller's skill and app files are kept and how much space they use. |
| GET | `/api/storage/{...key}` | Read | Serves a stored icon, avatar, workspace file or screenshot. |

## Templates group

Templates: read them; publish, build and run previews (write).

13 read, 11 write.

| Method | Path | Level | What it does |
| - | - | - | - |
| GET | `/api/builds` | Read | Lists the account's finished template image builds. |
| POST | `/api/builds/create` | Write | Records a new template image build and returns where to push the image. |
| GET | `/api/builds/latest` | Read | Returns the newest finished image build of a named template. |
| POST | `/api/builds/update` | Write | Updates a template image build's status, error and logs. |
| GET | `/api/templates` | Read | Lists the account's templates. |
| POST | `/api/templates` | Write | Publishes a new template version and can start its build. |
| GET | `/api/templates/apps` | Read | Lists the apps the template editor offers, each with the template text it adds. |
| GET | `/api/templates/apps/recipes` | Read | Returns the template editor's app catalog. |
| GET | `/api/templates/build-jobs` | Read | Lists the account's template build jobs and whether each is ready. |
| POST | `/api/templates/generate` | Write | Writes a template from a description with AI, paid from AI credits. |
| GET | `/api/templates/global` | Read | Lists Orgo's curated templates. |
| GET | `/api/templates/global/{namespace}/{name}` | Read | Lists every version of one curated template. |
| POST | `/api/templates/run` | Write | Starts a short lived test computer from a template for its author. |
| DELETE | `/api/templates/run` | Write | Stops a test computer started from a template. |
| POST | `/api/templates/run/stop` | Write | Stops a test computer started from a template, for a browser tab that is closing. |
| POST | `/api/templates/summarize` | Write | Streams a short AI summary of what a template builds, paid from AI credits. |
| POST | `/api/templates/validate` | Read | Checks a template for errors without saving it. |
| GET | `/api/templates/{namespace}/{name}` | Read | Lists every version of one of the account's templates. |
| GET | `/api/templates/{namespace}/{name}/{version}` | Read | Returns one template version. |
| DELETE | `/api/templates/{namespace}/{name}/{version}` | Write | Deletes a template version everywhere, cancelling its builds and removing its saved image. |
| GET | `/api/templates/{namespace}/{name}/{version}/build` | Read | Returns whether a template version's image is built, building, failed or not built. |
| POST | `/api/templates/{namespace}/{name}/{version}/build` | Write | Starts building a template version's image. |
| DELETE | `/api/templates/{namespace}/{name}/{version}/build` | Write | Cancels a template version's image build. |
| GET | `/api/templates/{namespace}/{name}/{version}/build/events` | Read | Streams the live progress of a template version's image build. |

## Workspaces group

Workspaces: list and read them; create, rename and delete them (write).

23 read, 17 write.

| Method | Path | Level | What it does |
| - | - | - | - |
| GET | `/api/integrations/github` | Read | Shows the GitHub accounts linked to the workspace. |
| GET | `/api/integrations/github/branches` | Read | Lists the branches of a GitHub repository the workspace can import. |
| GET | `/api/integrations/github/repos` | Read | Lists the GitHub repositories the workspace can import. |
| GET | `/api/me` | Read | Shows the caller's account id, email and which features it may use. |
| GET | `/api/projects` | Read | Lists the workspaces the caller owns or belongs to, with their computers. |
| POST | `/api/projects` | Write | Creates a workspace. |
| GET | `/api/projects/by-name/{name}` | Read | Returns a workspace found by its name. |
| GET | `/api/projects/{id}` | Read | Returns a workspace with its computers. |
| PATCH | `/api/projects/{id}` | Write | Renames a workspace or changes its icon, status or private screens setting. |
| DELETE | `/api/projects/{id}` | Write | Deletes a workspace and everything in it. |
| GET | `/api/projects/{id}/activity` | Read | Lists the workspace's activity, newest first, for people with full access. |
| GET | `/api/projects/{id}/automations` | Read | Returns the workspace's automation, its latest run and the results it found. |
| GET | `/api/projects/{id}/capacity` | Read | Returns how full the workspace's dedicated servers are. |
| POST | `/api/projects/{id}/delete` | Write | Deletes a workspace and everything in it. |
| GET | `/api/projects/{id}/delete-preview` | Read | Lists the computers, keys, skills and apps that would go with the workspace if it were deleted. |
| GET | `/api/projects/{id}/domains` | Read | Lists the workspace's free names under Orgo's domain and the domains it bought. |
| GET | `/api/projects/{id}/domains/{domainId}` | Read | Gets one domain the workspace bought, with the names that point at its computers. |
| GET | `/api/projects/{id}/domains/{domainId}/dns` | Read | Shows where a bought domain's DNS is answered and every record in its zone. |
| POST | `/api/projects/{id}/domains/{domainId}/dns/records` | Write | Adds a DNS record to a bought domain. |
| PATCH | `/api/projects/{id}/domains/{domainId}/dns/records/{recordId}` | Write | Changes one DNS record of a bought domain. |
| DELETE | `/api/projects/{id}/domains/{domainId}/dns/records/{recordId}` | Write | Removes one DNS record from a bought domain. |
| PUT | `/api/projects/{id}/domains/{domainId}/nameservers` | Write | Switches a bought domain between Orgo DNS and nameservers of the owner's choice. |
| POST | `/api/projects/{id}/icon` | Write | Uploads a new icon for the workspace. |
| GET | `/api/projects/{id}/skills` | Read | Lists the workspace's skills and apps, or what changed and what was deleted since a given time. |
| POST | `/api/projects/{id}/skills` | Write | Creates a workspace skill from its instructions and files. |
| GET | `/api/projects/{id}/skills/approvals` | Read | Lists which skill scripts a person has approved to run in the workspace. |
| POST | `/api/projects/{id}/skills/approvals` | Write | Approves a skill script to run in the workspace, by a signed in person or the Bops app they signed in to, never another key. |
| DELETE | `/api/projects/{id}/skills/approvals` | Write | Revokes a person's approval of a skill script, by a signed in person or the Bops app they signed in to, never another key. |
| POST | `/api/projects/{id}/skills/import` | Write | Imports a folder of files as a new draft skill. |
| GET | `/api/projects/{id}/skills/{skillId}` | Read | Returns a workspace skill with one version's instructions and file list. |
| PATCH | `/api/projects/{id}/skills/{skillId}` | Write | Changes a skill's name, description, bots or status. |
| DELETE | `/api/projects/{id}/skills/{skillId}` | Write | Deletes a skill with every version and file. |
| GET | `/api/projects/{id}/skills/{skillId}/download` | Read | Returns a skill version's files with short lived download links, for installing it on a computer. |
| GET | `/api/projects/{id}/skills/{skillId}/export` | Read | Returns a skill version as a folder of files to save or import again. |
| GET | `/api/projects/{id}/skills/{skillId}/files/{...path}` | Read | Returns one file of a skill version as text, a download link or its raw bytes. |
| POST | `/api/projects/{id}/skills/{skillId}/rollback` | Write | Points a skill back at one of its earlier versions. |
| POST | `/api/projects/{id}/skills/{skillId}/versions` | Write | Publishes a new version of a skill. |
| GET | `/api/projects/{id}/timeline` | Read | Returns the workspace's recent API activity and screenshots. |
| GET | `/api/user/profile` | Read | Shows the account's id, email, name and plan status. |
| GET | `/api/user/project-limit` | Read | Shows how many workspaces the account's plan allows. |

## Members group

People, invites and share links.

1 read, 9 write.

| Method | Path | Level | What it does |
| - | - | - | - |
| POST | `/api/projects/{id}/accept-invite` | Write | Accepts an invite to the workspace as the caller. |
| POST | `/api/projects/{id}/invite` | Write | Invites a person to the workspace by email. |
| DELETE | `/api/projects/{id}/invite` | Write | Revokes a pending invite to the workspace. |
| GET | `/api/projects/{id}/members` | Read | Lists the workspace's members and open invites. |
| PATCH | `/api/projects/{id}/members` | Write | Changes a member's role in the workspace. |
| DELETE | `/api/projects/{id}/members` | Write | Removes a member from the workspace, or the caller themselves. |
| GET | `/api/projects/{id}/share-link` | Write | Lists the workspace's live share links with the links people join by. |
| POST | `/api/projects/{id}/share-link` | Write | Makes a share link anyone can use to join the workspace. |
| DELETE | `/api/projects/{id}/share-link` | Write | Revokes a workspace share link. |
| POST | `/api/share/{code}/claim` | Write | Joins the workspace through a share link as the caller. |

## Secrets group

The names of your secrets (read); setting, deleting, applying and using them (write). Revealing a value is never a key’s. Putting them on a computer is write: a key without Secrets write launches a template as if you had saved no secrets (the computer gets none of yours), and can’t ask for Build & launch (`403` with `code: "key_permission"`).

5 read, 7 write.

| Method | Path | Level | What it does |
| - | - | - | - |
| GET | `/api/bot/computers/{id}/agent-env` | Read | Lists the names of the keys an agent holds on its computer, showing only their last four characters. |
| POST | `/api/bot/computers/{id}/agent-env` | Write | Writes chosen secrets from the caller's vault into an agent's settings on the computer. |
| POST | `/api/computers/{id}/secrets/sync` | Write | Writes chosen secrets from the vault onto the computer. |
| GET | `/api/identities` | Read | Lists the stored browser sign ins and the computers each may be used on. |
| PATCH | `/api/identities/{id}` | Write | Turns a stored browser sign in on or off. |
| DELETE | `/api/identities/{id}` | Write | Deletes a stored browser sign in. |
| GET | `/api/identities/{id}/history` | Read | Lists what has happened to one stored browser sign in, including each time an agent used it. |
| GET | `/api/secrets` | Read | Lists the names of the account's saved secrets, never their values. |
| POST | `/api/secrets` | Write | Saves a secret to the account or to one workspace. |
| POST | `/api/secrets/call` | Write | Calls a third party API with a saved secret without showing the secret. |
| GET | `/api/secrets/providers` | Read | Lists the APIs a saved secret can call through Orgo. |
| DELETE | `/api/secrets/{name}` | Write | Deletes a saved secret from the account or from one workspace. |

## AI group

Models, chats and agents. Write means it may use them.

64 read, 80 write.

| Method | Path | Level | What it does |
| - | - | - | - |
| GET | `/api/ai` | Read | Lists the models available through the caller's own OpenRouter key. |
| POST | `/api/ai` | Write | Sends a chat completion to OpenRouter using the caller's own OpenRouter key. |
| GET | `/api/apps/catalog` | Read | Lists every app an agent can be connected to. |
| GET | `/api/bot/agent-activity` | Read | Lists what each busy agent in a workspace is doing right now. |
| GET | `/api/bot/agents` | Read | Lists the Orgo Bot agents in a workspace. |
| POST | `/api/bot/agents` | Write | Creates an Orgo Bot agent in a workspace or on one of its computers. |
| GET | `/api/bot/agents/{id}` | Read | Gets one Orgo Bot agent. |
| PATCH | `/api/bot/agents/{id}` | Write | Renames an agent, changes its settings, or moves it to another computer. |
| DELETE | `/api/bot/agents/{id}` | Write | Deletes an agent and leaves its files on the computer. |
| GET | `/api/bot/agents/{id}/connectors` | Read | Lists the connectors an agent can use, the ones it has, and its open requests. |
| DELETE | `/api/bot/agents/{id}/connectors/{provider}` | Write | Removes a connector from an agent and its computer. |
| POST | `/api/bot/agents/{id}/connectors/{provider}/bind` | Write | Gives an agent a connector by putting its key and settings on the agent's computer. |
| POST | `/api/bot/agents/{id}/connectors/{provider}/test` | Write | Runs a connector's check on the agent's computer and records the result. |
| GET | `/api/bot/agents/{id}/credential-requests` | Read | Lists an agent's open requests for a provider key. |
| PATCH | `/api/bot/agents/{id}/credential-requests/{requestId}` | Write | Dismisses an agent's request for a provider key. |
| GET | `/api/bot/agents/{id}/health` | Read | Shows an agent's health over the last 24 hours. |
| GET | `/api/bot/agents/{id}/heartbeat` | Read | Shows whether an agent's heartbeat is installed on its computer. |
| POST | `/api/bot/agents/{id}/heartbeat` | Write | Installs or renews an agent's heartbeat on its computer with a new credential. |
| DELETE | `/api/bot/agents/{id}/heartbeat` | Write | Revokes an agent's heartbeat and removes it from the computer. |
| GET | `/api/bot/agents/{id}/runs` | Read | Lists an agent's recent runs. |
| GET | `/api/bot/agents/{id}/skills/orgo-connect` | Read | Answers that only POST is allowed here. |
| POST | `/api/bot/agents/{id}/skills/orgo-connect` | Write | Installs the current Orgo connect skill on an agent's computer. |
| PUT | `/api/bot/agents/{id}/skills/orgo-connect` | Read | Answers that only POST is allowed here. |
| PATCH | `/api/bot/agents/{id}/skills/orgo-connect` | Read | Answers that only POST is allowed here. |
| DELETE | `/api/bot/agents/{id}/skills/orgo-connect` | Read | Answers that only POST is allowed here. |
| GET | `/api/bot/agents/{id}/snapshots` | Read | Lists an agent's saved snapshots. |
| POST | `/api/bot/agents/{id}/snapshots` | Write | Saves a snapshot of an agent from its computer. |
| GET | `/api/bot/agents/{id}/snapshots/{snapshotId}` | Read | Gets one of an agent's snapshots. |
| DELETE | `/api/bot/agents/{id}/snapshots/{snapshotId}` | Write | Deletes one of an agent's snapshots. |
| POST | `/api/bot/agents/{id}/snapshots/{snapshotId}/restore` | Write | Restores an agent on its computer from a saved snapshot. |
| GET | `/api/bot/alert-channels` | Read | Lists where a workspace is told when one of its agents goes down. |
| POST | `/api/bot/alert-channels` | Write | Adds an email or webhook to be told when an agent goes down. |
| PATCH | `/api/bot/alert-channels/{id}` | Write | Turns an agent alert channel on or off. |
| DELETE | `/api/bot/alert-channels/{id}` | Write | Removes an agent alert channel. |
| GET | `/api/bot/computers/{id}/agent-install` | Read | Shows whether the agent install on a computer has finished. |
| POST | `/api/bot/computers/{id}/agent-install` | Write | Starts installing the Hermes agent on a Linux computer. |
| POST | `/api/bot/computers/{id}/agent-profile` | Write | Sets up a separate home on the computer for a new agent. |
| DELETE | `/api/bot/computers/{id}/agent-profile` | Write | Removes an agent's home from the computer. |
| GET | `/api/bot/computers/{id}/agents` | Read | Lists a computer's agents and what is running on it now. |
| GET | `/api/bot/computers/{id}/codex` | Read | Shows whether Codex is installed and added to the agent on a computer. |
| POST | `/api/bot/computers/{id}/codex` | Write | Installs Codex on a computer and adds it to the agent there. |
| GET | `/api/bot/computers/{id}/credential-requests` | Read | Lists the open key requests from the agent on a computer. |
| GET | `/api/bot/computers/{id}/crons` | Read | Lists the agent's scheduled jobs on a computer. |
| POST | `/api/bot/computers/{id}/hermes/chat` | Write | Sends one chat turn to the agent on a computer and streams its reply. |
| GET | `/api/bot/computers/{id}/runtime-enrollments` | Read | Lists the OpenClaw agents enrolled on a computer. |
| POST | `/api/bot/computers/{id}/runtime-enrollments` | Write | Enrolls an OpenClaw agent already running on a computer as an Orgo agent. |
| POST | `/api/bot/computers/{id}/runtime-enrollments/{enrollmentId}` | Write | Checks an enrolled OpenClaw agent on a computer again and updates its state. |
| DELETE | `/api/bot/computers/{id}/runtime-enrollments/{enrollmentId}` | Write | Revokes an enrolled OpenClaw agent on a computer. |
| GET | `/api/bot/computers/{id}/skills` | Read | Lists the skills installed for the agent on a computer. |
| GET | `/api/bot/connector-configs` | Read | Lists the account's custom Composio settings with their keys hidden. |
| GET | `/api/bot/connectors` | Read | Lists the apps connected for a workspace's agents. |
| GET | `/api/bot/connectors/toolkits` | Read | Searches the apps an agent can connect to. |
| GET | `/api/bot/connectors/toolkits/{slug}` | Read | Shows the ways one app can be connected. |
| GET | `/api/bot/scan` | Read | Checks which computers in a workspace already have an agent. |
| POST | `/api/bot/scan` | Read | Checks which of the listed computers already have an agent. |
| GET | `/api/bot/workspace-skills` | Read | Lists the default skills of the workspace agent. |
| POST | `/api/chat` | Write | Runs a chat turn with the computer use agent on a computer and streams its reply. |
| POST | `/api/chat/compact` | Write | Summarizes a chat thread's older turns so the next run starts smaller. |
| POST | `/api/chat/inject` | Write | Adds a message to an agent run that is in progress. |
| GET | `/api/chat/threads` | Read | Lists the chat threads on a computer. |
| POST | `/api/chat/threads` | Write | Creates a chat thread on a computer. |
| GET | `/api/chat/threads/{id}` | Read | Gets one chat thread and its messages. |
| PATCH | `/api/chat/threads/{id}` | Write | Renames, archives or updates the messages of a chat thread. |
| DELETE | `/api/chat/threads/{id}` | Write | Deletes a chat thread. |
| GET | `/api/chat/threads/{id}/run` | Read | Shows whether a chat thread's agent is running. |
| DELETE | `/api/chat/threads/{id}/run` | Write | Stops the agent run the caller started on a chat thread. |
| POST | `/api/chat/threads/{id}/title` | Write | Writes a short title for a chat thread with AI. |
| POST | `/api/chat/windows` | Write | Runs a chat turn with the computer use agent on a Windows computer. |
| GET | `/api/computers/{id}/agent` | Read | Reports the state of the agent on the computer and the apps it can use. |
| POST | `/api/computers/{id}/agent` | Write | Sets up the agent on the computer with a model and starts it. |
| GET | `/api/computers/{id}/agent/activity` | Read | Counts the messages the computer's agents handled each day, by channel. |
| GET | `/api/computers/{id}/agent/apps` | Read | Lists which apps the agent on the computer is signed in to. |
| POST | `/api/computers/{id}/agent/chat` | Write | Sends one chat message to the agent on the computer and streams its reply. |
| GET | `/api/computers/{id}/agent/install` | Read | Reports how an agent install on the computer is going. |
| POST | `/api/computers/{id}/agent/install` | Write | Starts installing Hermes, OpenClaw, Claude Code or Codex on the computer. |
| GET | `/api/computers/{id}/agent/schedules` | Read | Lists the scheduled jobs of the agent on the computer. |
| POST | `/api/computers/{id}/agent/schedules` | Write | Adds a scheduled job to the agent on the computer. |
| POST | `/api/computers/{id}/agent/schedules/{jobId}` | Write | Pauses, resumes or runs now one of the agent's scheduled jobs. |
| DELETE | `/api/computers/{id}/agent/schedules/{jobId}` | Write | Deletes one of the agent's scheduled jobs. |
| GET | `/api/computers/{id}/agent/skills` | Read | Lists the skills of the agent on the computer. |
| POST | `/api/computers/{id}/agent/skills` | Write | Adds a skill to the agent on the computer. |
| PATCH | `/api/computers/{id}/agent/skills` | Write | Turns one of the agent's skills on or off. |
| DELETE | `/api/computers/{id}/agent/skills` | Write | Removes a skill from the agent on the computer. |
| GET | `/api/computers/{id}/agent/telegram` | Write | Checks a Telegram bot pairing and gives the new bot to the agent once it exists. |
| POST | `/api/computers/{id}/agent/telegram` | Write | Starts pairing a Telegram bot with the agent on the computer. |
| GET | `/api/integrations/apps/{app}/actions` | Read | Lists what an agent can do with one app once a computer signs in to it. |
| GET | `/api/integrations/latitude-observability` | Read | Shows the workspace's Latitude monitoring connection, agents and setup jobs. |
| POST | `/api/integrations/latitude-observability/agents` | Write | Chooses which agents Latitude monitors. |
| PATCH | `/api/integrations/latitude-observability/agents/{agentId}` | Write | Retries, turns on or turns off Latitude monitoring for one agent. |
| POST | `/api/integrations/latitude-observability/hermes-computers` | Write | Adds the Hermes agent already set up on a computer to Latitude monitoring. |
| GET | `/api/integrations/latitude-observability/jobs/{jobId}` | Read | Shows one Latitude monitoring setup job. |
| DELETE | `/api/integrations/latitude-observability/projects/{integrationId}` | Write | Deletes the Latitude project made for one monitored agent. |
| POST | `/api/sandbox` | Write | Runs code in a short lived cloud sandbox and returns its output. |
| POST | `/api/support/chat` | Write | Asks the help panel's support agent a question and streams the answer. |
| POST | `/api/transcribe` | Write | Turns a short voice recording into text. |
| GET | `/api/trident/activity` | Read | Gets a Trident workspace's target statuses, campaign ideas and buy box. |
| POST | `/api/trident/activity` | Write | Updates a Trident target's status, a campaign idea, or the buy box. |
| DELETE | `/api/trident/activity` | Write | Removes a Trident campaign idea. |
| GET | `/api/trident/agent` | Read | Shows whether a Trident workspace's agent computer is up. |
| POST | `/api/trident/agent/install` | Write | Sets up the Trident tools and memory on the agent's computer and restarts the agent. |
| GET | `/api/trident/agent/settings` | Read | Shows how hard the Trident agent thinks. |
| PATCH | `/api/trident/agent/settings` | Write | Changes how hard the Trident agent thinks and restarts it. |
| GET | `/api/trident/agent/skills` | Read | Lists the skills the Trident agent made on its computer, or shows one. |
| DELETE | `/api/trident/agent/skills` | Write | Deletes a skill the Trident agent made on its computer. |
| GET | `/api/trident/agent/tool-calls` | Read | Shows what the Trident agent's tools were given and returned during a turn. |
| GET | `/api/trident/artifacts/{id}` | Read | Gets one Trident list as a table or a CSV file. |
| PATCH | `/api/trident/artifacts/{id}` | Write | Restores a deleted Trident list within its restore window. |
| DELETE | `/api/trident/artifacts/{id}` | Write | Deletes a Trident list, either for now or for good. |
| POST | `/api/trident/artifacts/{id}/edit` | Write | Applies cell edits to a Trident list. |
| GET | `/api/trident/chat` | Read | Lists past Trident chats, or shows one in full. |
| POST | `/api/trident/chat` | Write | Sends a chat turn to the Trident agent and streams its reply. |
| DELETE | `/api/trident/chat` | Write | Deletes a Trident chat. |
| GET | `/api/trident/composio` | Read | Shows which apps are connected for a Trident workspace. |
| POST | `/api/trident/composio/drafts` | Write | Saves an outreach note as a draft in a connected Gmail account. |
| GET | `/api/trident/composio/toolkits` | Read | Searches the apps a Trident workspace can connect. |
| GET | `/api/trident/cron` | Read | Lists a Trident workspace's scheduled jobs. |
| POST | `/api/trident/cron` | Write | Creates a scheduled job for the Trident agent. |
| GET | `/api/trident/cron/ownership` | Read | Shows who owns each Trident scheduled job and the teams that can own them. |
| PUT | `/api/trident/cron/ownership` | Write | Sets a Trident job's owner, or saves or deletes a team. |
| PATCH | `/api/trident/cron/{id}` | Write | Turns a Trident scheduled job on or off, or runs it now. |
| DELETE | `/api/trident/cron/{id}` | Write | Deletes a Trident scheduled job. |
| GET | `/api/trident/cron/{id}/runs` | Read | Lists what a Trident scheduled job produced each time it ran. |
| GET | `/api/trident/docs` | Read | Gets the written description of Trident skills and their steps. |
| POST | `/api/trident/groups/{groupId}/run` | Write | Runs a group of Trident skills in order in the background. |
| GET | `/api/trident/inbox-rules` | Read | Gets a Trident workspace's rules for incoming mail. |
| PUT | `/api/trident/inbox-rules` | Write | Replaces the Trident mail rules and updates the jobs that use them. |
| POST | `/api/trident/runs/{runId}/cancel` | Write | Cancels a Trident run. |
| POST | `/api/trident/skills/{slug}/run` | Write | Starts a Trident skill run. |
| GET | `/api/trident/state` | Read | Gets the Trident skills, recent runs and lists. |
| POST | `/api/v1/chat/completions` | Write | Runs the computer use agent on a computer through an OpenAI style chat completions call. |
| GET | `/api/v1/handoffs` | Read | Lists the handoffs on a computer. |
| POST | `/api/v1/handoffs` | Write | Hands a job to an agent on a computer. |
| GET | `/api/v1/handoffs/{id}` | Read | Gets one handoff with its journal and open questions. |
| PATCH | `/api/v1/handoffs/{id}` | Write | Cancels a handoff. |
| GET | `/api/v1/support/allowance` | Read | Shows how many free support tokens the caller has left today. |
| POST | `/api/v1/support/ask` | Write | Asks Orgo's support agent a question and returns the answer. |
| GET | `/api/v1/threads` | Read | Lists the chat threads on a computer. |
| POST | `/api/v1/threads` | Write | Creates a chat thread on a computer. |
| GET | `/api/v1/threads/{id}` | Read | Gets one chat thread. |
| DELETE | `/api/v1/threads/{id}` | Write | Deletes a chat thread. |
| POST | `/api/voice/session` | Write | Makes a short lived token so the browser can open a voice call. |
| POST | `/api/voice/usage` | Write | Charges a finished voice reply to the account's credits. |
| GET | `/api/workspace-threads/{workspaceId}` | Read | Returns the caller's latest chat with the workspace's agent. |
| PATCH | `/api/workspace-threads/{workspaceId}` | Write | Archives the caller's current chat with the workspace's agent so the next message starts a new one. |

## Bops group

What the Bops app keeps in Orgo: its settings, map, routines, access and Orbit.

19 read, 27 write.

| Method | Path | Level | What it does |
| - | - | - | - |
| GET | `/api/bops/apps` | Read | Lists the Bops apps seen on the account in the last 90 days. |
| POST | `/api/bops/checkout` | Write | Opens a Stripe Checkout page to buy or change a Bops plan. |
| POST | `/api/bops/computer/active` | Write | Tells Orgo the free Bops computer is in use so it is not suspended for sitting idle. |
| GET | `/api/bops/credit/card-on-file` | Read | Returns the card a Bops AI credit top up would charge and any top ups still pending. |
| POST | `/api/bops/credit/card-on-file` | Write | Buys Bops AI credit on the card on file. |
| POST | `/api/bops/credit/checkout` | Write | Opens a Stripe Checkout page to buy Bops AI credit. |
| GET | `/api/bops/plan` | Read | Returns the Bops plan, AI credit and free Bops computer, granting the free starting credit on first read. |
| POST | `/api/bops/portal` | Write | Opens the Stripe portal for the Bops plan. |
| GET | `/api/bops/settings` | Read | Returns whether the account's Bops bots work in the cloud or on the Mac. |
| GET | `/api/projects/{id}/access` | Read | Lists what each Bops bot in the workspace may use. |
| PUT | `/api/projects/{id}/access` | Write | Replaces the whole list of what each Bops bot in the workspace may use. |
| GET | `/api/projects/{id}/access/log` | Read | Lists the Bops bots' recorded uses of apps and keys, newest first. |
| POST | `/api/projects/{id}/access/log` | Write | Records Bops bots' uses of apps and keys. |
| GET | `/api/projects/{id}/bops` | Read | Returns the Bops workspace's map of bots, the computers they work on, what they own and their watches. |
| PUT | `/api/projects/{id}/bops` | Write | Replaces the Bops workspace's map of bots, what they own and their watches. |
| GET | `/api/projects/{id}/bops/apps` | Read | Lists the apps the Bops workspace's bots made, with their versions, or what changed since a given time. |
| PUT | `/api/projects/{id}/bops/apps` | Write | Saves every app one Mac's Bops bots made at once and can delete that Mac's apps left out. |
| GET | `/api/projects/{id}/bops/apps/{bopsId}` | Read | Returns an app a Bops bot made, with its versions. |
| PUT | `/api/projects/{id}/bops/apps/{bopsId}` | Write | Saves an app a Bops bot made: its name, bot, versions and the version it opens at. |
| DELETE | `/api/projects/{id}/bops/apps/{bopsId}` | Write | Deletes an app a Bops bot made with its code and data, keeping a record that it was deleted. |
| GET | `/api/projects/{id}/bops/apps/{bopsId}/data` | Read | Returns a short lived download link for what an app a Bops bot made keeps. |
| PUT | `/api/projects/{id}/bops/apps/{bopsId}/data` | Write | Saves what an app a Bops bot made keeps. |
| GET | `/api/projects/{id}/bops/apps/{bopsId}/versions/{n}` | Read | Returns one version of an app a Bops bot made, with a short lived download link for its code. |
| PUT | `/api/projects/{id}/bops/apps/{bopsId}/versions/{n}` | Write | Saves the code of one version of an app a Bops bot made. |
| GET | `/api/projects/{id}/crm` | Read | Lists the Bops workspace's CRM files, or what changed since a given time. |
| GET | `/api/projects/{id}/crm/{name}` | Read | Returns a CRM file of the Bops workspace with a short lived download link for its contents. |
| PUT | `/api/projects/{id}/crm/{name}` | Write | Saves a CRM file of the Bops workspace. |
| PATCH | `/api/projects/{id}/crm/{name}` | Write | Renames a CRM file of the Bops workspace. |
| DELETE | `/api/projects/{id}/crm/{name}` | Write | Deletes a CRM file of the Bops workspace, keeping it in the workspace's trash for 30 days. |
| GET | `/api/projects/{id}/orbit` | Read | Returns the Bops workspace's Orbit memory in full, or what changed since a given time. |
| GET | `/api/projects/{id}/orbit/issues` | Read | Lists the Bops workspace's Orbit issues. |
| POST | `/api/projects/{id}/orbit/issues` | Write | Creates an Orbit issue, or updates the one already open for the same thread or ticket. |
| GET | `/api/projects/{id}/orbit/issues/{issueId}` | Read | Returns an Orbit issue and its history. |
| PATCH | `/api/projects/{id}/orbit/issues/{issueId}` | Write | Updates an Orbit issue or adds notes to it. |
| DELETE | `/api/projects/{id}/orbit/issues/{issueId}` | Write | Deletes an Orbit issue and its history. |
| PUT | `/api/projects/{id}/orbit/items` | Write | Saves Orbit memory items and their sources, merging duplicates. |
| DELETE | `/api/projects/{id}/orbit/items` | Write | Deletes Orbit memory items. |
| POST | `/api/projects/{id}/orbit/items/delete-everywhere-preview` | Read | Lists the chat histories an Orbit item came from and what deleting them would also remove. |
| POST | `/api/projects/{id}/orbit/tombstones` | Write | Records hashes of forgotten Orbit facts so no Mac learns them again. |
| GET | `/api/projects/{id}/routines` | Read | Lists the Bops workspace's routines. |
| POST | `/api/projects/{id}/routines` | Write | Creates a Bops routine. |
| PUT | `/api/projects/{id}/routines` | Write | Saves many Bops routines at once and can delete the ones left out. |
| PATCH | `/api/projects/{id}/routines/{routineId}` | Write | Updates a Bops routine. |
| DELETE | `/api/projects/{id}/routines/{routineId}` | Write | Deletes a Bops routine. |
| GET | `/api/projects/{id}/routines/{routineId}/runs` | Read | Lists a Bops routine's recent runs. |
| POST | `/api/projects/{id}/routines/{routineId}/runs` | Write | Records the result of a Bops routine's run. |

## Billing group

Plan, credits, usage and invoices (read); anything that buys, changes or cancels (write).

35 read, 33 write.

| Method | Path | Level | What it does |
| - | - | - | - |
| GET | `/api/account/capacity` | Read | Shows what the account may run, what it runs and how many computers of each size it may still add. |
| POST | `/api/account/capacity` | Write | Buys computers or memory, vCPU and storage for the account on the card on file, or prices them first. |
| PATCH | `/api/account/capacity` | Write | Sets how many added computers the account keeps from the next renewal. |
| GET | `/api/billing/addons` | Read | Lists the add-ons on the account's plan and when they renew. |
| GET | `/api/billing/billing-mode` | Read | Says whether the plan must switch to flexible billing before an add-on can be bought. |
| POST | `/api/billing/billing-mode` | Write | Switches the plan to flexible billing so add-ons can be bought, which cannot be undone. |
| POST | `/api/billing/card/check` | Write | Checks the card on file after one is added, which lifts the free account limits and can grant the starting credit. |
| GET | `/api/billing/compute` | Read | Lists the hourly computer sizes and prices the workspace owner can choose. |
| POST | `/api/billing/compute` | Read | Makes a price quote for one hourly computer size without buying it. |
| GET | `/api/billing/compute-balance` | Read | Shows the account's credit balance and how much of it is held. |
| GET | `/api/billing/compute-limits` | Read | Shows the largest computer the workspace owner can create right now and the account limits behind it. |
| GET | `/api/billing/compute-requests` | Read | Lists the account's open requests for custom computers. |
| POST | `/api/billing/compute-requests` | Write | Asks Orgo for a custom computer of a chosen type. |
| POST | `/api/billing/compute-reservations` | Write | Quotes, reserves, reprices or releases a reserved GPU computer for a workspace. |
| GET | `/api/billing/compute-subscriptions` | Read | Lists the account's monthly computer and hardware subscriptions. |
| POST | `/api/billing/compute-subscriptions` | Write | Quotes, buys, reprices or cancels a monthly computer or hardware subscription. |
| GET | `/api/billing/compute-units` | Read | Shows the computers the account has bought and any scheduled reduction. |
| POST | `/api/billing/compute-units` | Write | Buys one or more computers of a shape on the account's plan. |
| PATCH | `/api/billing/compute-units` | Write | Gives back bought computers at the next renewal. |
| POST | `/api/billing/compute-units/preview` | Read | Shows what buying computers would cost without buying them. |
| GET | `/api/billing/connect` | Read | Shows whether the account's payout account for client billing is set up. |
| GET | `/api/billing/connect/brand` | Read | Shows the name, color and logo clients see at checkout. |
| POST | `/api/billing/connect/brand` | Write | Uploads the logo clients see at checkout. |
| PATCH | `/api/billing/connect/brand` | Write | Changes the name and color clients see at checkout. |
| GET | `/api/billing/disk-blocks` | Read | Shows how much extra storage the account has bought. |
| POST | `/api/billing/disk-blocks` | Write | Sets how much extra storage the account buys. |
| POST | `/api/billing/disk-blocks/preview` | Read | Shows what a change to extra storage would cost without making it. |
| POST | `/api/billing/hardware/cancel` | Write | Cancels one monthly hardware unit at the end of its paid period. |
| POST | `/api/billing/hardware/get` | Write | Buys a free hardware unit such as a Mac or iPhone and hands it to the account. |
| GET | `/api/billing/invoices` | Read | Lists the account's recent invoices. |
| POST | `/api/billing/plan/cancel` | Write | Cancels the plan at the end of its paid period, or undoes that. |
| POST | `/api/billing/plan/retry-payment` | Write | Pays the plan's open bill now with the card on file. |
| POST | `/api/billing/plan/schedule/release` | Write | Undoes a plan change scheduled for the next renewal. |
| POST | `/api/billing/portal` | Write | Opens the Stripe billing portal for the account. |
| GET | `/api/billing/quota` | Read | Shows the account's allocated resources and usage this month. |
| GET | `/api/billing/ram-addon` | Read | Shows how much extra memory the account has bought. |
| POST | `/api/billing/ram-addon` | Write | Sets how much extra memory the account buys. |
| POST | `/api/billing/ram-addon/preview` | Read | Shows what a change to extra memory would cost without making it. |
| GET | `/api/billing/summary` | Read | Shows the account's plan, price and renewal date. |
| GET | `/api/billing/vcpu-addon` | Read | Shows how much extra vCPU the account has bought. |
| POST | `/api/billing/vcpu-addon` | Write | Sets how much extra vCPU the account buys. |
| POST | `/api/billing/vcpu-addon/preview` | Read | Shows what a change to extra vCPU would cost without making it. |
| GET | `/api/billing/vm-slots` | Read | Shows how many extra computer slots the account has bought. |
| POST | `/api/billing/vm-slots` | Write | Sets how many extra computer slots the account buys. |
| POST | `/api/billing/vm-slots/preview` | Read | Shows what adding computer slots would cost without buying them. |
| POST | `/api/checkout` | Write | Starts a plan purchase or plan change and returns a Stripe Checkout page when one is needed. |
| GET | `/api/credits` | Read | Shows the account's AI credit balance and plan. |
| POST | `/api/credits/checkout` | Write | Opens a Stripe Checkout page to buy credits. |
| GET | `/api/credits/subscription-addon` | Read | Shows the monthly credit add-on on the account's plan. |
| POST | `/api/credits/subscription-addon` | Write | Sets or removes the monthly credit add-on on the account's plan. |
| GET | `/api/credits/transactions` | Read | Lists the account's recent credit transactions. |
| GET | `/api/domains/search` | Read | Searches for a free name under Orgo's domain and for domains to buy, with their prices in Orgo credits. |
| GET | `/api/projects/{id}/client-billing` | Read | Returns what the workspace's client is billed and what the workspace costs. |
| POST | `/api/projects/{id}/client-billing` | Write | Creates a payment link for the workspace's client and emails it to them. |
| PATCH | `/api/projects/{id}/client-billing` | Write | Changes the client's monthly price or AI amount from the next invoice. |
| DELETE | `/api/projects/{id}/client-billing` | Write | Stops billing the workspace's client at the end of the period or right away. |
| GET | `/api/projects/{id}/client-billing/payments` | Read | Lists the client's payments for the workspace, newest first. |
| POST | `/api/projects/{id}/client-billing/payments/{invoiceId}/refund` | Write | Refunds one of the client's payments in full. |
| POST | `/api/projects/{id}/client-billing/resend` | Write | Emails the client's waiting payment link again. |
| GET | `/api/stock` | Read | Lists how much of each kind of hardware is free to get. |
| GET | `/api/user/subscription` | Read | Shows the account's plan, its limits and whether it needs to pay. |
| GET | `/api/user/usage/spend` | Read | Shows credit spent per day on AI and computers, and the top models by spend. |
| POST | `/api/v1/credits` | Write | Buys credits with a machine payment so an agent can top up its own account. |
| GET | `/api/v1/invoices` | Read | Lists the invoices the account has sent. |
| POST | `/api/v1/invoices` | Write | Creates an invoice to bill a customer, with a page where they pay. |
| GET | `/api/v1/invoices/{id}` | Read | Gets one invoice with its current status. |
| POST | `/api/v1/invoices/{id}/send` | Write | Emails an invoice to its customer. |
| POST | `/api/v1/invoices/{id}/void` | Write | Cancels an unpaid invoice. |

## API keys group

Listing keys (read); making, changing and revoking them (write), never past the key’s own access.

3 read, 5 write.

| Method | Path | Level | What it does |
| - | - | - | - |
| GET | `/api/computers/{id}/keys` | Read | Lists the API keys bound to one computer, never their values: every one for its workspace's owner, only the caller's own for a member. |
| DELETE | `/api/computers/{id}/keys/{keyId}` | Write | Revokes an API key bound to one computer: any of them for its workspace's owner, only the caller's own for a member. |
| GET | `/api/keys` | Read | Lists the account's API keys without their values, only those inside the caller's own scope. |
| POST | `/api/keys` | Write | Creates an API key for the account, one workspace or one computer and shows its value once, never with more access than the caller has. |
| DELETE | `/api/keys` | Write | Revokes one API key named by ?id=, the old way to call DELETE /api/keys/\{id}. |
| GET | `/api/keys/{id}` | Read | Shows one API key without its value, if it is inside the caller's own scope. |
| PATCH | `/api/keys/{id}` | Write | Changes a key's name, access, expiry or scope, never past the caller's own access and never its value. |
| DELETE | `/api/keys/{id}` | Write | Revokes one API key that is within the caller's own access. |

## Which endpoints a one-computer key can call

A one-computer key reaches a single Linux computer and nothing else. It can call only the endpoints below, and only about its own computer, within its permissions. Anything else answers `403` with `code: "computer_scope"`. How to make one, and what it can never do, is described in [One-computer keys for contractors and embeds](https://docs.orgo.ai/api-reference/api-keys/computer-keys.md#one-computer-keys-for-contractors-and-embeds).

A computer's own key, the one Orgo makes for a computer, calls a different list. It is described in [What a computer key can call](https://docs.orgo.ai/api-reference/api-keys/computer-keys.md#what-a-computer-key-can-call).

| Method | Path | What it does |
| - | - | - |
| GET | `/api/computers/{id}` | Gets a computer with its status, hardware and connection details. |
| POST | `/api/computers/{id}/bash` | Runs a shell command on the computer and returns its output. |
| POST | `/api/computers/{id}/click` | Clicks at a point on the computer's screen. |
| POST | `/api/computers/{id}/drag` | Drags the mouse from one point to another on the computer. |
| POST | `/api/computers/{id}/exec` | Runs Python code on the computer and returns its output. |
| POST | `/api/computers/{id}/freeze` | Stops the computer and keeps its disk, the same as stop. |
| POST | `/api/computers/{id}/key` | Presses a key or key combination on the computer. |
| POST | `/api/computers/{id}/mouse-move` | Moves the pointer on the computer's screen without clicking. |
| POST | `/api/computers/{id}/restart` | Restarts the computer. |
| POST | `/api/computers/{id}/resume` | Resumes a suspended computer where it left off. |
| GET | `/api/computers/{id}/screens` | Lists the screens on the computer. |
| POST | `/api/computers/{id}/screens` | Adds a screen to the computer. |
| GET | `/api/computers/{id}/screens/{screenId}` | Gets one screen on the computer. |
| GET | `/api/computers/{id}/screenshot` | Takes a screenshot of the computer's screen. |
| POST | `/api/computers/{id}/scroll` | Scrolls on the computer's screen. |
| POST | `/api/computers/{id}/start` | Starts a stopped computer. |
| POST | `/api/computers/{id}/stop` | Stops the computer and keeps its disk. |
| POST | `/api/computers/{id}/suspend` | Suspends the computer with its memory saved, so it resumes where it left off. |
| POST | `/api/computers/{id}/type` | Types text on the computer. |
| GET | `/api/computers/{id}/vnc-password` | Gets the computer's VNC password and its Desktop API token. |
| POST | `/api/computers/{id}/wait` | Waits a number of seconds on the computer. |
| POST | `/api/computers/{id}/wake` | Starts a stopped computer, the same as start. |
| GET | `/api/desktops/{id}/proxy/{...path}` | Passes a read request through to the computer's Desktop API. |
| HEAD | `/api/desktops/{id}/proxy/{...path}` | Passes a read request through to the computer's Desktop API. |
| POST | `/api/desktops/{id}/proxy/{...path}` | Passes a request that acts on the computer through to its Desktop API. |
| PUT | `/api/desktops/{id}/proxy/{...path}` | Passes a request that acts on the computer through to its Desktop API. |
| PATCH | `/api/desktops/{id}/proxy/{...path}` | Passes a request that acts on the computer through to its Desktop API. |
| DELETE | `/api/desktops/{id}/proxy/{...path}` | Passes a request that acts on the computer through to its Desktop API. |
| WebSocket | `/desktops/{id}/ws/audio` | Streams the computer's sound. |
| WebSocket | `/desktops/{id}/ws/rtc` | Streams the computer's screen over WebRTC, with its mouse and keyboard. |
| WebSocket | `/desktops/{id}/ws/stats` | Streams the live statistics of a screen connection. |
| WebSocket | `/desktops/{id}/ws/terminal` | Opens a terminal on the computer. |
| WebSocket | `/desktops/{id}/ws/websockify` | Streams the computer's screen over VNC, with its mouse and keyboard. |

## Endpoints a restricted key never uses

Every endpoint not listed on this page is one of these kinds. None is in a group, so a restricted key, a one-computer key and a computer's own key are refused all of them with `403`.

* **Only you, signed in.** Key security, signing in and out, linking other accounts, and what only a browser does. Some also take a full access key or the key a Bops app signed in with; a restricted key or a computer’s own key never can.
* **Open to anyone.** Health and status, sign-in flows, and webhooks that other services send, checked by their signature. They need no key.
* **Orgo staff.** Orgo’s own tools. No key of yours reaches them.
* **Orgo’s own machinery.** Called by Orgo’s own servers and computers with credentials of their own.
* **Scheduled jobs.** Orgo’s own jobs, run on a schedule.

## Related pages

* [Create and manage API keys](https://docs.orgo.ai/api-reference/api-keys/manage.md): set `permissions` when you create or change a key.
* [Key expiry and rotation](https://docs.orgo.ai/api-reference/api-keys/expiry-and-rotation.md): how long a key lives.
* [Key scopes and computer keys](https://docs.orgo.ai/api-reference/api-keys/computer-keys.md): keys for one workspace or one computer.
* [Authentication](https://docs.orgo.ai/api-reference/authentication.md): how a request authenticates.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.