Skip to main content

Runtime Parameters

Every prompt version can carry a parameters object: arbitrary JSON that is versioned, tagged, and fetched together with the prompt itself. Use it for application settings that should change in lockstep with the prompt — search iteration limits, confidence thresholds, structured output schemas, metadata field lists, feature switches.
Available since Python SDK 0.26.0 and TypeScript SDK 0.33.0 (reading prompt.parameters works from Python SDK 0.25.0; writing via create/update requires 0.26.0). Changing parameters creates a new prompt version, just like changing the prompt text.

Why

Prompts rarely live alone. The code around them has knobs — how many retrieval rounds to run, what score counts as confident, which fields to extract. When those knobs are hardcoded, a prompt rollback doesn’t roll them back. Storing them in parameters means one versioned unit: deploy, tag, and revert prompt + settings together.

Shape

parameters is an object with arbitrary JSON values (nested objects and arrays included). It defaults to {}. LangWatch does not interpret its contents — your application owns the schema.

Reading parameters

Python SDK

TypeScript SDK

REST API

Writing parameters

Python SDK

TypeScript SDK

REST API

Versioning behavior

  • Updating parameters (even with no other change) creates a new prompt version with its own versionId.
  • Restoring an older version restores that version’s parameters too.
  • Tags (production, staging, custom) resolve to a version, so fetching by tag always returns the matching parameters.
  • Explicit updates (PUT, SDK update) always create a new version, even if the content is unchanged.
  • The sync endpoint (POST /api/prompts/{id}/sync, used by the CLI) compares content key-order independently — re-syncing the same parameters with keys in a different order reports up_to_date and does not create a new version.

In the UI

In the prompt editor, the collapsible Config section lets you edit the parameters JSON for a draft, and the version history shows a read-only Config tab per version.