Orquesta Logs API

openapi: 3.2.0
info:
  title: Orquesta Public Logs 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: Logs
  description: Execution logs emitted by agents during a prompt run.
paths:
  /api/v1/logs:
    get:
      tags:
      - Logs
      summary: List execution logs by prompt or project
      operationId: listLogs
      description: 'Either `promptId` or `projectId` is required. When `promptId` is set the logs are ordered

        ascending by `sequence`; when `projectId` is set they are ordered descending by `timestamp`.'
      parameters:
      - in: query
        name: promptId
        required: false
        schema:
          type: string
          format: uuid
      - in: query
        name: projectId
        required: false
        schema:
          type: string
          format: uuid
      - in: query
        name: limit
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
      - in: query
        name: afterSequence
        required: false
        schema:
          type: integer
        description: 'With `promptId` only: return logs whose `sequence` is greater than this, for incremental polling.'
      responses:
        '200':
          description: Log list.
          content:
            application/json:
              schema:
                type: object
                required:
                - logs
                properties:
                  logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/LogEntry'
        '400':
          description: Neither `promptId` nor `projectId` provided.
          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:
    LogEntry:
      type: object
      required:
      - id
      - promptId
      - level
      - category
      - timestamp
      properties:
        id:
          type: string
          format: uuid
        promptId:
          type: string
          format: uuid
        level:
          type: string
          enum:
          - debug
          - info
          - warn
          - error
        category:
          type: string
          description: e.g. tool, system, chat, summary
        message:
          type: string
          nullable: true
          description: Truncated at 10K chars. Full content is in `details`.
        details:
          type: object
          nullable: true
          description: Structured payload (tool_result, command output, etc.)
        durationMs:
          type: integer
          nullable: true
        sequence:
          type: integer
          description: Monotonically increasing within a prompt
        timestamp:
          type: string
          format: date-time
    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)