Amigo Simulations API

openapi: 3.1.0
info:
  title: Amigo Account Simulations API
  version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
  Bearer-Authorization-Organization: []
  Basic: []
tags:
- name: Simulations
paths:
  /v1/{workspace_id}/simulations/runs:
    post:
      tags:
      - Simulations
      summary: Create Simulation Run
      description: Create a simulation coverage run with an optional Lakebase branch.
      operationId: create-simulation-run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRunRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create-Simulation-Run
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
    get:
      tags:
      - Simulations
      summary: List Simulation Runs
      operationId: list-simulation-runs
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List-Simulation-Runs
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/runs/summary:
    get:
      tags:
      - Simulations
      summary: Get Simulation Runs Summary
      description: 'Aggregate run counts (total + by status) for the Runs summary strip.


        Registered *before* ``/runs/{run_id}`` so the static ``summary`` path

        segment is matched here rather than parsed as a run UUID (which would 422).'
      operationId: get-simulation-runs-summary
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationRunSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/suites:
    get:
      tags:
      - Simulations
      summary: List Simulation Suites
      description: List first-class simulation suites.
      operationId: list-simulation-suites
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSimulationSuitesResponse'
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
    post:
      tags:
      - Simulations
      summary: Create Simulation Suite
      description: Create a reusable suite definition for saved simulation cases.
      operationId: create-simulation-suite
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSimulationSuiteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationSuiteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
  /v1/{workspace_id}/simulations/suites/{suite_id}:
    get:
      tags:
      - Simulations
      summary: Get Simulation Suite
      operationId: get-simulation-suite
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: suite_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Suite Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationSuiteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Simulations
      summary: Update Simulation Suite
      operationId: update-simulation-suite
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: suite_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Suite Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSimulationSuiteRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationSuiteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Simulations
      summary: Delete Simulation Suite
      operationId: delete-simulation-suite
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: suite_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Suite Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/suites/{suite_id}/runs:
    get:
      tags:
      - Simulations
      summary: List Simulation Suite Runs
      description: List durable suite-run groups for a first-class suite.
      operationId: list-simulation-suite-runs
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: suite_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Suite Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 20
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSimulationSuiteRunsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/cases:
    get:
      tags:
      - Simulations
      summary: List Simulation Cases
      description: List durable simulation cases for case-library inspection.
      operationId: list-simulation-cases
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Id
      - name: tags
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
              maxLength: 128
            maxItems: 20
          - type: 'null'
          title: Tags
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          exclusiveMinimum: 0
          default: 10
          title: Limit
      - name: continuation_token
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Continuation Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_SimulationCaseResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Simulations
      summary: Create Simulation Cases
      description: Create durable simulation cases for an internal benchmark suite.
      operationId: create-simulation-cases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSimulationCasesRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSimulationCasesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
  /v1/{workspace_id}/simulations/cases/{case_id}:
    get:
      tags:
      - Simulations
      summary: Get Simulation Case
      description: Fetch one durable simulation case for case-library inspection.
      operationId: get-simulation-case
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: case_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Case Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationCaseResponse'
        '404':
          description: Simulation case not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Simulations
      summary: Update Simulation Case
      description: Update editable fields on one durable simulation case.
      operationId: update-simulation-case
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: case_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Case Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSimulationCaseRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationCaseResponse'
        '404':
          description: Simulation case not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Simulations
      summary: Delete Simulation Case
      description: Delete one durable simulation case.
      operationId: delete-simulation-case
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: case_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Case Id
      responses:
        '204':
          description: Successful Response
        '404':
          description: Simulation case not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/runs/{run_id}:
    get:
      tags:
      - Simulations
      summary: Get Simulation Run
      description: 'Fetch a single run including objective / bridge_request / scenarios.


        Use the bridge_request payload to re-POST /bridge and replay the run.'
      operationId: get-simulation-run
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/performance:
    get:
      tags:
      - Simulations
      summary: Get Simulation Performance
      description: 'Aggregate recent graded (case/suite) runs into the Simulations overview:

        overall pass rate, per-metric trend series, and per-case / per-suite rollups

        (each with its per-conversation verdicts).


        ``limit`` bounds how many recent runs are read (capped at 50). One request

        replaces the console''s former one-fetch-per-run fan-out.'
      operationId: get-simulation-performance
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: service_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Service Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 15
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationPerformanceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/runs/{run_id}/complete:
    post:
      tags:
      - Simulations
      summary: Complete Simulation Run
      operationId: complete-simulation-run
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      - name: error
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                title: Response Complete-Simulation-Run
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/sessions/{session_id}/promote:
    post:
      tags:
      - Simulations
      summary: Promote Simulation Session
      description: 'Promote a run-less (interactive playground) session into a coverage run.


        Interactive text sessions are created run-less, so ``fork`` — which requires

        a ``run_id`` — 404s on them. This creates a coverage run, binds the existing

        agent-engine session to it (``adopt-run``, a Valkey meta update — the session

        itself is not recreated), and writes the platform-api ``SimulationCoverageSession``

        record that ``get_session_metadata`` returns, unblocking fork/score.


        Idempotent: a session that already has a coverage record returns its existing

        run with ``already_bound=True``.'
      operationId: promote-simulation-session
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoteSessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/runs/{run_id}/sessions:
    post:
      tags:
      - Simulations
      summary: Create Simulation Session
      description: 'Create a simulation session within a run. Proxies to agent-engine.


        entity_id ownership: agent-engine''s _resolve_caller queries the entity

        with workspace_id scoping — a workspace-A entity_id resolves to None in

        workspace-B, so no cross-tenant data is exposed.'
      operationId: create-simulation-session
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationSessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/sessions/{session_id}/step:
    post:
      tags:
      - Simulations
      summary: Simulation Step
      description: Step a simulation session and auto-store the turn observation.
      operationId: simulation-step
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StepRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationStepResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/sessions/{session_id}/fork:
    post:
      tags:
      - Simulations
      summary: Simulation Fork
      description: Fork a session into N branches — clone + step each alternative atomically.
      operationId: simulation-fork
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForkRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Simulation-Fork
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/sessions/{session_id}/score:
    post:
      tags:
      - Simulations
      summary: Score Simulation Session
      description: ASI assigns a score to a completed simulation session.
      operationId: score-simulation-session
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScoreSessionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                title: Response Score-Simulation-Session
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/sessions:
    post:
      tags:
      - Simulations
      summary: Create Test Conversation
      description: Create a test conversation session (no coverage run required).
      operationId: create-test-conversation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationSessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
  /v1/{workspace_id}/simulations/sessions/step:
    post:
      tags:
      - Simulations
      summary: Test Conversation Step
      description: Step a test conversation (no coverage auto-store).
      operationId: test-conversation-step
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StepRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationStepResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
  /v1/{workspace_id}/simulations/sessions/recommend:
    post:
      tags:
      - Simulations
      summary: Simulation Recommend
      operationId: simulation-recommend
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecommendRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
  /v1/{workspace_id}/simulations/sessions/{session_id}:
    get:
      tags:
      - Simulations
      summary: Simulation Observe
      operationId: simulation-observe
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationSnapshotResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Simulations
      summary: Simulation Destroy
      operationId: simulation-destroy
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DestroySessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/sessions/{session_id}/intelligence:
    get:
      tags:
      - Simulations
      summary: Simulation Intelligence
      operationId: simulation-intelligence
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationIntelligenceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/simulations/services/{service_id}/graph:
    get:
      tags:
      - Simulations
      summary: Get Simulation Coverage Graph
      description: Get the B&B knowledge graph for a service — topology + observations merged.
      operationId: get-simulation-coverage-graph
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: service_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Service Id
      - name: run_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Run Id
      - name: include_turns
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Turns
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get-Simulation-Coverage-Graph
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Simulations
      summary: Delete Simulation Coverage Graph
      operationId: delete-simulation-coverage-graph
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: service_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Service Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              s

# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amigo/refs/heads/main/openapi/amigo-simulations-api-openapi.yml