Opper AI Roundtable API

openapi: 3.2.0
info:
  description: Schema-driven generative API that orchestrates LLM-powered workflows.
  title: Task Roundtable API
  version: 3.0.0
servers:
- description: Production
  url: https://api.opper.ai
- description: Local development
  url: http://localhost:8080
security:
- BearerAuth: []
tags:
- description: Roundtable endpoint — fan out a query to multiple LLMs and combine results
  name: Roundtable
paths:
  /v3/roundtable:
    post:
      description: Send a query to multiple models in parallel and combine results using a configurable resolution strategy (summary, fast, multiple_choice).
      operationId: createRoundtable
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoundtableRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoundtableResponse'
            text/event-stream:
              schema:
                description: 'Server-Sent Events stream. Each event is a JSON object prefixed with ''data: ''.'
                type: string
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          description: Unauthorized - missing or invalid API key
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Roundtable
      tags:
      - Roundtable
      x-beta: true
components:
  schemas:
    ErrorResponse:
      properties:
        error:
          properties:
            code:
              type: string
            details:
              description: Any value
            message:
              type: string
          required:
          - code
          - message
          type: object
        meta:
          type: object
      required:
      - error
      type: object
    RoundtableResponse:
      properties:
        data:
          description: Final consolidated output. Null in fast mode (no consolidation runs).
          type: string
        id:
          description: Stable identifier for this roundtable call.
          type: string
        meta:
          description: Aggregated call metadata.
          properties:
            models_used:
              description: Names of the models queried in parallel.
              items:
                type: string
              type: array
            resolution:
              description: Resolution mode that produced this response (summary / fast / multiple_choice).
              type: string
            summary_model:
              description: Model used for the consolidation call. Only set in summary mode.
              type: string
            summary_usage:
              description: Token counts for the consolidation call aggregated across retries.
              properties:
                cache_creation_1h_tokens:
                  type: integer
                cache_creation_tokens:
                  type: integer
                cache_read_tokens:
                  type: integer
                code_interpreter_sessions:
                  type: integer
                extra:
                  type: object
                file_search_calls:
                  type: integer
                google_search_prompts:
                  type: integer
                google_search_queries:
                  type: integer
                image_generation_calls:
                  type: integer
                input_audio_tokens:
                  type: integer
                input_image_tokens:
                  type: integer
                input_tokens:
                  type: integer
                output_audio_tokens:
                  type: integer
                output_image_tokens:
                  type: integer
                output_tokens:
                  type: integer
                reasoning_tokens:
                  type: integer
                service_tier:
                  type: string
                url_context_requests:
                  type: integer
                web_fetch_requests:
                  type: integer
                web_search_calls:
                  type: integer
                web_search_requests:
                  type: integer
                x_search_calls:
                  type: integer
              required:
              - input_tokens
              - output_tokens
              type: object
            total_cost:
              description: USD cost summed across all fan-out models and the consolidation call.
              type: number
            total_duration_ms:
              description: End-to-end request duration in milliseconds.
              type: integer
            trace_uuid:
              description: UUID of the trace span for this roundtable call.
              type: string
          required:
          - resolution
          - models_used
          - total_cost
          - total_duration_ms
          type: object
        model_results:
          description: Per-model fan-out results in the order they appeared in the request.
          items:
            properties:
              cost:
                description: USD cost for this model call summed across retries.
                type: number
              data:
                description: Raw model output. When output_schema is supplied this is a JSON string that validated against the schema.
                type: string
              duration_ms:
                description: Wall-clock time for this model call in milliseconds including retries.
                type: integer
              error:
                description: Provider or transport error message. Empty on success.
                type: string
              index:
                description: Position of this model in the request's models array (0-based).
                type: integer
              model:
                description: Name of the model that produced this result.
                type: string
              schema_error:
                description: Why the output failed schema validation. Empty when schema_valid is true or absent.
                type: string
              schema_valid:
                description: Whether the model's output validated against the request's output_schema. Absent when no output_schema was supplied.
                type: boolean
              usage:
                description: Token counts aggregated across all retry attempts.
                properties:
                  cache_creation_1h_tokens:
                    type: integer
                  cache_creation_tokens:
                    type: integer
                  cache_read_tokens:
                    type: integer
                  code_interpreter_sessions:
                    type: integer
                  extra:
                    type: object
                  file_search_calls:
                    type: integer
                  google_search_prompts:
                    type: integer
                  google_search_queries:
                    type: integer
                  image_generation_calls:
                    type: integer
                  input_audio_tokens:
                    type: integer
                  input_image_tokens:
                    type: integer
                  input_tokens:
                    type: integer
                  output_audio_tokens:
                    type: integer
                  output_image_tokens:
                    type: integer
                  output_tokens:
                    type: integer
                  reasoning_tokens:
                    type: integer
                  service_tier:
                    type: string
                  url_context_requests:
                    type: integer
                  web_fetch_requests:
                    type: integer
                  web_search_calls:
                    type: integer
                  web_search_requests:
                    type: integer
                  x_search_calls:
                    type: integer
                required:
                - input_tokens
                - output_tokens
                type: object
            required:
            - index
            - model
            - data
            - duration_ms
            type: object
          type: array
      required:
      - id
      - data
      - meta
      - model_results
      type: object
    RoundtableRequest:
      properties:
        choices:
          description: Literal options for multiple_choice resolution
          items:
            type: string
          type: array
        input:
          description: The question or prompt sent to all models
          type: string
        instructions:
          description: System prompt shared across all model calls
          type: string
        max_retries:
          description: Per-model retry count on transient errors (default 1 / max 3)
          type: integer
        models:
          description: Models to query in parallel
          items:
            properties:
              max_tokens:
                description: Override max output tokens for this model. Falls back to the model's configured default or 8192 when unspecified.
                type: integer
              name:
                description: Model identifier (e.g. gpt-4o or anthropic/claude-sonnet-4-20250514)
                type: string
              reasoning:
                description: 'Reasoning effort: low/medium/high/max'
                type: string
              temperature:
                description: Override temperature for this model (0.0-2.0)
                type: number
              top_p:
                description: Override top_p for this model
                type: number
            required:
            - name
            type: object
          type: array
        output_schema:
          description: JSON Schema for structured output — applied to all model calls and the consolidation call
          type: object
        resolution:
          description: 'Resolution mode: summary (default) / fast / multiple_choice'
          type: string
        stream:
          description: Enable SSE streaming
          type: boolean
        summary_model:
          description: Override the model used for consolidation in summary mode
          type: string
        timeout_ms:
          description: Per-model timeout in milliseconds covering all retries (default 120000 / max 300000)
          type: integer
      required:
      - input
      - models
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: API Key
      description: API key authentication. Pass your API key as a Bearer token.
      scheme: bearer
      type: http
    MCPBearer:
      description: Delegated user OAuth access token for the Opper MCP resource. Obtain through advertised OAuth authorization; runtime and management service keys are not accepted.
      scheme: bearer
      type: http
    ManagementBearer:
      bearerFormat: Management API Key
      description: Management API authentication. Pass an `op-mak-…` management token as a Bearer token. Runtime `op-…` API keys are rejected with 403 — they belong on the data-plane endpoints. Mint a management key from the platform UI under Settings → API keys.
      scheme: bearer
      type: http