Create workspace | Zuse Docs

POST/v1/api/workspaces

Starts a cloud workspace on a fresh branch and, if you pass a prompt, sends it to the agent. The machine starts right away; poll Get workspace or subscribe to webhooks to follow progress.

Authorization

apiKey

AuthorizationBearer <token>

An API key that starts with zk_. Create one in the Zuse app.

In: header

Header Parameters

Idempotency-Key?string

Retrying with the same key returns the original result instead of repeating the action. Up to 200 characters.

Lengthlength <= 200

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Options for a new cloud workspace. Every field is optional when your account has one ready project and an earlier workspace to copy the agent and model from.

prompt?string

First message for the agent, up to 65,536 characters. Omit it to create an idle workspace, for example to upload attachments first.

Lengthlength <= 65536

projectId?string

Project to work in. Defaults to your only ready project; required when you have more than one.

providerId?string

Cloud machine provider, from List providers. Defaults to your connected provider or the Zuse default.

agent?string

Agent to run, from List agents. Defaults to the agent of your most recent workspace.

model?string

Model ID for the agent. Defaults to the model of your most recent workspace.

runtimeMode?string

Permission mode for the agent. API-created workspaces default to full-access.

Default"full-access"

Value in

"auto"
"approval-required"
"auto-accept-edits"
"auto-accept-edits-and-bash"
"full-access"

baseRef?string

Branch, tag, or commit to start from. Defaults to the project's default branch. Allowed characters: letters, digits, ., _, /, #, -.

branch?string

Name of the branch to create. Defaults to a generated name. Allowed characters: letters, digits, ., _, /, -.

idempotencyKey?string

Makes retries safe, up to 200 characters. You can send the Idempotency-Key header instead; if you send both they must match.

Lengthlength <= 200

Response Body

`application/json`

curl -X POST "https://example.com/v1/api/workspaces" \  -H "Content-Type: application/json" \  -d '{}'

{  "workspace": {    "workspaceId": "workspace_Q2x8mN4pR7sT1vWz",    "providerId": "box",    "projectId": "proj_8f2c1a",    "branch": "fix-order-validation",    "baseRef": "main",    "state": "queued",    "statusCode": "agent-running",    "startupPhase": "allocating",    "runtimeState": "offline",    "agentStatus": "working",    "latestSeq": 4,    "lastTurn": {      "turnId": "turn_7a2c9e",      "outcome": "completed",      "completedAt": 1760697600000    },    "createdAt": 1760697600000,    "updatedAt": 1760697600000  }}

{  "error": "invalid_api_key",  "detail": "string"}

{  "error": "invalid_api_key",  "detail": "string"}

{  "error": "invalid_api_key",  "detail": "string"}

{  "error": "invalid_api_key",  "detail": "string"}

{  "error": "invalid_api_key",  "detail": "string"}

{  "error": "invalid_api_key",  "detail": "string"}

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`