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

# Update a simulation test

> Updates the provided fields of a simulation test. `toolMocking`, when provided, replaces the tool mocking of the test as a whole.



## OpenAPI

````yaml PUT /AgentTest/simulation/{testId}
openapi: 3.0.1
info:
  title: Starleads public API documentation
  description: >
    Welcome to the Starleads Public API documentation. This API provides public
    access to Starleads services, allowing developers and growth-hackers to
    interact with campaign-related data.

    ***

    ### Base endpoint

    ```https://api.starleads.co```

    ***

    ### Errors

    The API uses standard HTTP status codes to indicate the success or failure
    of the API call. In case of failure, the body of the response will be JSON
    in the following format:

    ```

    {
      "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
      "title": "Bad Request",
      "status": 400,
      "detail": "No campaign exists with campaignId : 11111111"
    }

    ```

    The ```type``` property is a link to a general description of the error
    type.

    ***

    ### Authentification

    Authentication for the API is handled with an API key that must be provided
    as a ```X-Api-Key``` header for every request.<br>

    **API keys are supposed to be a secret that only the client and server know.
    Please remember to not share them with anyone.**<br>

    You can find your API keys when authenticated in your Starleads profile
    :<br> ![Api key menu option](../images/api-menu-option-screenshot.png)
  version: v1
  x-logo:
    url: https://api.starleads.co/images/starleads-logo.png
servers: []
security: []
tags:
  - name: Agent
    description: >-
      Manage your AI agent's prompt. These endpoints allow you to read and
      update the prompt that drives your agent's behavior during calls.
  - name: CampaignField
    description: >-
      CampaignFields enables users to specify customizable fields within their
      campaigns. These fields serve as placeholders (e.g., ```{lastname}```)
      that can be dynamically filled with corresponding data when creating
      prompts, providing flexibility in tailoring campaign content based on
      specific variables.<br>**Those are the keys of the ```databag``` field of
      the request payload to add a new ```CampaignItem``` to a campaign.**
  - name: CampaignItem
    description: Represents prospects entries related to a campaign
  - name: Consumption
    description: >-
      Track your company's credit consumption. These endpoints expose your
      current balance, usage and billing period so you can build budget
      monitoring on top of the API.
  - name: Subscription
    description: >-
      Inspect your subscription contract: the plan you are on, your subscription
      status, the features currently active and your effective limits. No
      pricing information is exposed.
  - name: AgentTest
    description: >-
      Tests of your agents: simulation tests (a simulated user talks to the
      agent and each success criterion is judged) and classification tests (the
      agent must produce the expected tag for a conversation). A test belongs to
      one agent.
  - name: AgentTestExecution
    description: >-
      Executions of agent tests: launching a set of tests, following their
      progress and cancelling them. One execution groups the runs created
      together for a list of tests, each repeated up to 5 times.
  - name: AgentTestFolder
    description: >-
      Folders grouping the tests of an agent (flat, with a name, a color and a
      markdown body).
  - name: AgentTestRun
    description: >-
      Runs of agent tests: one run is one attempt of one test inside an
      execution. Results, history and cancellation.
  - name: SimulationChat
    description: >-
      Test an agent through a text chat, exactly as it would behave in a real
      conversation (prompt, fields and connected tools included). Start a chat,
      then exchange messages with the agent.
