> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate simulation resources

> Works out what to test for an existing agent, then creates the customer flows, metrics and checks to simulate it, and a run plan that runs them. It does not create or change the agent. It also reads the agent's recent production calls and open issues. Run it again and it builds on what earlier generations made, adding only what changed; when nothing has, it finishes straight away and says so. Runs in the background: watch the `simulation.resource_generation.completed` webhook, or poll `GET /v1/simulation/generations/resources/{generationId}`. Takes one agent for now. Refused while another generation for the agent is running. Needs the 'simulation:create' and 'metric:create' permissions. Exploration also needs 'simulation:run', and is turned off for keys without it unless explore.enabled is set.



## OpenAPI

````yaml /api-reference/openapi.documented.json post /v1/simulation/generations/resources
openapi: 3.1.0
info:
  title: Roark Analytics 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: Health
    x-displayName: Health
  - name: Authentication
    x-displayName: Current credential
  - name: Project API Key
    x-displayName: Project API keys
  - name: Personal API Key
    x-displayName: Personal API keys
  - name: Agent
    x-displayName: Agents
  - name: Agent Endpoint
    x-displayName: Endpoints
  - name: Tool
    x-displayName: Tools
  - name: Autoimprove
    x-displayName: Autoimprove
  - name: Generate Simulation Resources
    x-displayName: Generate resources
  - name: Customer Flow
    x-displayName: Customer flows
  - name: Customer Flow Folder
    x-displayName: Customer flow folders
  - name: Simulation Persona
    x-displayName: Personas
  - name: Simulation Environment
    x-displayName: Environments
  - name: Simulation Template
    x-displayName: Templates
  - name: Simulation Run Plan
    x-displayName: Plans
  - name: Simulation Run
    x-displayName: Runs
  - name: Simulation Tool Mock
    x-displayName: Tool mocks and fixtures
  - name: Metric
    x-displayName: Definitions
  - name: Metric Variant
    x-displayName: Variants
  - name: Metric Policy
    x-displayName: Policies
  - name: Metric Collection Job
    x-displayName: Collection jobs
  - name: Call
    x-displayName: Calls
  - name: Chat
    x-displayName: Chats
  - name: Customer
    x-displayName: Customers
  - name: Issue
    x-displayName: Issues
  - name: Analytics
    x-displayName: Analytics
  - name: Dashboard
    x-displayName: Dashboards & widgets
  - name: Live Report
    x-displayName: Live reports
  - name: Agent Connection
    x-displayName: Agent platforms
  - name: Calendar Connection
    x-displayName: Calendars
  - name: MCP Server Connection
    x-displayName: MCP servers
  - name: Knowledge Base
    x-displayName: Knowledge bases
  - name: HTTP Request Definition
    x-displayName: HTTP request definitions
  - name: Webhook
    x-displayName: Webhooks
  - name: Config
    x-displayName: Config as code
  - name: Organization Project
    x-displayName: Projects
  - name: Organization Project Member
    x-displayName: Project members
  - name: Usage
    x-displayName: Usage
  - name: Benchmark
    x-displayName: Model benchmarks
paths:
  /v1/simulation/generations/resources:
    post:
      tags:
        - Generate Simulation Resources
      summary: Generate simulation resources
      description: >-
        Works out what to test for an existing agent, then creates the customer
        flows, metrics and checks to simulate it, and a run plan that runs them.
        It does not create or change the agent. It also reads the agent's recent
        production calls and open issues. Run it again and it builds on what
        earlier generations made, adding only what changed; when nothing has, it
        finishes straight away and says so. Runs in the background: watch the
        `simulation.resource_generation.completed` webhook, or poll `GET
        /v1/simulation/generations/resources/{generationId}`. Takes one agent
        for now. Refused while another generation for the agent is running.
        Needs the 'simulation:create' and 'metric:create' permissions.
        Exploration also needs 'simulation:run', and is turned off for keys
        without it unless explore.enabled is set.
      operationId: postV1SimulationGenerationsResources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateSimulationResourcesInput'
      responses:
        '202':
          description: The generation has started
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SimulationResourceGeneration'
                required:
                  - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Conflict error
              example:
                type: conflict
                code: resource_in_use
                message: The resource is in use and cannot be deleted
          description: Conflict
        '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
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Roark from '@roarkanalytics/sdk';

            const client = new Roark({
              bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted
            });

            const response = await client.simulation.generateResources({
              agentIds: ['182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'],
            });

            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from roark_analytics import Roark

            client = Roark(
                bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted
            )
            response = client.simulation.generate_resources(
                agent_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
            )
            print(response.data)
