Update an existing scenario

Update an existing scenario

PATCH /api/scenarios/{id}

Python

Python

import requests

url = "https://app.langwatch.ai/api/scenarios/{id}"

payload = { "name": "<string>" }
headers = {
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

200

{
  "id": "<string>",
  "name": "<string>",
  "situation": "<string>",
  "criteria": [
    "<string>"
  ],
  "labels": [
    "<string>"
  ],
  "parameters": [
    {
      "name": "<string>",
      "description": "<string>",
      "defaultValue": "<string>",
      "secret": true
    }
  ],
  "platformUrl": "<string>",
  "simulatorModel": "<string>",
  "judgeModel": "<string>",
  "maxTurns": 123,
  "minTurns": 123,
  "testSuiteId": "<string>"
}

Authorizations

X-Auth-Token · string · header · required

Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI.

Path Parameters

id · string · required

Body

application/json

name · string

Minimum string length: 1

situation · string

criteria · string[]

labels · string[]

parameters · object[]

The parameters this scenario declares by name, each with an optional description and default. A run supplies values for these names, readable from the scenario's own text as params.NAME. A parameter marked secret carries no default: its value is supplied per run, encrypted, delivered to the target as secrets.NAME, and never readable from the scenario's own text.

Maximum array length: 20

Show child attributes

simulatorModel · string | null

Model for the simulated user, e.g. openai/gpt-5-mini. Null uses the project default.

Maximum string length: 200

Pattern: ^[a-zA-Z0-9_-]+(?:\/[^\s/]+)+$

judgeModel · string | null

Model for the judge, e.g. openai/gpt-5-mini. Null uses the project default.

Maximum string length: 200

Pattern: ^[a-zA-Z0-9_-]+(?:\/[^\s/]+)+$

maxTurns · integer | null

Maximum conversation turns for a run of this scenario. Null uses the default.

Required range: 1 <= x <= 100

minTurns · integer | null

Minimum conversation turns before the judge may end the run. Null uses the default.

Required range: 0 <= x <= 100

testSuiteId · string | null

The test suite to file this scenario in. It must name a non-archived test suite of the same project. null files the scenario into the project's Default test suite.

Response

200

application/json

Scenario updated

id · string · required

name · string · required

situation · string · required

criteria · string[] · required

labels · string[] · required

parameters · object[] · required

Show child attributes

platformUrl · string<uri> · required

simulatorModel · string | null

The model that plays the user, or null for the project default. Absent on servers that predate model overrides on this family.

judgeModel · string | null

The model that judges the run, or null for the project default. Absent on servers that predate model overrides on this family.

maxTurns · integer | null

The most conversation turns a run of this scenario takes, or null for the default. Absent on servers that predate turn limits on this family.

minTurns · integer | null

The fewest conversation turns before the judge may end a run, or null for the default. Absent on servers that predate turn limits on this family.

testSuiteId · string | null

The test suite this scenario is filed in, or null when unfiled. Absent on servers that predate test suites.