Orquesta Projects API

openapi: 3.2.0
info:
  title: Orquesta Public Projects 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: Projects
  description: Projects in your organization.
paths:
  /api/v1/projects:
    get:
      tags:
      - Projects
      summary: List projects in your organization
      operationId: listProjects
      description: 'For agent tokens (`oat_`), returns only the token''s project. With `grantable=1`, only the

        projects the token''s user administers, each with `role`.'
      parameters:
      - name: grantable
        in: query
        required: false
        schema:
          type: string
          enum:
          - '1'
        description: Keep only projects the user administers (org owner/admin or project admin) and add `role`.
      responses:
        '200':
          description: Project list.
          content:
            application/json:
              schema:
                type: object
                required:
                - projects
                properties:
                  projects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/projects/{id}:
    get:
      tags:
      - Projects
      summary: Get one project with its organization and the token user's roles
      operationId: getProject
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Project detail. Any role that reaches the project may read it.
          content:
            application/json:
              schema:
                type: object
                required:
                - project
                properties:
                  project:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      slug:
                        type: string
                      description:
                        type: string
                        nullable: true
                      agentOnline:
                        type: boolean
                      agentLastSeen:
                        type: string
                        format: date-time
                        nullable: true
                      createdAt:
                        type: string
                        format: date-time
                      organization:
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                          name:
                            type: string
                            nullable: true
                      orgRole:
                        type: string
                        nullable: true
                        description: The token user's org role (owner/admin/member…), null when none or unattributed.
                      projectRole:
                        type: string
                        nullable: true
                        description: The token user's project role (admin/developer/prompter), null when none.
                      iconUrl:
                        type: string
                        format: uri
                        nullable: true
                        description: https only; null when the project has no icon.
                      derplins:
                        type: object
                        properties:
                          enrolled:
                            type: boolean
                          enrolledAt:
                            type: string
                            format: date-time
                            nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/me:
    get:
      tags:
      - Projects
      summary: The user the token acts for
      operationId: getMe
      responses:
        '200':
          description: Identity of the token's user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      email:
                        type: string
                        nullable: true
                      fullName:
                        type: string
                        nullable: true
                  organizationId:
                    type: string
                    format: uuid
                  tokenType:
                    type: string
                    enum:
                    - api_key
                    - cli
                    - agent
                    - mcp
                  scopes:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Token not attributed to a user.
  /api/v1/projects/{id}/members:
    post:
      tags:
      - Projects
      summary: Add a user to a project the token's user administers
      operationId: addProjectMember
      description: 'Requires an `omt_` with `members:write`. The user must already belong to the project''s

        organization. `admin` is never granted. The added user is notified in-app and by email.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                role:
                  type: string
                  enum:
                  - prompter
                  - developer
                  default: developer
      responses:
        '200':
          description: Already a member (`adopted:true`), nothing changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectMemberGrant'
        '201':
          description: Added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectMemberGrant'
        '400':
          description: Invalid body, or `not_org_member`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Plan member limit reached (`BILLING_LIMIT`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/projects/{id}/members/{memberId}:
    delete:
      tags:
      - Projects
      summary: Remove a member from a project the token's user administers
      operationId: removeProjectMember
      description: Requires `members:write`. Admin rows and the acting user cannot be removed; business-managed rows answer 409.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: memberId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Removed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  removed:
                    type: boolean
                  memberId:
                    type: string
                  userId:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Membership managed by a Studio business (`managed_by_business`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/v1/projects/{id}/agent-tokens:
    post:
      tags:
      - Projects
      summary: Mint an agent token (oat_) for the project
      operationId: createProjectAgentToken
      description: Requires `agent-tokens:write`. The raw token appears only in this response.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  maxLength: 100
                expiresInDays:
                  type: integer
                  minimum: 1
                  maximum: 365
                  default: 365
      responses:
        '201':
          description: Minted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tokenId:
                    type: string
                  name:
                    type: string
                  token:
                    type: string
                    description: oat_… — store it now, it is never shown again
                  expiresAt:
                    type: string
                    format: date-time
        '400':
          description: Invalid body.
          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/projects/{id}/agent-tokens/{tokenId}:
    delete:
      tags:
      - Projects
      summary: Revoke an agent token of the project
      operationId: revokeProjectAgentToken
      description: Requires `agent-tokens:write`. Idempotent.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: tokenId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  revoked:
                    type: boolean
                  tokenId:
                    type: string
                  revokedAt:
                    type: string
                    format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/projects/{id}/notifications:
    post:
      tags:
      - Projects
      summary: Send an in-app notification to a project member
      operationId: notifyProjectMember
      description: Requires `notifications:write`. `link` must be a path on Orquesta starting with `/`.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - title
              - message
              properties:
                email:
                  type: string
                  format: email
                title:
                  type: string
                  maxLength: 120
                message:
                  type: string
                  maxLength: 1000
                link:
                  type: string
                  maxLength: 500
      responses:
        '201':
          description: Sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  notificationId:
                    type: string
                  userId:
                    type: string
        '400':
          description: Invalid body or link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Project:
      type: object
      required:
      - id
      - name
      - createdAt
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        description:
          type: string
          nullable: true
        agentOnline:
          type: boolean
        agentLastSeen:
          type: string
          format: date-time
          nullable: true
        productionUrl:
          type: string
          format: uri
          nullable: true
        iconUrl:
          type: string
          format: uri
          nullable: true
          description: 'Project icon: the published site''s favicon, else the GitHub repo owner''s avatar. Null when the project has neither (https only).'
        derplins:
          type: object
          description: Whether the project opted into Derplins.
          properties:
            enrolled:
              type: boolean
            enrolledAt:
              type: string
              format: date-time
              nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        role:
          type: string
          enum:
          - org_owner
          - org_admin
          - admin
          description: 'Only with `grantable=1`: why the user may administer this project.'
    ProjectMemberGrant:
      type: object
      properties:
        memberId:
          type: string
        userId:
          type: string
        role:
          type: string
          enum:
          - prompter
          - developer
        adopted:
          type: boolean
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message
  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)