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.
Every Orgo API error response is JSON with two stable fields plus an optional request_id to use when contacting support.
{
"error": "Invalid API key. Check it for typos or generate a new one at https://www.orgo.ai/start.",
"request_id": "f0c2c4a8-9d8e-4d2f-b8a6-2a9a4c2d4b1f"
}
{
"error": "screen is unavailable",
"request_id": "f0c2c4a8-9d8e-4d2f-b8a6-2a9a4c2d4b1f",
"upstream_status": 409
}
request_id when emailing spencer@orgo.ai about a failed call. It maps directly to a server-side log line.
Authentication
| Symptom | What it means | Fix |
|---|
401 Invalid API key. | The Bearer token in your Authorization header is not a known Orgo API key. | Generate a new key at orgo.ai/start. Check for whitespace or a missing sk_ prefix. |
401 Missing API key. | No Authorization header on the request. | Set Authorization: Bearer $ORGO_API_KEY. |
401 Your session has expired. | You called the API from a browser session that timed out. | Sign in again, or switch to an API key for programmatic calls. |
403 Access denied on a computer or workspace | The key belongs to a different account, or you were removed from the workspace. | Confirm the workspace ID, or ask the workspace owner to re-invite you. |
403 workspace_scope_mismatch | The API key is workspace-scoped and the request targets a different workspace. The response includes key_workspace_id and target_workspace_id so the boundary is explicit. | Use an account-wide key, or create a key scoped to the target workspace. See Authentication. |
Computer not responding
| Symptom | What it means | Fix |
|---|
404 Computer not found | The ID in the URL doesn’t match a computer your account can see. | Re-fetch the ID from GET /workspaces/{id}. |
400 Desktop instance not available | The computer record exists, but it never got a backing VM (still booting or failed). | Wait a few seconds and retry. If it persists, POST /computers/{id}/restart. |
503 Could not reach the desktop. Try again in a moment. | The control plane could not connect to the desktop. Usually transient. | Retry with exponential backoff (1s, 2s, 4s). If it keeps failing, restart the computer. |
409 Conflict | The action is blocked by the computer’s current state, e.g. resize while not running. | Read the message; restart or stop the computer if needed. |
Action errors (bash, click, type, exec, etc.)
When an action endpoint returns a non-200, the upstream_status field tells you whether the failure came from Orgo’s control plane or from the desktop itself.
upstream_status | Meaning |
|---|
| Not present | The error originated in Orgo’s control plane (auth, lookup, validation). |
400 | The desktop rejected the request body (e.g. bash command parse error, click out of bounds). |
408, 504 | The desktop timed out the action. Common with long bash commands; pass a higher timeout in the body. |
500 | The desktop crashed handling the action. Capture the request_id and contact support. |
Recovering a stuck computer
A computer is “stuck” if it returns 200 on GET /computers/{id} but action calls fail.
GET https://{instance_id}.orgo.dev/health. If this returns 200, the desktop is up and the issue is in the control plane. Retry your action.- If
/health fails, POST /computers/{id}/restart. State is preserved across restart.
- If restart fails, capture
request_ids from a few attempts and email spencer@orgo.ai. Do not delete the computer; deletion drops the disk.
Rate limits
429 Too Many Requests means you have exceeded the per-key rate limit. Back off with exponential retry (start at 1s, double each retry, max 60s). If you need higher limits, email spencer@orgo.ai.
Reporting a bug
When something is broken, send:
- The
request_id from the error response (the most important field).
- The exact request you made (method, URL, body, redacted of secrets).
- The full error response.
Email: spencer@orgo.ai. Discord: discord.gg/tbYGpvnnJD.
