Orquesta Prompts API

openapi: 3.2.0
info:
  title: Orquesta Public Prompts 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: Prompts
  description: Prompt execution records (one per CLI/agent/dashboard run).
paths:
  /api/v1/prompts:
    get:
      tags:
      - Prompts
      summary: List prompts in your organization
      operationId: listPrompts
      description: 'Returns prompts ordered by `createdAt` descending. Agent-token (`oat_`) calls are

        automatically restricted to the token''s project; passing a different `projectId` returns 403.'
      parameters:
      - in: query
        name: projectId
        required: false
        schema:
          type: string
          format: uuid
      - in: query
        name: createdBy
        required: false
        schema:
          type: string
          format: uuid
        description: User id of the prompt author
      - in: query
        name: status
        required: false
        schema:
          type: string
        description: Single status, or comma-separated list (e.g. "running,pending")
      - in: query
        name: createdByEmail
        required: false
        schema:
          type: string
          format: email
        description: Author by email (exact, case-insensitive). Malformed → 400; unknown → empty list.
      - in: query
        name: from
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: createdAfter
        required: false
        schema:
          type: string
          format: date-time
        description: Alias of `from`.
      - in: query
        name: fields
        required: false
        schema:
          type: string
          enum:
          - meta
        description: '`meta` returns only id, projectId, status, source, cliType, createdBy, createdAt, completedAt — no content.'
      - in: query
        name: to
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: sessionId
        required: false
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,128}$
        description: Only prompts reported by this interactive session (turns an orquesta-cli session self-reports)
      - in: query
        name: offset
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - in: query
        name: limit
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 50
      responses:
        '200':
          description: Paginated prompt list.
          content:
            application/json:
              schema:
                type: object
                required:
                - prompts
                - pagination
                properties:
                  prompts:
                    type: array
                    items:
                      $ref: '#/components/schemas/PromptListItem'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
      - Prompts
      summary: Submit a prompt for execution
      operationId: createPrompt
      description: 'Queues a prompt on a project''s agent. The prompt is created with status `pending`;

        the agent picks it up on its next heartbeat (every 15 seconds) and transitions it to

        `running` — there is no separate execute call. Poll `GET /api/v1/prompts/{id}` or

        `GET /api/v1/logs?promptId=...` for progress.


        Requires a token that can be attributed to a user: a CLI token (`oclt_`), or an org

        API key (`oak_`) with the `prompts:write` scope. Agent tokens (`oat_`) are rejected —

        a token that lives on the machine which would run the prompt cannot enqueue its own work.


        A project you cannot reach returns 404, not 403, so ids cannot be probed.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - projectId
              - content
              properties:
                projectId:
                  type: string
                  format: uuid
                content:
                  type: string
                  maxLength: 50000
                  description: The prompt text.
                context:
                  type: object
                  additionalProperties: true
                  description: Arbitrary JSON passed through to the agent.
                tags:
                  type: array
                  items:
                    type: string
                source:
                  type: string
                  enum:
                  - api
                  - dashboard
                  default: api
                mode:
                  type: string
                  enum:
                  - run
                  - report
                  default: run
                  description: '`report` records work already done elsewhere: the prompt is stored `completed` with a local-only source and is never dispatched to an agent. `source` is ignored; no agent is required. Refused (403) for external-agent tokens.'
                result:
                  type: string
                  maxLength: 50000
                  description: Result text to store with a `report`-mode prompt.
                workstreamId:
                  type: string
                  format: uuid
                  description: 'Run the prompt in this workstream: its agent (the microVM when the workstream runs there, which is woken), working directory and branch. 404 when the workstream is not in the project.'
      responses:
        '201':
          description: Prompt created and queued.
          content:
            application/json:
              schema:
                type: object
                required:
                - prompt
                properties:
                  prompt:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      projectId:
                        type: string
                        format: uuid
                      content:
                        type: string
                      status:
                        type: string
                        example: pending
                      source:
                        type: string
                      createdBy:
                        type: string
                        format: uuid
                      createdAt:
                        type: string
                        format: date-time
                      workstreamId:
                        type: string
                        format: uuid
                      completedAt:
                        type: string
                        format: date-time
                        description: Report mode only.
                      mode:
                        type: string
                        enum:
                        - report
                        description: Present only in report mode.
        '400':
          description: Invalid body, or the project has no agent configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/prompts/{id}:
    get:
      tags:
      - Prompts
      summary: Get a single prompt by id (with context)
      operationId: getPrompt
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Prompt detail.
          content:
            application/json:
              schema:
                type: object
                required:
                - prompt
                properties:
                  prompt:
                    $ref: '#/components/schemas/PromptDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Prompts
      summary: Update a prompt's collaboration fields
      operationId: updatePrompt
      description: 'Star, tag, assign or re-rate an existing prompt. Requires a CLI token (`oclt_`) or an

        org API key (`oak_`) with `prompts:write`; agent tokens are read-only. `assigned_to`

        must be a member of the same organization.'
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                is_starred:
                  type: boolean
                tags:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                assigned_to:
                  type:
                  - string
                  - 'null'
                  format: uuid
                complexity:
                  type:
                  - string
                  - 'null'
      responses:
        '200':
          description: The updated fields.
          content:
            application/json:
              schema:
                type: object
                required:
                - prompt
                properties:
                  prompt:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      is_starred:
                        type: boolean
                      tags:
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                      assigned_to:
                        type:
                        - string
                        - 'null'
                        format: uuid
                      complexity:
                        type:
                        - string
                        - 'null'
        '400':
          description: No valid fields, a wrong field type, or an assignee outside the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/prompts/{id}/cancel:
    post:
      tags:
      - Prompts
      summary: Cancel a pending or running prompt
      operationId: cancelPrompt
      description: 'Tells the project''s agent to stop the prompt and marks it `failed` with error

        `Cancelled by user`. A prompt that already finished keeps its outcome and the call

        returns `cancelled: false` with its current status. Requires a CLI token (`oclt_`) or an

        org API key with `prompts:write`; agent tokens are rejected.'
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Cancellation result.
          content:
            application/json:
              schema:
                type: object
                required:
                - cancelled
                - status
                properties:
                  cancelled:
                    type: boolean
                  status:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    InternalError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    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'
  schemas:
    Pagination:
      type: object
      required:
      - offset
      - limit
      - total
      - hasMore
      properties:
        offset:
          type: integer
          minimum: 0
        limit:
          type: integer
          minimum: 1
        total:
          type: integer
          minimum: 0
        hasMore:
          type: boolean
    PromptDetail:
      allOf:
      - $ref: '#/components/schemas/PromptListItem'
      - type: object
        properties:
          context:
            type: object
            nullable: true
            description: Arbitrary context attached at creation time
          result:
            nullable: true
            description: 'The agent''s final deliverable (JSON: usually a summary/text); null until the prompt completes'
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message
    PromptListItem:
      type: object
      required:
      - id
      - content
      - status
      - source
      - projectId
      - createdAt
      properties:
        id:
          type: string
          format: uuid
        content:
          type: string
        status:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          - cancelled
        source:
          type: string
          enum:
          - api
          - auto
          - auto-brain
          - batuta
          - dashboard
        projectId:
          type: string
          format: uuid
        projectName:
          type: string
        createdBy:
          type: string
          format: uuid
          nullable: true
        createdByEmail:
          type: string
          format: email
          nullable: true
        createdByName:
          type: string
          nullable: true
        parentPromptId:
          type: string
          format: uuid
          nullable: true
        complexity:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
        isStarred:
          type: boolean
        tokensUsed:
          type: integer
          minimum: 0
        costCents:
          type: integer
          minimum: 0
        cliType:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
          description: Extracted from llm_config.model
        sessionId:
          type: string
          nullable: true
          description: Interactive session that reported this prompt (context.sessionId)
        gitBranch:
          type: string
          nullable: true
        gitCommitSha:
          type: string
          nullable: true
        gitCommitUrl:
          type: string
          format: uri
          nullable: true
        linearIssueIdentifier:
          type: string
          nullable: true
        linearIssueUrl:
          type: string
          format: uri
          nullable: true
        createdAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        error:
          type: string
          nullable: true
  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)