Orquesta Workstreams API

openapi: 3.2.0
info:
  title: Orquesta Public Workstreams API
  version: '1.0'
  summary: Programmatic access to prompts, logs, projects, agents, users, and the Batuta LLM proxy.
  description: 'The Orquesta Public API exposes read access to your organization''s prompts, execution logs,

    projects, agents, and users, plus an OpenAI-compatible chat-completions proxy ("Batuta LLM")

    that routes across multiple upstream models with smart per-prompt classification.


    All endpoints under `/api/v1/*` are stable, versioned, and safe to integrate against. Internal

    dashboard endpoints (`/api/projects/[id]/batuta/*`, `/api/agent/*`, `/api/auth/*`, etc.) are

    NOT part of this contract and may change without notice.


    ## Authentication


    Pass an API key on every request via either header:


    - `Authorization: Bearer `

    - `X-API-Key: `


    Three token prefixes are accepted; each carries different scope semantics:


    | Prefix | Type | Scope | Scopes granted |

    |----------|-------------------|-------------------|---------------------------------------------------------|

    | `oak_` | Org API key | Organization, or a chosen subset of its projects | DB-configured (any of `prompts:read`, `prompts:write`, `logs:read`, ...) |

    | `oclt_` | CLI token | Organization | All four read scopes (synthesized), plus prompt submit |

    | `oat_` | Agent token | Project (single) | All four read scopes; queries restricted to its project |


    An `oclt_` inherits its creator''s access: an org owner or admin reaches every project,

    anyone else only the projects they are a member of. Projects outside that set are

    reported as not found.


    An `oak_` is org-wide unless it was restricted to specific projects when it was created

    (or edited afterwards). A restricted key sees only those projects in every listing, and

    a request naming any other project is reported as not found — the same answer as a

    project that does not exist, so a key cannot enumerate the organization.


    Generate keys from the dashboard: https://getorquesta.com/dashboard/settings


    ## Errors


    Non-Batuta endpoints return `{ "error": "human-readable message" }` with status codes

    401 (missing/invalid key), 403 (scope/project mismatch), 404 (not found), 500 (internal).


    Batuta proxy endpoints (`/chat/completions`, `/models`) return OpenAI-compatible errors:

    `{ "error": { "message": "...", "type": "auth_error" | "billing_error" | "routing_error" | "proxy_error" } }`.'
  contact:
    name: Orquesta Support
    url: https://getorquesta.com
    email: oscar@getorquesta.com
  license:
    name: Proprietary
servers:
- url: https://getorquesta.com
  description: Production
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Workstreams
  description: Named streams of work inside a project (branch, directory, purpose), each bound to one agent.
