---
title: "Create a workstream"
method: POST
path: "/api/v1/projects/{id}/workstreams"
tags: ["Workstreams"]
---

# Create a workstream

`POST /api/v1/projects/{id}/workstreams`

## Request

- Base URL: `https://getorquesta.com`
- URL: `https://getorquesta.com/api/v1/projects/{id}/workstreams`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

`oclt_` and `oat_` act for the person they were minted for; `oak_` needs `workstreams:write`.
Without `agent_token_id` the workstream goes to the calling agent (`oat_`) or the project's
most recently seen agent; 409 `NO_AGENT` when the project has none. `run_on_microvm: true`
moves it onto the metered on-demand runner — refused for `oat_`, and the acting person must be a
project admin. If that step fails the workstream still exists and the response carries `microvmError`.

## Request body

- object: camelCase spellings (workingDirectory, systemPrompt, autoMerge, agentTokenId, runOnMicroVm) are accepted too.
  - `name` string, required: Unique per agent.
  - `kind` 'code' | 'analysis' | 'action'
  - `branch` string, nullable
  - `working_directory` string, nullable
  - `system_prompt` string, nullable: Purpose / standing instructions for the stream.
  - `auto_merge` boolean
  - `agent_token_id` string, uuid: Agent of the project that runs it.
  - `run_on_microvm` boolean

## Response `201`

Created.

- object
  - `workstream` Workstream, required
    - `id` string, uuid
    - `name` string
    - `kind` 'code' | 'analysis' | 'action'
    - `branch` string, nullable
    - `workingDirectory` string, nullable
    - `systemPrompt` string, nullable
    - `autoMerge` boolean
    - `status` string, nullable
    - `currentPromptId` string, uuid, nullable
    - `agentTokenId` string, uuid
    - `onMicrovm` boolean: Runs on the project's on-demand microVM.
    - `createdBy` string, uuid, nullable
    - `createdAt` string, date-time
  - `microvmError` object
    - `code` 'RUNNER_PROJECT_MODE' | 'RUNNER_UNAVAILABLE' | 'RUNNER_BILLING' | 'WORKSTREAM_NAME_TAKEN' | 'INTERNAL'
    - `error` string

## Other responses

- `400`: Invalid body.
- `401`: Missing or invalid API key.
- `403`: Insufficient scope, revoked token, or project-scope mismatch.
- `404`: Resource not found (or invisible to your scope).
- `409`: Name already used on that agent (`WORKSTREAM_NAME_TAKEN`) or no agent (`NO_AGENT`).

---

[API](https://skmtc.dev/getorquesta/apis/orquesta-public-api.md) · [All operations](https://skmtc.dev/getorquesta/apis/orquesta-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getorquesta/apis/orquesta-public-api/revisions/7d27e0ae8324?raw)