Roark Simulation Template API

openapi: 3.2.0
info:
  title: Roark Analytics Simulation Template API
  description: The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform.
  version: 1.0.0
servers:
- description: Production
  url: https://api.roark.ai
security:
- Bearer: []
tags:
- name: Simulation Template
paths:
  /v1/simulation/template:
    get:
      responses:
        '200':
          description: The built-in simulation templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSimulationTemplatesResponse'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: getV1SimulationTemplate
      tags:
      - Simulation Template
      summary: List simulation templates
      description: 'Returns the built-in simulation templates, each resolved against this project: the metric and

        check definitions it collects, and the flows it runs with the variants it covers.


        A template is a preset rather than a stored object, so building a run from one produces an

        ordinary run plan you own and can edit afterwards. Pass a `slug` as `template` to

        POST /v1/simulation/run.


        Every entry is complete, so there is no per-template endpoint to follow up with, and the list

        is a fixed catalogue rather than a paginated one. Only templates a request can actually run

        are listed.'
components:
  schemas:
    SimulationTemplateMetricRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Metric definition ID
        slug:
          type: string
          description: Stable metric slug, e.g. "response_time"
          example: response_time
      required:
      - id
      - slug
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
          - validation
          - authentication
          - forbidden
          - not_found
          - conflict
          - payment_required
          - rate_limit
          - internal
          description: The error type category
          examples:
          - validation
          - authentication
        code:
          type: string
          description: Machine-readable error code identifier
          examples:
          - invalid_parameter
          - missing_required_field
          - unauthorized
        message:
          type: string
          description: Human-readable error message
          examples:
          - The request was invalid
          - Authentication required
        param:
          type: string
          description: The parameter that caused the error (if applicable)
          examples:
          - email
          - user_id
        details:
          description: Additional error context information
      required:
      - type
      - code
      - message
    GetSimulationTemplatesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SimulationTemplate'
      required:
      - data
      description: The built-in simulation templates.
    SimulationTemplate:
      type: object
      properties:
        slug:
          type: string
          description: Stable identifier. Name this in a run request.
          example: health-check
        title:
          type: string
          description: Display name
          example: Health check
        description:
          type: string
          description: What this template tests
        category:
          type: string
          description: Grouping used in the dashboard library
          example: Performance
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/SimulationTemplateMetricRef'
          description: The metrics this template collects, resolved to this project's definitions.
        thresholds:
          type: array
          items:
            $ref: '#/components/schemas/SimulationTemplateMetricRef'
          description: The Pass/Fail checks this template attaches alongside its metrics.
        flows:
          type: array
          items:
            $ref: '#/components/schemas/SimulationTemplateFlow'
          description: 'The flows this template runs, and which of their ways of running it covers.


            Empty means the template presets only what to measure, and a run has to say what to measure it

            on: pass `flows` to POST /v1/simulation/run. When it is not empty you can still pass `flows` to

            narrow it, naming a subset of the ids listed here.'
        includeFlowMetrics:
          type: boolean
          description: Whether runs from this template also collect each attached flow's own metrics, on top of the template's set.
        defaultMaxSimulationDurationSeconds:
          type: integer
          description: The per-simulation cap a run from this template uses unless the request sets its own.
          example: 60
        sweep:
          oneOf:
          - $ref: '#/components/schemas/SimulationTemplateSweep'
          - type: 'null'
          description: 'Set when this template is a property sweep: it runs ONE flow once per value of a single

            caller or environment property, and the report compares the values against `baseline`.


            This is what decides the size of the run. A sweep attaches the flow once per entry in

            `values`, so a plan built from it costs `values.length` times the calls a normal template

            would, before iterations. Read it before creating a plan you have to pay for.


            `null` for every other template.'
        defaultEndCallReasons:
          type: array
          items:
            type: string
          description: 'The end-call conditions a run from this template uses unless the request sets its own.


            Empty for templates whose calls end when the agent says goodbye. Non-empty where the template

            runs scripted flows that finish on a verdict: the simulated caller hangs up on an end-call

            phrase or one of these, so a run that discards them would stay on the line until the duration

            cap.'
          example: []
      required:
      - slug
      - title
      - description
      - category
      - metrics
      - thresholds
      - flows
      - includeFlowMetrics
      - defaultMaxSimulationDurationSeconds
      - sweep
      - defaultEndCallReasons
      description: 'A built-in simulation template, resolved against this project: what it measures and what it runs.'
      example:
        slug: red-teaming
        title: Red teaming
        description: Adversarial probing. Tests refusals, jailbreak resistance, and whether the agent’s policy holds.
        category: Safety
        metrics:
        - id: 9c1e2f3a-4b5c-4d6e-8f70-1a2b3c4d5e6f
          slug: compliance_prompt_injection_resistance
        thresholds:
        - id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
          slug: compliance_prompt_injection_resistance_check
        flows:
        - id: 550e8400-e29b-41d4-a716-446655440000
          title: Prompt injection
          slug: sf-prompt-injection
          happyPath:
            title: Direct attempt
          edgeCases:
          - id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
            title: Encoded payload
            slug: data-embedded-injection
        includeFlowMetrics: false
        sweep: null
        defaultMaxSimulationDurationSeconds: 900
        defaultEndCallReasons: []
    SimulationTemplateEdgeCase:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Customer flow variant ID
        title:
          type: string
          description: What this way of running the flow is called
        slug:
          type:
          - string
          - 'null'
          description: 'The stable slug of a Roark-curated edge case, null for one of your own.


            Prefer this over `id` in a run you keep in version control. A curated edge case is a global

            row, so its id differs between deployments, and renaming one replaces the row and its id

            outright. The slug survives both.'
          example: data-embedded-injection
      required:
      - id
      - title
      - slug
    SimulationTemplateFlow:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Customer flow ID
        title:
          type: string
          description: Flow title
        slug:
          type:
          - string
          - 'null'
          description: 'The stable slug of a Roark-curated flow, null for one of your own.


            Prefer this over `id` when you are storing a run in version control: a curated flow is a

            global row, so its id is the same for every project but differs between deployments, while

            the slug is stable wherever the flow exists. Both are accepted by a run request.'
          example: sf-prompt-injection
        happyPath:
          type:
          - object
          - 'null'
          properties:
            title:
              type: string
          required:
          - title
          description: The flow's default way of running, when this template covers it. Null when it does not, or the flow has none.
        edgeCases:
          type: array
          items:
            $ref: '#/components/schemas/SimulationTemplateEdgeCase'
          description: The other ways of running this flow that this template covers.
      required:
      - id
      - title
      - slug
      - happyPath
      - edgeCases
    SimulationTemplateSweep:
      type: object
      properties:
        property:
          type: string
          enum:
          - ACCENT
          - AGE
          - BACKGROUND_NOISE
          - BACKGROUND_NOISE_VOLUME
          - BASE_EMOTION
          - CONFIRMATION_STYLE
          - GENDER
          - INTENT_CLARITY
          - LANGUAGE
          - INTERRUPTION
          - MEMORY_RELIABILITY
          - RESPONSE_TIMING
          - SPEECH_CLARITY
          - SPEECH_PACE
          description: The property this template varies across the flow it runs.
          example: BACKGROUND_NOISE
        baseline:
          type:
          - string
          - 'null'
          description: 'The reference value, shown first in the results, resolved to what a plan built from this

            template will actually record. `null` when the property has no obvious norm. It does not

            change the verdict: each value is compared with every other value combined.'
          example: NONE
        values:
          type: array
          items:
            type: string
          description: Every value the template sweeps, in the order the plan attaches them.
      required:
      - property
      - baseline
      - values
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT