> ## 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.
# List workspaces
> List all workspaces accessible to the API key.
Returns every workspace you own or belong to, each with its computers under `desktops`. Workspaces you own come first, oldest first, followed by workspaces shared with you.
This call is not read-only. If the account has no workspaces yet, the first call with an account-wide key creates one named `'s workspace` and returns it. The name comes from your profile name, or from the part of your email before the `@` when no profile name is set.
A workspace-scoped API key sees only the workspace it is scoped to, and never triggers the default-workspace creation. See [Authentication](/api-reference/authentication).
## Response
The same array is returned under two keys.
Array of workspace objects, each with its `desktops`. Read this key.
The identical array. `project` is the API's original name for a workspace. The key is kept for existing integrations. Do not read it in new code.
For an account on the free plan, the body can also carry a `trial_snapshot` object. The dashboard reads it. It is not part of the documented contract.
Each workspace object carries the fields listed on [Get workspace](/api-reference/workspaces/get), including `role` and `permissions`, plus:
People with access to the workspace, counting the owner. Returned by this endpoint only.
Subscription tier of the workspace owner. Computers are funded by the owner's plan, so this is the tier that sets the hardware ceiling for every computer in the workspace, including computers created by invited members.
Email address of the workspace owner. Returned to every member of the workspace, not only the owner.
Computers in the workspace, in no guaranteed order. Ephemeral computers are excluded. Each entry is the stored computer record with credential fields removed, plus the same `permissions` object, so it carries more fields than the example below. Treat any field not documented here as internal and subject to change.
## Example
```bash cURL theme={null}
curl https://www.orgo.ai/api/workspaces \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```python Python theme={null}
import os
import requests
api_key = os.environ["ORGO_API_KEY"]
response = requests.get(
"https://www.orgo.ai/api/workspaces",
headers={"Authorization": f"Bearer {api_key}"}
)
workspaces = response.json()["workspaces"]
for ws in workspaces:
n = len(ws.get("desktops") or [])
print(f"{ws['name']}: {n} computers")
```
```javascript JavaScript theme={null}
const apiKey = process.env.ORGO_API_KEY;
const response = await fetch('https://www.orgo.ai/api/workspaces', {
headers: { 'Authorization': `Bearer ${apiKey}` }
});
const { workspaces } = await response.json();
workspaces.forEach(ws => {
const n = (ws.desktops || []).length;
console.log(`${ws.name}: ${n} computers`);
});
```
### Response
The response repeats the same array under `projects`, omitted here for length.
```json theme={null}
{
"workspaces": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "production",
"user_id": "4d96f9a0-7727-4b63-889a-32544c206d7c",
"status": "active",
"icon_url": null,
"created_at": "2026-04-07T10:30:00Z",
"updated_at": "2026-04-07T10:30:00Z",
"member_count": 3,
"owner_tier": "hacker",
"owner_email": "owner@example.com",
"role": "owner",
"permissions": { "canView": true, "canWrite": true, "canManageAccess": true },
"desktops": [
{
"id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
"name": "agent-1",
"os": "linux",
"ram": 4,
"cpu": 1,
"status": "running",
"permissions": { "canView": true, "canWrite": true, "canManageAccess": true }
}
]
}
]
}
```
## Errors
| Status | Body | Meaning |
| - | - | - |
| `401` | `{ "error": "Invalid API key" }` | The Bearer token starts with `sk_` but is not a known Orgo key. |
| `401` | `{ "error": "Authentication required" }` | No `Authorization` header, or a Bearer token that is not an `sk_` key. |
| `500` | `{ "error": "" }` | The listing query failed, or the default-workspace creation failed. |
| `503` | `{ "error": "Service temporarily unavailable. …" }` | Orgo could not verify the credential because of a server-side fault. The response carries `Retry-After: 5`. Retry after that delay. |
There is no `403` on this endpoint. It never rejects a caller who authenticated.
## OpenAPI
````yaml GET /workspaces
openapi: 3.1.0
info:
title: Orgo API
description: >-
Launch cloud computers that AI agents can control and interact with. Create
workspaces, provision computers, and control them programmatically.
version: 2.0.0
contact:
name: Orgo Support
email: spencer@orgo.ai
url: https://orgo.ai
servers:
- url: https://www.orgo.ai/api
description: Production
security:
- bearerAuth: []
tags:
- name: Account
description: >-
Account capacity: how many computers an account may run, and adding or
giving back more.
- name: Clients
description: >-
Run Orgo for your clients from your own app: a workspace and scoped key
each, billed to you or to them.
- name: Workspaces
description: Organize computers into named workspaces
- name: Computers
description: Provision and manage virtual computers
- name: Computer Lifecycle
description: Start, stop, and restart computers
- name: Computer Actions
description: Control mouse, keyboard, and execute commands
- name: Screens
description: >-
More than one desktop on a single computer. Each screen is its own X
server with its own cursor and window manager, so an agent working on one
cannot disturb another.
- name: Files
description: Upload and download files
- name: Templates
description: Author, build, and launch reproducible computers from templates
paths:
/workspaces:
get:
tags:
- Workspaces
summary: List workspaces
description: >-
Lists every workspace you own or belong to, each with its computers
under `desktops`: owned workspaces first, oldest first, then workspaces
shared with you. The same array is returned under `workspaces` and
`projects`; read `workspaces`. Not read-only: an account with no
workspaces gets one created on the first call with an account-wide key.
operationId: listWorkspaces
responses:
'200':
description: Your workspaces
content:
application/json:
schema:
type: object
properties:
workspaces:
type: array
items:
$ref: '#/components/schemas/WorkspaceWithDesktops'
description: >-
Workspaces you own or belong to, each with its computers
embedded.
projects:
type: array
items:
$ref: '#/components/schemas/WorkspaceWithDesktops'
description: >-
The same array under its older name. Identical contents,
element for element.
deprecated: true
trial_snapshot:
type: object
additionalProperties: true
description: >-
Present for an account on the free plan. The dashboard
reads it; it is not part of the documented contract.
example:
workspaces:
- id: 550e8400-e29b-41d4-a716-446655440000
name: production
user_id: 4d96f9a0-7727-4b63-889a-32544c206d7c
status: active
icon_url: null
created_at: '2026-04-07T10:30:00Z'
updated_at: '2026-04-07T10:30:00Z'
member_count: 3
owner_tier: hacker
owner_email: owner@example.com
role: owner
permissions:
canView: true
canWrite: true
canManageAccess: true
desktops:
- id: a3bb189e-8bf9-3888-9912-ace4e6543002
name: agent-1
os: linux
ram: 4
cpu: 1
status: running
permissions:
canView: true
canWrite: true
canManageAccess: true
projects:
- id: 550e8400-e29b-41d4-a716-446655440000
name: production
user_id: 4d96f9a0-7727-4b63-889a-32544c206d7c
status: active
icon_url: null
created_at: '2026-04-07T10:30:00Z'
updated_at: '2026-04-07T10:30:00Z'
member_count: 3
owner_tier: hacker
owner_email: owner@example.com
role: owner
permissions:
canView: true
canWrite: true
canManageAccess: true
desktops:
- id: a3bb189e-8bf9-3888-9912-ace4e6543002
name: agent-1
os: linux
ram: 4
cpu: 1
status: running
permissions:
canView: true
canWrite: true
canManageAccess: true
'401':
$ref: '#/components/responses/Unauthorized'
'500':
description: The listing query failed, or the default-workspace creation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: …
'503':
$ref: '#/components/responses/AuthUnavailable'
components:
schemas:
WorkspaceWithDesktops:
allOf:
- $ref: '#/components/schemas/Workspace'
- type: object
properties:
owner_tier:
type: string
description: >-
Subscription tier of the workspace owner. It sets the hardware
ceiling for every computer in the workspace.
example: hacker
owner_email:
type: string
description: Email address of the workspace owner. Returned to every member.
role:
type: string
enum:
- owner
- admin
- member
description: >-
Your role in the workspace: `owner`, `admin` (can edit), or
`member` (view only).
permissions:
$ref: '#/components/schemas/Permissions'
member_count:
type: integer
description: >-
People with access to the workspace, counting the owner.
Returned by `GET /workspaces` only.
desktops:
type: array
description: >-
Computers in the workspace, in no guaranteed order. Ephemeral
computers are excluded. Each entry is the stored computer record
with credential fields removed, plus `permissions`. Treat fields
not documented here as internal.
items:
allOf:
- $ref: '#/components/schemas/Computer'
- type: object
properties:
permissions:
$ref: '#/components/schemas/Permissions'
Error:
type: object
description: >-
The base error body. Every failure carries `error`; individual endpoints
add the fields named in the schemas below.
required:
- error
properties:
error:
type: string
description: Human-readable message.
example: Access denied
code:
type: string
description: >-
Machine-readable reason. Present on the failures that define one,
absent otherwise.
Workspace:
type: object
properties:
id:
type: string
description: Unique workspace identifier
example: 550e8400-e29b-41d4-a716-446655440000
name:
type: string
description: Workspace name
example: production
user_id:
type: string
description: Owner user ID
status:
type: string
enum:
- active
- inactive
example: active
icon_url:
type:
- string
- 'null'
description: Icon URL for the workspace, or `null` when none is set.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
Permissions:
type: object
description: What your role in the workspace allows.
properties:
canView:
type: boolean
example: true
canWrite:
type: boolean
description: '`false` for a view-only member.'
example: true
canManageAccess:
type: boolean
description: Only the owner has it.
example: true
Computer:
type: object
properties:
id:
type: string
description: Unique computer identifier
example: a3bb189e-8bf9-3888-9912-ace4e6543002
name:
type: string
description: Computer name
example: agent-1
workspace_id:
type: string
description: >-
ID of the workspace the computer belongs to. Returned by `POST
/computers`; `GET /computers/{id}` returns it as `project_id`.
example: 550e8400-e29b-41d4-a716-446655440000
project_name:
type: string
description: Name of the parent workspace
example: production
os:
type: string
enum:
- linux
- windows
- macos
- android
- ios
description: >-
Operating system. `ios` is a physical handset rather than a virtual
computer.
example: linux
ram:
type: integer
enum:
- 4
- 8
- 12
- 16
- 32
- 64
description: RAM in GB. `12` occurs only on macOS.
example: 4
cpu:
type: number
enum:
- 0.5
- 1
- 2
- 4
- 8
- 16
description: vCPU cores.
example: 1
status:
type: string
enum:
- creating
- running
- restarting
- updating
- suspended
- frozen
- stopped
- error
- deleted
description: Current status
example: running
url:
type: string
description: >-
Base URL of the computer's own API on the host that runs it, as
`http://:`. Plain HTTP, and reachable only from inside
Orgo's network. It is not a dashboard link and not an endpoint you
can call. Use `connection_url` from your own code.
example: http://198.51.100.24:8081
created_at:
type: string
format: date-time
instance_id:
type: string
description: >-
Stable identifier for the underlying compute instance, returned by
`POST /computers`. Use it for connection URLs and to reference the
computer across restarts. `GET /computers/{id}` returns the same
value as `fly_instance_id`.
example: a3881618
hostname:
type: string
description: >-
Same-origin host for the computer's connection endpoints:
`www.orgo.ai`. Empty while the computer has no instance id, such as
when it is `frozen`.
example: www.orgo.ai
connection_url:
type: string
description: >-
Same-origin connection base
(https://www.orgo.ai/desktops/{instance_id}). Append /ws/websockify,
/ws/terminal, or /ws/audio for WebSocket endpoints; HTTP Desktop API
calls go to
https://www.orgo.ai/api/desktops/{instance_id}/proxy/{endpoint}.
example: https://www.orgo.ai/desktops/a3881618
vnc_password:
type:
- string
- 'null'
description: >-
VNC / WebSocket Bearer token. Rotates on restart, on start, and on a
RAM resize, so do not persist it. `null` when you have view-only
access to the workspace, or when the stored credential cannot be
decrypted.
example: a06db12a8683df96
project_id:
type: string
description: >-
ID of the parent workspace, under its older name. `POST /computers`
returns it as a deprecated alias of `workspace_id`; `GET
/computers/{id}` returns only this name.
example: 550e8400-e29b-41d4-a716-446655440000
fly_instance_id:
type:
- string
- 'null'
description: >-
The instance id under its legacy name. The same value `POST
/computers` returns as `instance_id`. `GET /computers/{id}` returns
only this name. `null` while the computer has no host (`frozen`).
example: a3881618
permissions:
$ref: '#/components/schemas/Permissions'
private_screens:
type: boolean
description: >-
Returned by `GET /computers/{id}`. `true` when the computer's
workspace keeps screens private, so the Orgo dashboard keeps the
screen covered until someone chooses to show it.
example: false
instance_details:
type: object
additionalProperties: true
description: >-
The computer's placement and connection record: `provider`, `id`,
`name`, `webUrl`, `vncHost`, `vncPort`, `apiPort`, `serverAddress`,
`resolution`, and `fromPool`, plus `hypervisor` and
`templateTerminals` when they apply. `GET /computers/{id}` and the
workspace endpoints remove every field whose name contains
`password`, `secret`, `token`, `api_key`, or `authorized_keys`, in
any letter case and at any depth.
hardware:
type:
- object
- 'null'
description: >-
What the computer runs on, from its current VM's launch record. `GET
/computers/{id}` always returns it, `null` when the host has not
reported a launch record for the computer's current VM. `POST
/computers` returns it, with `launch`, only when the host reports
how it launched the computer.
properties:
host_cpu:
type:
- object
- 'null'
description: >-
The host's CPU, or `null` when the launch record does not name
it.
properties:
family:
type:
- string
- 'null'
name:
type:
- string
- 'null'
signature:
type:
- string
- 'null'
cpu_model:
type:
- string
- 'null'
description: '`host`, or the named CPU model the guest was given.'
hypervisor:
type:
- string
- 'null'
description: '`qemu` or `firecracker`.'
qemu:
type:
- string
- 'null'
description: The QEMU version that ran the computer.
boot:
type:
- string
- 'null'
description: How the computer last booted.
fallback:
type:
- string
- 'null'
description: >-
Set when the launch could not do what it was asked and fell
back, such as a resume that cold-booted because the CPU
differed.
launched_at:
type:
- string
- 'null'
format: date-time
launch:
type: object
additionalProperties: true
description: >-
Returned by `POST /computers` alongside `hardware`, when the host
reports how it launched the computer: the host's launch record for
the new computer, without the host's name or the source its state
was restored from.
resolution:
type: string
description: >-
Display resolution in `WIDTHxHEIGHTxDEPTH` format. Returned by `POST
/computers`.
example: 1280x720x24
gpu_downgraded:
type: boolean
description: >-
Returned by `POST /computers` only, present and `true` when you
asked for a `gpu` and a CPU computer was created instead.
warning:
type: string
description: Present only alongside `gpu_downgraded`, explaining the downgrade.
description: >-
A computer. No single response carries every field: `POST /computers`
returns `workspace_id`, `project_id`, `instance_id`, `fly_instance_id`,
and the connect fields, plus `hardware` and `launch` when the host
reports them; `GET /computers/{id}` returns `project_id`,
`project_name`, `permissions`, `fly_instance_id`, the connect fields,
`private_screens`, and `hardware`; a computer embedded in a workspace
carries the stored row. Each operation's example shows what that
operation returns.
responses:
Unauthorized:
description: 'No usable credential. Send `Authorization: Bearer $ORGO_API_KEY`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid-key:
summary: The key is not one of yours
value:
error: Invalid API key
no-credential:
summary: No key and no session
value:
error: Authentication required
AuthUnavailable:
description: >-
Orgo could not verify the credential because of a server-side fault,
such as a database outage. Retry after `Retry-After`. Do not rotate the
key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: >-
Service temporarily unavailable. The database is not accepting
requests. Retry shortly.
headers:
Retry-After:
description: Seconds to wait before retrying. Always `5`.
schema:
type: string
example: '5'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your key at orgo.ai/workspaces
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.