Create workspace
curl --request POST \
--url http://127.0.0.1:8765/v1/workspaces \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"id": "demo",
"config": {
"mounts": {
"/": {
"vfs": "ram",
"mode": "write"
}
}
}
}
'import requests
url = "http://127.0.0.1:8765/v1/workspaces"
payload = {
"id": "demo",
"config": { "mounts": { "/": {
"vfs": "ram",
"mode": "write"
} } }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({id: 'demo', config: {mounts: {'/': {vfs: 'ram', mode: 'write'}}}})
};
fetch('http://127.0.0.1:8765/v1/workspaces', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "demo",
"status": "running",
"created_at": "2026-11-07T00:00:00.000Z",
"system_time": null,
"sessions": [
{
"session_id": "01a1b425-ec80-7038-86e0-75b597344043",
"cwd": "/"
}
],
"mounts": [
{
"prefix": "/",
"vfs": "ram",
"mode": "write",
"description": "",
"backend": "workspace",
"mountpoint": null
}
],
"internals": null
}
Lifecycle
Create workspace
POST
/
v1
/
workspaces
Create workspace
curl --request POST \
--url http://127.0.0.1:8765/v1/workspaces \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"id": "demo",
"config": {
"mounts": {
"/": {
"vfs": "ram",
"mode": "write"
}
}
}
}
'import requests
url = "http://127.0.0.1:8765/v1/workspaces"
payload = {
"id": "demo",
"config": { "mounts": { "/": {
"vfs": "ram",
"mode": "write"
} } }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({id: 'demo', config: {mounts: {'/': {vfs: 'ram', mode: 'write'}}}})
};
fetch('http://127.0.0.1:8765/v1/workspaces', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "demo",
"status": "running",
"created_at": "2026-11-07T00:00:00.000Z",
"system_time": null,
"sessions": [
{
"session_id": "01a1b425-ec80-7038-86e0-75b597344043",
"cwd": "/"
}
],
"mounts": [
{
"prefix": "/",
"vfs": "ram",
"mode": "write",
"description": "",
"backend": "workspace",
"mountpoint": null
}
],
"internals": null
}
Create a workspace from a configuration or saved template.
Returns
See error examples and recovery steps. The complete OpenAPI contract includes every response schema.
201 when created, 200 for an identical retry with the same ID, or 409 if that ID has a different configuration. Set explain=true to check policies without creating anything.
{
"id": "demo",
"status": "running",
"created_at": "2026-11-07T00:00:00.000Z",
"system_time": null,
"sessions": [
{
"session_id": "01a1b425-ec80-7038-86e0-75b597344043",
"cwd": "/"
}
],
"mounts": [
{
"prefix": "/",
"vfs": "ram",
"mode": "write",
"description": "",
"backend": "workspace",
"mountpoint": null
}
],
"internals": null
}
Errors
Errors
| Status | Meaning |
|---|---|
400 | The request is malformed: the body is not JSON (invalid_json) or not a JSON object, a field is missing (missing_field), unknown (unknown_field) or has a wrong value (invalid_value), or the request is otherwise invalid (invalid_request). param names the field at fault. |
401 | The token is missing or wrong (unauthorized). |
403 | The call is refused. A policy refused it (policy_refused, with decision), a mount mode or permission refused it (forbidden), the backend is out of space or quota (storage_full), or the request came for a host or from a browser origin that is not allowed (host_not_allowed, origin_not_allowed). |
409 | The identifier already exists with a different workspace configuration. |
429 | Past a rate limit (rate_limited), or a new session past max_sessions (session_limit). |
503 | The server cannot take the request now. It is at max_workspaces (server_full), shutting down (shutting_down), or no worker can take the request (unavailable). |
Authorizations
Body
application/json
Workspace configuration or saved template to create from. Supply exactly one of config and template.
Response
Existing workspace for an identical retry, or policy evaluation when explain=true.
- WorkspaceDetail
- Option 2