Skip to main content
PUT
Python

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
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.

fields
object

The value for each field the test suite declares, keyed by field identifier: text, a number or a boolean, in the field's own type. A field the suite does not declare answers 422 scenario_field_unknown; a value of the wrong type answers 422 scenario_field_type_invalid. An empty value clears the field. Send the full record; an empty record clears every value.

Response

Scenario updated

id
string
required
name
string
required
situation
string
required
criteria
string[]
required
labels
string[]
required
parameters
object[]
required
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.

fields
object

The value this scenario carries for each field its test suite declares, keyed by field identifier. A field with no value has no key. Absent on servers that predate suite fields.

Last modified on May 19, 2026