paths:
  /AgentTest/simulation/{testId}:
    put:
      tags:
        - AgentTest
      summary: Update a simulation test
      description: >-
        Updates the provided fields of a simulation test. `toolMocking`, when
        provided, replaces the tool mocking of the test as a whole.
      operationId: UpdateSimulationTest
      parameters:
        - name: X-Api-Key
          in: header
          description: Api key to pass as a ```X-Api-Key``` request header.
          required: true
          schema:
            type: string
        - name: testId
          in: path
          description: ID of the test.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSimulationTestRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/UpdateSimulationTestRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/UpdateSimulationTestRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAgentTest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    UpdateSimulationTestRequest:
      type: object
      properties:
        name:
          type: string
          nullable: true
        scenario:
          type: string
          nullable: true
        criteria:
          type: array
          items:
            type: string
          nullable: true
        maxTurns:
          type: integer
          format: int32
          nullable: true
        conversationContext:
          type: array
          items:
            $ref: '#/components/schemas/PublicChatMessage'
          description: >-
            Messages the conversation starts from. Null leaves the stored value
            untouched; an empty list clears it.
          nullable: true
        variables:
          type: object
          additionalProperties:
            type: string
          nullable: true
        toolMocking:
          $ref: '#/components/schemas/PublicToolMocking'
      additionalProperties: false
      description: Fields to update on a simulation test (only the provided ones change)
    PublicAgentTest:
      type: object
      properties:
        id:
          type: string
          nullable: true
        kind:
          $ref: '#/components/schemas/AgentTestKind'
        agentId:
          type: string
          nullable: true
        folderId:
          type: string
          description: Folder containing the test, null at the root
          nullable: true
        name:
          type: string
          nullable: true
        lastRunId:
          type: string
          description: Most recent run of the test
          nullable: true
        lastRunStatus:
          $ref: '#/components/schemas/TestRunStatus'
        lastRunAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        scenario:
          type: string
          description: 'Simulation only: persona and intent of the simulated user'
          nullable: true
        criteria:
          type: array
          items:
            type: string
          description: 'Simulation only: success criteria, each judged independently'
          nullable: true
        maxTurns:
          type: integer
          description: 'Simulation only: maximum number of user/agent exchanges (1-30)'
          format: int32
          nullable: true
        conversationMessages:
          type: array
          items:
            $ref: '#/components/schemas/PublicChatMessage'
          description: >-
            Simulation only: messages the conversation starts from, in
            chronological order; empty when the run starts from scratch
          nullable: true
        variables:
          type: object
          additionalProperties:
            type: string
          description: 'Simulation only: values of the agent variables (name → value)'
          nullable: true
        toolMocking:
          $ref: '#/components/schemas/PublicToolMocking'
        conversationContext:
          $ref: '#/components/schemas/PublicConversationContext'
        tagExpected:
          type: string
          description: 'Classification only: expected tag'
          nullable: true
      additionalProperties: false
      description: >-
        A test of an agent. Depending on kind, either the simulation fields
        (scenario, criteria, maxTurns, variables) or the classification fields
        (conversationContext, tagExpected) are set.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    PublicChatMessage:
      type: object
      properties:
        role:
          type: string
          description: '"user" or "assistant"'
          nullable: true
        text:
          type: string
          nullable: true
        timestamp:
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
      description: One message of a conversation
    PublicToolMocking:
      type: object
      properties:
        mockedTools:
          type: array
          items:
            $ref: '#/components/schemas/PublicMockedTool'
          description: >-
            Tools to mock, targeted by their id (see the agent's connected
            tools). Each one returns its `resultTemplate` instead of being
            executed.
          nullable: true
        mockAllTools:
          type: boolean
          description: >-
            Mocks every tool connected to the agent. Tools listed in
            `mockedTools` keep their own template; the others return a default
            response telling the agent the call succeeded. Default false.
        mockCallTransfer:
          type: boolean
          description: >-
            Mocks the call transfer, so the simulation never transfers to a
            human. Independent of `mockAllTools`: a phone agent with call
            transfer enabled places a real transfer unless this is true. Default
            false.
      additionalProperties: false
      description: >-
        Which tools of the agent are mocked (not really executed) during a
        simulation. Every mock is opt-in: nothing is mocked unless asked for
        here, and `mockAllTools` does not imply `mockCallTransfer`. The
        knowledge base retrieval always runs for real.
    AgentTestKind:
      enum:
        - Simulation
        - Classification
      type: string
    TestRunStatus:
      enum:
        - Queued
        - Running
        - Passed
        - Failed
        - Error
        - Cancelled
      type: string
    PublicConversationContext:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/PublicChatMessage'
          description: Messages of the conversation, in chronological order
          nullable: true
        dataBag:
          type: object
          additionalProperties:
            type: string
          description: Variable values (name → value) available to the agent
          nullable: true
      additionalProperties: false
      description: Conversation used as input of a classification test
    PublicMockedTool:
      required:
        - toolId
      type: object
      properties:
        toolId:
          minLength: 1
          type: string
          description: ID of the tool to mock. It must be connected to the agent.
        resultTemplate:
          type: string
          description: >-
            Result handed back to the agent instead of the real one. Supports
            `{name}` placeholders resolved against the call parameters and the
            conversation variables. Empty: a default response telling the agent
            the call succeeded.
          nullable: true
        delaySeconds:
          maximum: 60
          minimum: 0
          type: number
          description: Simulated execution time, in seconds (0 to 60). Default 0.
          format: double
      additionalProperties: false

````