Orquesta Agent Mesh API

openapi: 3.2.0
info:
  title: Orquesta Public Agent Mesh 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: Agent Mesh
  description: 'Who may ask whom inside an organization, as code: export a declarative document, edit it,

    plan (a diff that changes nothing) and apply. Needs an org API key (`oak_`) with the opt-in

    scopes `mesh:read` / `mesh:write` (writing: org-wide key whose creator is owner/admin).

    `oat_` reads its own neighbourhood and never writes. The organization id is

    `organizationId` in `GET /api/v1/projects`. The same flow is exposed over MCP

    (`mesh_get`, `mesh_plan`, `mesh_apply`, `mesh_status`). Guide: /docs#mcp-mesh-code.'
paths:
  /api/organizations/{orgId}/mesh/export:
    parameters:
    - name: orgId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Agent Mesh
      summary: Export the mesh as a document
      operationId: exportMesh
      description: '`mesh:read`. Returns `{version: 1, enforce, families[], capabilities[], nodes[], edges[], flows[]}`

        plus `state_hash`. Nodes are named by project slug (or `proposed:`), never by database id.'
      responses:
        '200':
          description: The mesh document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeshDocument'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/organizations/{orgId}/mesh/plan:
    parameters:
    - name: orgId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      tags:
      - Agent Mesh
      summary: Plan a change (diff only, nothing applied)
      operationId: planMesh
      description: '`mesh:write`. Body: the edited document (or `{document}`). An omitted section is untouched; an

        included one is authoritative (unlisted edges are deleted). A plan that creates or widens an

        encargo+auto edge, changes `enforce` or deletes more than 20 edges is stored as

        `pending_confirmation` until the org owner approves it. 30 plans per hour per actor.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeshDocument'
      responses:
        '201':
          description: Plan stored (valid 1 h).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeshPlan'
        '400':
          description: '`invalid_document` — wrong shape.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: '`invalid_plan` — unresolved references; `details` lists every problem.'
        '429':
          description: Rate limited.
  /api/organizations/{orgId}/mesh/apply:
    parameters:
    - name: orgId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      tags:
      - Agent Mesh
      summary: Apply a plan atomically
      operationId: applyMesh
      description: '`mesh:write`. One transaction. 20 applies per hour per actor.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - plan_id
              properties:
                plan_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeshPlan'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: '`mesh_state_changed` (the mesh moved since the plan — plan again) or `confirmation_required` (waits for the owner).'
        '410':
          description: '`plan_expired`.'
  /api/organizations/{orgId}/mesh/plans:
    parameters:
    - name: orgId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Agent Mesh
      summary: Recent plans
      operationId: listMeshPlans
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Plans, newest first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  plans:
                    type: array
                    items:
                      $ref: '#/components/schemas/MeshPlan'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/organizations/{orgId}/mesh/plans/{planId}:
    parameters:
    - name: orgId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    - name: planId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Agent Mesh
      summary: Plan status
      operationId: getMeshPlan
      responses:
        '200':
          description: The plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeshPlan'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Agent Mesh
      summary: Approve or reject a plan
      operationId: decideMeshPlan
      description: Approve needs the org owner's dashboard session; a token may only reject a plan it made.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - decision
              properties:
                decision:
                  type: string
                  enum:
                  - approve
                  - reject
      responses:
        '200':
          description: Decided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeshPlan'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  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'
  schemas:
    MeshPlan:
      type: object
      properties:
        plan_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - planned
          - pending_confirmation
          - applied
          - rejected
          - expired
          - stale
          - failed
        changes:
          type: array
          items:
            type: object
        summary:
          type: object
        confirmation_reasons:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string
          description: Only on plan creation. Inconsistencies already in the mesh (node capabilities missing from the catalog, edge capabilities the target does not offer) that the plan carries over unchanged; only ones the document introduces are errors.
        state_hash:
          type: string
        plan_hash:
          type: string
        expires_at:
          type: string
          format: date-time
        no_op:
          type: boolean
    MeshDocument:
      type: object
      description: Mesh as code, version 1. See /docs#mcp-mesh-code.
      properties:
        version:
          type: integer
          enum:
          - 1
        enforce:
          type: string
          enum:
          - 'off'
          - shadow
          - 'on'
        families:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              color:
                type: string
              sort_order:
                type: integer
        capabilities:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              label:
                type: string
              description:
                type: string
        nodes:
          type: array
          items:
            type: object
            properties:
              ref:
                type: string
              project:
                type: string
                description: Project slug
              label:
                type: string
              family:
                type: string
              status:
                type: string
              capabilities:
                type: array
                items:
                  type: string
              notes:
                type: string
        edges:
          type: array
          items:
            type: object
            properties:
              from:
                type: string
                description: Node ref, or @handle
              to:
                type: string
              kind:
                type: string
                enum:
                - consulta
                - encargo
              approval:
                type: string
                enum:
                - auto
                - owner
                - target
                - deny
              capabilities:
                type: array
                items:
                  type: string
              daily_limit:
                type: integer
              allow_auto_agent:
                type: boolean
        flows:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              color:
                type: string
              goal:
                type: string
              edges:
                type: array
                items:
                  type: object
        state_hash:
          type: string
          readOnly: true
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message
  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)