openapi: 3.2.0
info:
  title: PLATFORM Simulation Suites API
  version: 1.0.0
servers:
- url: https://api.synthflow.ai/v2
  description: Global
- url: https://api.us.synthflow.ai/v2
  description: United States
- url: https://api.eu.synthflow.ai/v2
  description: European Union
tags:
- name: Simulation Suites
paths:
  /simulation_suites:
    post:
      operationId: create-simulation-suite
      summary: Create a simulation suite
      description: Create a new simulation suite attached to a specific agent. The suite can only be executed on the agent specified by model_id.
      tags:
      - Simulation Suites
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-simulation-suite_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Create-simulation-suiteRequestBadRequestError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulationSuiteCreateIn'
    get:
      operationId: list-simulation-suites
      summary: List simulation suites
      description: List simulation suites with pagination and optional filtering.
      tags:
      - Simulation Suites
      parameters:
      - name: page_number
        in: query
        description: Page number.
        required: false
        schema:
          type: integer
          default: 1
      - name: page_size
        in: query
        description: Number of items per page.
        required: false
        schema:
          type: integer
          default: 10
      - name: search
        in: query
        description: Search term for simulation suite names.
        required: false
        schema:
          type: string
      - name: model_ids
        in: query
        description: Filter by list of model IDs.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: start_date
        in: query
        description: Filter by created_at >= start_date (ISO format).
        required: false
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        description: Filter by created_at <= end_date (ISO format).
        required: false
        schema:
          type: string
          format: date-time
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-simulation-suites_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List-simulation-suitesRequestBadRequestError'
  /simulation_suites/{suite_id}:
    get:
      operationId: get-simulation-suite
      summary: Get a simulation suite
      description: Retrieve a simulation suite by ID.
      tags:
      - Simulation Suites
      parameters:
      - name: suite_id
        in: path
        description: Simulation suite ID.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-simulation-suite_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-simulation-suiteRequestBadRequestError'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-simulation-suiteRequestNotFoundError'
    put:
      operationId: update-simulation-suite
      summary: Update a simulation suite
      description: Update an existing simulation suite.
      tags:
      - Simulation Suites
      parameters:
      - name: suite_id
        in: path
        description: Simulation suite ID.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-simulation-suite_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Update-simulation-suiteRequestBadRequestError'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Update-simulation-suiteRequestNotFoundError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulationSuiteUpdateIn'
    delete:
      operationId: delete-simulation-suite
      summary: Delete a simulation suite
      description: Delete a simulation suite by ID.
      tags:
      - Simulation Suites
      parameters:
      - name: suite_id
        in: path
        description: Simulation suite ID.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '204':
          description: '204'
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delete-simulation-suiteRequestBadRequestError'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delete-simulation-suiteRequestNotFoundError'
  /simulation_suites/{suite_id}/execute:
    post:
      operationId: execute-simulation-suite
      summary: Execute a simulation suite
      description: Execute all test cases in a suite. The suite runs on the agent it was created for (determined by the suite's model_id).
      tags:
      - Simulation Suites
      parameters:
      - name: suite_id
        in: path
        description: Simulation suite ID.
        required: true
        schema:
          type: string
      - name: target_agent_id
        in: query
        description: Target agent ID. Must match the suite's model_id.
        required: true
        schema:
          type: string
      - name: max_turns
        in: query
        description: Maximum number of turns per simulation.
        required: false
        schema:
          type: integer
          default: 20
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/execute-simulation-suite_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execute-simulation-suiteRequestBadRequestError'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execute-simulation-suiteRequestNotFoundError'
components:
  schemas:
    get-simulation-suite_Response_200:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/status'
        response:
          $ref: '#/components/schemas/SimulationSuiteReadOut'
      title: get-simulation-suite_Response_200
    list-simulation-suites_Response_200:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/status'
        response:
          $ref: '#/components/schemas/PaginatedSimulationSuitesList'
      title: list-simulation-suites_Response_200
    SimulationSuiteListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Suite ID
        name:
          type: string
          description: Name of the simulation suite
        model_id:
          type: string
          description: Agent model ID this suite is for
        workspace_id:
          type: string
          description: Workspace ID this suite belongs to
        language:
          type: string
          default: en-US
          description: Language locale for the persona agent and test cases (e.g., 'en-US', 'es-ES', 'fr-FR')
        created_at:
          type: string
          format: date-time
          description: When the suite was created
        updated_at:
          type: string
          format: date-time
          description: When the suite was last updated
        case_summaries:
          type: array
          items:
            $ref: '#/components/schemas/SimulationCaseSummary'
          description: Summary of cases in this suite
        agent:
          $ref: '#/components/schemas/AgentListItem'
          description: Agent information associated with this suite
      required:
      - id
      - name
      - model_id
      - workspace_id
      title: SimulationSuiteListItem
    SimulationCaseReadOutCallSuccessType:
      type: string
      enum:
      - all
      - any
      title: SimulationCaseReadOutCallSuccessType
    Execute-simulation-suiteRequestBadRequestError:
      type: object
      properties: {}
      title: Execute-simulation-suiteRequestBadRequestError
    Execute-simulation-suiteRequestNotFoundError:
      type: object
      properties: {}
      title: Execute-simulation-suiteRequestNotFoundError
    execute-simulation-suite_Response_200:
      type: object
      properties:
        session_id:
          type: string
          format: uuid
        suite_id:
          type: string
          format: uuid
        suite_name:
          type: string
        total_cases:
          type: integer
        status:
          type: string
      title: execute-simulation-suite_Response_200
    SimulationSuiteUpdateIn:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: New name for the simulation suite
        model_id:
          type:
          - string
          - 'null'
          description: New agent model ID for the suite
      title: SimulationSuiteUpdateIn
    PaginatedSimulationSuitesList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SimulationSuiteListItem'
          description: List of simulation suites
        total:
          type: integer
          description: Total number of simulation suites
        page_number:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of items per page
      required:
      - items
      - total
      - page_number
      - page_size
      title: PaginatedSimulationSuitesList
    SimulationCaseSummary:
      type: object
      properties:
        simulation_case_id:
          type: string
          format: uuid
          description: Unique identifier for the simulation case
        name:
          type: string
          description: Name of the simulation case
      required:
      - simulation_case_id
      - name
      title: SimulationCaseSummary
    SimulationCaseReadOut:
      type: object
      properties:
        simulation_case_id:
          type: string
          format: uuid
        workspace_id:
          type: string
        suite_id:
          type:
          - string
          - 'null'
          format: uuid
          description: ID of the simulation suite this case belongs to.
        name:
          type: string
        prompt:
          type: string
        type:
          $ref: '#/components/schemas/SimulationCaseReadOutType'
        success_criteria:
          type: array
          items:
            type: string
        call_success_type:
          $ref: '#/components/schemas/SimulationCaseReadOutCallSuccessType'
        base_agent:
          oneOf:
          - $ref: '#/components/schemas/SimulationCaseReadOutBaseAgent'
          - type: 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      description: Simulation case details.
      title: SimulationCaseReadOut
    Delete-simulation-suiteRequestNotFoundError:
      type: object
      properties: {}
      title: Delete-simulation-suiteRequestNotFoundError
    SimulationCaseReadOutType:
      type: string
      enum:
      - custom
      - agent_based
      title: SimulationCaseReadOutType
    Delete-simulation-suiteRequestBadRequestError:
      type: object
      properties: {}
      title: Delete-simulation-suiteRequestBadRequestError
    create-simulation-suite_Response_200:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/status'
        response:
          $ref: '#/components/schemas/SimulationSuiteReadOut'
      title: create-simulation-suite_Response_200
    Get-simulation-suiteRequestBadRequestError:
      type: object
      properties: {}
      title: Get-simulation-suiteRequestBadRequestError
    SimulationSuiteCreateIn:
      type: object
      properties:
        name:
          type: string
          description: Name of the simulation suite
        model_id:
          type: string
          description: Agent model ID this suite is for. The suite can only run on this specific agent.
        language:
          type: string
          default: en-US
          description: Language locale for the persona agent and test cases (e.g., 'en-US', 'es-ES', 'fr-FR'). Must be a valid locale code. Note that 'multi' is not allowed for simulation suites.
      required:
      - name
      - model_id
      title: SimulationSuiteCreateIn
    Update-simulation-suiteRequestNotFoundError:
      type: object
      properties: {}
      title: Update-simulation-suiteRequestNotFoundError
    Get-simulation-suiteRequestNotFoundError:
      type: object
      properties: {}
      title: Get-simulation-suiteRequestNotFoundError
    List-simulation-suitesRequestBadRequestError:
      type: object
      properties: {}
      title: List-simulation-suitesRequestBadRequestError
    update-simulation-suite_Response_200:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/status'
        response:
          $ref: '#/components/schemas/SimulationSuiteReadOut'
      title: update-simulation-suite_Response_200
    SimulationCaseReadOutBaseAgent:
      type: object
      properties:
        model_id:
          type: string
        agent_name:
          type: string
        agent_type:
          type: string
        voice_engine_type:
          type: string
        phone_number:
          type:
          - string
          - 'null'
        updated_at:
          type: string
          format: date-time
        image_url:
          type:
          - string
          - 'null'
      title: SimulationCaseReadOutBaseAgent
    AgentListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        avatar:
          type:
          - string
          - 'null'
      title: AgentListItem
    status:
      type: string
      description: Whether the request was successful.
      title: status
    Create-simulation-suiteRequestBadRequestError:
      type: object
      properties: {}
      title: Create-simulation-suiteRequestBadRequestError
    SimulationSuiteReadOut:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the simulation suite
        name:
          type: string
          description: Name of the simulation suite
        model_id:
          type: string
          description: Agent model ID this suite is for
        workspace_id:
          type: string
          description: Workspace ID this suite belongs to
        language:
          type: string
          default: en-US
          description: Language locale for the persona agent and test cases (e.g., 'en-US', 'es-ES', 'fr-FR')
        cases:
          type: array
          items:
            $ref: '#/components/schemas/SimulationCaseReadOut'
          description: Test cases included in this suite
        agent:
          $ref: '#/components/schemas/AgentListItem'
          description: Agent information associated with this suite
        created_at:
          type: string
          format: date-time
          description: When the suite was created
        updated_at:
          type: string
          format: date-time
          description: When the suite was last updated
      title: SimulationSuiteReadOut
    Update-simulation-suiteRequestBadRequestError:
      type: object
      properties: {}
      title: Update-simulation-suiteRequestBadRequestError
  securitySchemes:
    sec0:
      type: http
      scheme: bearer