---
title: "Edit a suite under optimistic revision control"
method: PATCH
path: "/v1/agents/{agent_id}/simulation-suites/{suite_id}"
---

# Edit a suite under optimistic revision control

`PATCH /v1/agents/{agent_id}/simulation-suites/{suite_id}`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/agents/{agent_id}/simulation-suites/{suite_id}`
- Auth: none declared

Every accepted edit appends a NEW immutable revision instead of mutating content, so a run that pinned an earlier revision keeps reading exactly what it executed. The request must carry the revision the edit is based on; a stale write returns 409 with the revision that beat it and never overwrites. Scenario personas may carry bounded interruption and intent-change rules that drive an adaptive caller, and each scenario may carry up to five semantic rubrics; a rubric is a separate evaluator call on every attempt, which is why that ceiling is low.

## Path parameters

- `agent_id` string, required
- `suite_id` string, required

## Request body

- object
  - `baseline_run_id` string: A finished run of THIS suite that later runs are compared against. Send an empty string to clear it. A run belonging to another suite, one that is still going, or one that recorded no attempts is refused with 400 -- each would make the comparison meaningless.
  - `default_snapshot_source` 'draft' | 'published'
  - `description` string
  - `name` string
  - `policy` object
  - `revision` integer, required: The revision this edit is based on.
  - `scenarios` object[]: Complete replacement scenario list for this immutable revision. An adaptive_voice scenario may include caller_environment, a version-pinned synthetic caller MICROPHONE condition with noise_level. It is distinct from the agent's outgoing audio_environment/volume; a scenario that supplies it must use adaptive_voice and supply a non-blank language. Off requires noise_level=0 and is the quiet baseline.
    - `caller_environment` CallerInputEnvironmentSelection: Simulation Lab only: a version-pinned condition mixed into the synthetic caller microphone. This is not the agent's outgoing audio_environment and never changes a production call's STT/TTS configuration.
      - `asset_version` 'v1', required: Immutable packaged asset version; it is never inferred.
      - `noise_level` integer, required: Whole-number caller-input level. Off requires 0; enabled presets require 1 through 100.
      - `preset_id` string, required: Exact catalogue id. `off` has no asset and is the quiet baseline.
  - `status` 'active' | 'archived'

## Response `200`

Suite at its new revision

## Other responses

- `400`: Missing revision or an invalid scenario contract
- `404`: Suite not found, or Simulations Lab is not enabled
- `409`: Stale revision; the response carries the revision that won

---

[API](https://skmtc.dev/skysay/apis/skysay-api.md) · [All operations](https://skmtc.dev/skysay/apis/skysay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skysay/apis/skysay-api/revisions/95b8c66f99aa?raw)