components:
  schemas:
    GenerateSimulationResourcesInput:
      type: object
      properties:
        agentIds:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          maxItems: 1
          description: >-
            The agents to generate simulation resources for. One agent per
            generation for now.
        industry:
          type: string
          enum:
            - HEALTHCARE
            - FINANCIAL_SERVICES
            - INSURANCE
            - DEBT_COLLECTION
            - RETAIL
            - TRAVEL_AND_HOSPITALITY
            - TELECOMMUNICATIONS
            - TECHNOLOGY
            - PUBLIC_SECTOR
            - UTILITIES
            - LOGISTICS
            - AUTOMOTIVE
            - HOME_SERVICES
            - RESTAURANTS
            - EDUCATION
            - OTHER
          description: The industry the agent serves.
        websiteUrl:
          type: string
          format: uri
          description: A page Roark reads to learn about the business.
        testingInstructions:
          type: string
          maxLength: 50000
          description: >-
            What you want tested, in your own words. Each scenario you describe
            becomes a flow.
        capabilities:
          type: array
          items:
            type: string
            enum:
              - APPOINTMENT_BOOKING
              - FAQ
              - IDENTITY_VERIFICATION
              - ACCOUNT_MANAGEMENT
              - BILLING_AND_PAYMENTS
              - ORDER_MANAGEMENT
              - TROUBLESHOOTING
              - CALL_ROUTING
              - LEAD_QUALIFICATION
              - COLLECTIONS
              - OUTBOUND_CALLING
          description: >-
            The capabilities to test. Omit to let Roark work them out from the
            agent.
        agentEndpointId:
          type: string
          format: uuid
          description: >-
            The endpoint the run plan calls. Defaults to the agent's newest
            endpoint.
        explore:
          $ref: '#/components/schemas/SimulationResourceGenerationExploreInput'
      required:
        - agentIds
      description: Input for generating simulation resources for agents
    SimulationResourceGeneration:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Simulation resource generation ID
        agentIds:
          type: array
          items:
            type: string
            format: uuid
          description: The agents the inputs were generated for
        status:
          type: string
          enum:
            - PENDING
            - RUNNING
            - NEEDS_INPUT
            - COMPLETED
            - FAILED
            - CANCELLED
          description: >-
            PENDING, RUNNING, NEEDS_INPUT (waiting on a question; it goes ahead
            with the default if nobody answers), COMPLETED, FAILED or CANCELLED
        layers:
          type: array
          items:
            $ref: '#/components/schemas/SimulationResourceGenerationLayer'
          description: The checklist the generation works through
        question:
          $ref: '#/components/schemas/SimulationResourceGenerationQuestion'
        activity:
          type: array
          items:
            $ref: '#/components/schemas/SimulationResourceGenerationActivity'
          description: What the generation did and said, in order
        industry:
          type:
            - string
            - 'null'
          enum:
            - HEALTHCARE
            - FINANCIAL_SERVICES
            - INSURANCE
            - DEBT_COLLECTION
            - RETAIL
            - TRAVEL_AND_HOSPITALITY
            - TELECOMMUNICATIONS
            - TECHNOLOGY
            - PUBLIC_SECTOR
            - UTILITIES
            - LOGISTICS
            - AUTOMOTIVE
            - HOME_SERVICES
            - RESTAURANTS
            - EDUCATION
            - OTHER
        capabilities:
          type: array
          items:
            type: string
            enum:
              - APPOINTMENT_BOOKING
              - FAQ
              - IDENTITY_VERIFICATION
              - ACCOUNT_MANAGEMENT
              - BILLING_AND_PAYMENTS
              - ORDER_MANAGEMENT
              - TROUBLESHOOTING
              - CALL_ROUTING
              - LEAD_QUALIFICATION
              - COLLECTIONS
              - OUTBOUND_CALLING
        runPlanId:
          type:
            - string
            - 'null'
          format: uuid
          description: The run plan to start once the generation completes
        explore:
          type: object
          properties:
            enabled:
              type: boolean
            maxConversations:
              type: integer
            maxConversationMinutes:
              type: integer
            conversationsUsed:
              type: integer
          required:
            - enabled
            - maxConversations
            - maxConversationMinutes
            - conversationsUsed
        testDataNeeded:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              reason:
                type: string
              callId:
                type:
                  - string
                  - 'null'
                format: uuid
            required:
              - label
              - reason
              - callId
          description: Test data the agent asked for that Roark did not have
        errorMessage:
          type:
            - string
            - 'null'
        items:
          type: array
          items:
            $ref: '#/components/schemas/SimulationResourceGenerationItem'
        createdAt:
          type: string
        completedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - agentIds
        - status
        - layers
        - question
        - activity
        - industry
        - capabilities
        - runPlanId
        - explore
        - testDataNeeded
        - errorMessage
        - items
        - createdAt
        - completedAt
      description: >-
        The simulation resources Roark generated for agents: the flows, metrics,
        checks and run plan, and why
    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
    SimulationResourceGenerationExploreInput:
      type: object
      properties:
        enabled:
          type: boolean
          default: true
          description: >-
            Whether Roark calls the agent to discover what it does before
            finishing the generation. Exploration calls are billed.
        maxConversations:
          type: integer
          minimum: 1
          maximum: 25
          default: 10
          description: The most exploration calls Roark places.
        maxConversationMinutes:
          type: integer
          minimum: 1
          maximum: 15
          default: 5
          description: The longest a single exploration call may last, in minutes.
      description: Exploration settings
    SimulationResourceGenerationLayer:
      type: object
      properties:
        layer:
          type: string
          enum:
            - CORE
            - INDUSTRY
            - CAPABILITY
            - AGENT_CONTEXT
            - EXPLORATION
            - CUSTOMER_INSTRUCTIONS
            - PRODUCTION_CALLS
        status:
          type: string
          enum:
            - COVERED
            - SKIPPED
            - OPEN
            - NOT_APPLICABLE
          description: >-
            COVERED: tests exist for it, or are added when the generation
            finishes. SKIPPED: the generation could not test it and said why.
            OPEN: not covered yet; the generation does not finish while a layer
            is open. NOT_APPLICABLE: nothing to test it from.
        summary:
          type: string
      required:
        - layer
        - status
        - summary
      description: Where one part of testing the agent stands
    SimulationResourceGenerationQuestion:
      type:
        - object
        - 'null'
      properties:
        question:
          type: string
        options:
          type: array
          items:
            type: string
        defaultOption:
          type: string
      required:
        - question
        - options
        - defaultOption
      description: The question the generation is waiting on, while NEEDS_INPUT
    SimulationResourceGenerationActivity:
      type: object
      properties:
        kind:
          type: string
          enum:
            - STATUS
            - REASONING
            - ACTION
            - GUIDANCE
            - QUESTION
            - ANSWER
            - EXPLORATION
            - ERROR
          description: >-
            STATUS, REASONING, ACTION, GUIDANCE, QUESTION, ANSWER, EXPLORATION
            or ERROR
        text:
          type: string
        createdAt:
          type: string
      required:
        - kind
        - text
        - createdAt
      description: One thing the generation did or said, in order
    SimulationResourceGenerationItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        layer:
          type: string
          enum:
            - CORE
            - INDUSTRY
            - CAPABILITY
            - AGENT_CONTEXT
            - EXPLORATION
            - CUSTOMER_INSTRUCTIONS
            - PRODUCTION_CALLS
          description: >-
            Why it exists: CORE (every agent), INDUSTRY, CAPABILITY,
            AGENT_CONTEXT (your prompt or website), EXPLORATION or
            CUSTOMER_INSTRUCTIONS
        kind:
          type: string
          enum:
            - FLOW
            - METRIC
            - CHECK
            - LAYER
          description: A flow, a metric, or a pass or fail check
        action:
          type: string
          enum:
            - CREATED
            - SKIPPED
          description: CREATED, or SKIPPED with the reason
        resourceId:
          type:
            - string
            - 'null'
          format: uuid
          description: The flow or metric it created
        label:
          type: string
        capability:
          type:
            - string
            - 'null'
          enum:
            - APPOINTMENT_BOOKING
            - FAQ
            - IDENTITY_VERIFICATION
            - ACCOUNT_MANAGEMENT
            - BILLING_AND_PAYMENTS
            - ORDER_MANAGEMENT
            - TROUBLESHOOTING
            - CALL_ROUTING
            - LEAD_QUALIFICATION
            - COLLECTIONS
            - OUTBOUND_CALLING
        source:
          $ref: '#/components/schemas/SimulationResourceGenerationItemSource'
        reason:
          type: string
        origin:
          type:
            - string
            - 'null'
          enum:
            - DISCOVERED
            - INFERRED
          description: >-
            Exploration only: DISCOVERED on a call, or INFERRED from a path the
            agent offered
      required:
        - id
        - layer
        - kind
        - action
        - resourceId
        - label
        - capability
        - source
        - reason
        - origin
      description: Something the generation created or chose to leave out, and why
    SimulationResourceGenerationItemSource:
      type: object
      properties:
        type:
          type: string
          enum:
            - CATALOGUE
            - PROMPT
            - DESCRIPTION
            - WEBSITE
            - EXPLORATION_CALL
            - INSTRUCTIONS
            - PRODUCTION_CALL
        url:
          type:
            - string
            - 'null'
          description: The page it came from, for website sources
        callId:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The call it came from: an exploration call Roark placed, or one of
            the agent’s production calls
        offsetMs:
          type:
            - integer
            - 'null'
          description: Where in the call
        quote:
          type:
            - string
            - 'null'
          description: The words in the source that led to it
      required:
        - type
        - url
        - callId
        - offsetMs
        - quote
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.