> ## 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.
# Get workspace
> Retrieve a workspace by ID.
Returns one workspace by ID, including its computers under `desktops`. Owners and invited members both have read access.
A workspace-scoped API key can read only the workspace it is scoped to. Any other ID returns `403`. See [Authentication](/api-reference/authentication).
## Path parameters
Workspace ID. Required.
## Response
Workspace identifier.
Workspace name.
User ID of the workspace owner.
Workspace status. `active` for a normal workspace.
Icon URL, or `null` when none is set.
ISO 8601 timestamp.
ISO 8601 timestamp.
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.
Email address of the workspace owner. Returned to every member of the workspace, not only the owner.
Your role in the workspace: `owner`, `admin` (can edit), or `member` (view only).
What your role allows, as three booleans: `canView`, `canWrite`, and `canManageAccess`. Only the owner has `canManageAccess`.
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. It carries more fields than the example below. Treat any field not documented here as internal and subject to change.
`member_count` is returned by [List workspaces](/api-reference/workspaces/list) only, not by this endpoint.
## Example
```bash cURL theme={null}
curl https://www.orgo.ai/api/workspaces/$WORKSPACE_ID \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```python Python theme={null}
import os
import requests
api_key = os.environ["ORGO_API_KEY"]
workspace_id = os.environ["WORKSPACE_ID"]
response = requests.get(
f"https://www.orgo.ai/api/workspaces/{workspace_id}",
headers={"Authorization": f"Bearer {api_key}"}
)
workspace = response.json()
print(f"Workspace: {workspace['name']}")
for d in workspace.get("desktops", []):
print(f" - {d['name']}: {d['status']}")
```
```javascript JavaScript theme={null}
const apiKey = process.env.ORGO_API_KEY;
const workspaceId = process.env.WORKSPACE_ID;
const response = await fetch(`https://www.orgo.ai/api/workspaces/${workspaceId}`, {
headers: { 'Authorization': `Bearer ${apiKey}` }
});
const workspace = await response.json();
console.log(`Workspace: ${workspace.name}`);
workspace.desktops?.forEach(d => {
console.log(` - ${d.name}: ${d.status}`);
});
```
### Response
```json theme={null}
{
"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",
"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 }
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"name": "agent-2",
"os": "linux",
"ram": 8,
"cpu": 2,
"status": "stopped",
"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. |
| `403` | `{ "error": "You do not have access to this workspace." }` | Your account neither owns nor belongs to the workspace, or no workspace has that ID. An unknown ID returns this `403`, not `404`. |
| `403` | `{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }` | A workspace-scoped key requested a different workspace. |
| `500` | `{ "error": "" }` | Unexpected server error. |
| `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. |
## OpenAPI
````yaml GET /workspaces/{id}
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/{id}:
get:
tags:
- Workspaces
summary: Get workspace
description: >-
Returns one workspace by ID, including its computers under `desktops`,
your `role`, and your `permissions`. Owners and members can read it. An
unknown ID returns `403`, not `404`.
operationId: getWorkspace
parameters:
- name: id
in: path
required: true
description: Workspace ID
schema:
type: string
responses:
'200':
description: Workspace details
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceWithDesktops'
example:
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'
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'
'403':
description: >-
You neither own nor belong to the workspace (an unknown ID also
returns this), or the key is scoped to another workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
no-access:
summary: Not the owner or a member of the workspace
value:
error: You do not have access to this workspace.
scope-mismatch:
summary: The API key is scoped to another workspace
value:
error: >-
This API key cannot access this workspace
(workspace_scope_mismatch).
'500':
description: Unexpected server error.
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.