paths:
  /api/v1/projects/{id}/workstreams:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Workstreams
      summary: List a project's workstreams
      operationId: listWorkstreams
      description: Any token that reaches the project (`projects:read`).
      responses:
        '200':
          description: Workstream list, oldest first.
          content:
            application/json:
              schema:
                type: object
                required:
                - workstreams
                properties:
                  workstreams:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workstream'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Workstreams
      summary: Create a workstream
      operationId: createWorkstream
      description: '`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`.

        An `oat_` (agent token) does not create: it files a **proposal** (optional `reason`, ≤500 chars)

        and gets 202 `{proposal, status: pending}`; the workstream exists only once a project admin approves

        it in Studio or the approvals inbox. Where proposals are not configured the agent''s POST creates directly (201).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/WorkstreamInput'
              - type: object
                required:
                - name
                properties:
                  reason:
                    type: string
                    maxLength: 500
                    description: Why the agent wants this workstream (agent tokens only; shown to the approver).
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                type: object
                required:
                - workstream
                properties:
                  workstream:
                    $ref: '#/components/schemas/Workstream'
                  microvmError:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - RUNNER_PROJECT_MODE
                        - RUNNER_UNAVAILABLE
                        - RUNNER_BILLING
                        - WORKSTREAM_NAME_TAKEN
                        - INTERNAL
                      error:
                        type: string
        '202':
          description: Proposal filed (agent token); nothing created yet.
          content:
            application/json:
              schema:
                type: object
                required:
                - proposal
                - status
                properties:
                  proposal:
                    $ref: '#/components/schemas/WorkstreamProposal'
                  status:
                    type: string
                    enum:
                    - pending
        '400':
          description: Invalid body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Name already used on that agent (`WORKSTREAM_NAME_TAKEN`) or no agent (`NO_AGENT`).
        '429':
          description: More than 10 proposals already pending on this project (`TOO_MANY_PENDING`).
  /api/v1/projects/{id}/workstreams/proposals:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Workstreams
      summary: List workstream proposals
      operationId: listWorkstreamProposals
      description: Workstreams agents asked for. Any token that reaches the project; `mine=1` keeps an agent token's own.
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - approved
          - rejected
          - all
          default: pending
      - name: mine
        in: query
        schema:
          type: string
          enum:
          - '1'
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: Proposals, newest first.
          content:
            application/json:
              schema:
                type: object
                required:
                - proposals
                properties:
                  proposals:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkstreamProposal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/projects/{id}/workstreams/proposals/{proposalId}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    - name: proposalId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Workstreams
      summary: Get one workstream proposal
      operationId: getWorkstreamProposal
      description: Poll this after a 202 — `status` turns `approved` (with `workstreamId`) or `rejected` (with `decisionNote`).
      responses:
        '200':
          description: The proposal.
          content:
            application/json:
              schema:
                type: object
                required:
                - proposal
                properties:
                  proposal:
                    $ref: '#/components/schemas/WorkstreamProposal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/projects/{id}/workstreams/{workstreamId}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    - name: workstreamId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Workstreams
      summary: Get one workstream
      operationId: getWorkstream
      responses:
        '200':
          description: The workstream.
          content:
            application/json:
              schema:
                type: object
                properties:
                  workstream:
                    $ref: '#/components/schemas/Workstream'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Workstreams
      summary: Update a workstream
      operationId: updateWorkstream
      description: 'Send only the fields to change; `null` or `""` clears `branch`, `working_directory`, `system_prompt`.

        `run_on_microvm` true/false moves it onto / off the on-demand runner (not with `oat_`; project admins only).

        Setting `kind: action` turns the stream''s Autopilot autonomy back to `propose`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkstreamInput'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  workstream:
                    $ref: '#/components/schemas/Workstream'
        '400':
          description: Invalid body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: The microVM billing could not be set up (`RUNNER_BILLING`).
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Name conflict
          or the whole project already runs on the microVM.: null
    delete:
      tags:
      - Workstreams
      summary: Delete a workstream
      operationId: deleteWorkstream
      description: Not with `oat_`; the acting person must be a project admin. Its Autopilot config and proposals are deleted with it.
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  id:
                    type: string
                    format: uuid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message
    Workstream:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        kind:
          type: string
          enum:
          - code
          - analysis
          - action
        branch:
          type:
          - string
          - 'null'
        workingDirectory:
          type:
          - string
          - 'null'
        systemPrompt:
          type:
          - string
          - 'null'
        autoMerge:
          type: boolean
        status:
          type:
          - string
          - 'null'
        currentPromptId:
          type:
          - string
          - 'null'
          format: uuid
        agentTokenId:
          type: string
          format: uuid
        onMicrovm:
          type: boolean
          description: Runs on the project's on-demand microVM.
        cli:
          type:
          - string
          - 'null'
          enum:
          - orquesta
          - claude
          - kimi
          - cursor
          - kiro
          - null
          description: Engine for this workstream's prompts; null inherits the project's. Needs agent 0.2.288.
        model:
          type:
          - string
          - 'null'
          description: Claude --model name/alias
          or the Orquesta CLI endpoint (batuta or a configured provider). Ignored by other engines.: null
        createdBy:
          type:
          - string
          - 'null'
          format: uuid
        createdAt:
          type: string
          format: date-time
    WorkstreamProposal:
      type: object
      description: A workstream an agent asked to create; it becomes a Workstream when a project admin approves it.
      properties:
        id:
          type: string
          format: uuid
        projectId:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - pending
          - approved
          - rejected
        name:
          type: string
        kind:
          type: string
          enum:
          - code
          - analysis
          - action
        branch:
          type:
          - string
          - 'null'
        workingDirectory:
          type:
          - string
          - 'null'
        systemPrompt:
          type:
          - string
          - 'null'
        autoMerge:
          type:
          - boolean
          - 'null'
        cli:
          type:
          - string
          - 'null'
        model:
          type:
          - string
          - 'null'
        reason:
          type:
          - string
          - 'null'
        agentTokenId:
          type:
          - string
          - 'null'
          format: uuid
        proposedBy:
          type:
          - string
          - 'null'
          format: uuid
        decidedBy:
          type:
          - string
          - 'null'
          format: uuid
        decidedAt:
          type:
          - string
          - 'null'
          format: date-time
        decisionNote:
          type:
          - string
          - 'null'
        workstreamId:
          type:
          - string
          - 'null'
          format: uuid
          description: Set once approved.
        createdAt:
          type: string
          format: date-time
    WorkstreamInput:
      type: object
      description: camelCase spellings (workingDirectory, systemPrompt, autoMerge, agentTokenId, runOnMicroVm, cliPreference) and `cli` are accepted too.
      properties:
        name:
          type: string
          maxLength: 100
          description: Unique per agent.
        kind:
          type: string
          enum:
          - code
          - analysis
          - action
          default: code
        branch:
          type:
          - string
          - 'null'
          maxLength: 200
        working_directory:
          type:
          - string
          - 'null'
          maxLength: 500
        system_prompt:
          type:
          - string
          - 'null'
          maxLength: 20000
          description: Purpose / standing instructions for the stream.
        auto_merge:
          type: boolean
          default: false
        agent_token_id:
          type: string
          format: uuid
          description: Agent of the project that runs it.
        run_on_microvm:
          type: boolean
        cli_preference:
          type:
          - string
          - 'null'
          enum:
          - orquesta
          - claude
          - kimi
          - cursor
          - kiro
          - null
          description: Engine for this workstream's prompts; null/empty inherits the project's.
        model:
          type:
          - string
          - 'null'
          maxLength: 120
          pattern: ^[A-Za-z0-9._:/@\\[\\]-]{1,120}$
          description: For claude a --model name or alias (sonnet
          opus: null
          haiku); for orquesta an endpoint (batuta or a config name/id). Cleared when the engine does not take a model.: null
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: Insufficient scope, revoked token, or project-scope mismatch.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: Resource not found (or invisible to your scope).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: orquesta-token (oak_|oclt_|oat_)
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
x-provenance:
  method: harvested
  publisher: Orquesta
  source: https://getorquesta.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)