Skip to main content
Per-run prompt overrides let you pass main_prompt directly when creating a run. Use this when your system owns prompt versioning and wants a run to execute a specific prompt version without updating the workflow’s stored prompt.

​
Why this exists

Normally, a run executes the workflow’s current main_prompt. That works well when the workflow itself is the source of truth, but it can create races if an external workflow builder stores prompt versions separately:
  • run A should execute prompt v3
  • run B should execute prompt v4
  • both runs use the same workflow
  • patching the workflow prompt before each run would mutate shared state
With a per-run override, each run carries its own prompt text. Concurrent runs can use different prompt versions without racing on the workflow record.

​
How it works

POST /v1/runs accepts an optional main_prompt field:
  • If main_prompt is provided, that run executes the supplied prompt text.
  • If main_prompt is omitted or null, the run falls back to the workflow’s stored main_prompt.
  • The workflow’s stored prompt is not changed.
  • The run response includes main_prompt; null means the run uses the workflow prompt fallback.
Cyberdesk does not store prompt version history for you. Store version history and “latest vs pinned” logic in your system, then send the resolved prompt text when creating a run.

​
Example: pinned prompt version

const { data: run } = await client.runs.create({
  workflow_id: 'workflow-uuid',
  main_prompt: 'Prompt v3: open the CRM, find the account, and update the renewal date.',
  input_values: {
    account_id: 'acct_123',
    renewal_date: '2026-07-01'
  }
});

​
Example: always use latest workflow prompt

Omit main_prompt to keep the existing behavior: 
{
  "workflow_id": "workflow-uuid",
  "input_values": {
    "account_id": "acct_123"
  }
}
This run uses whatever main_prompt is currently stored on the workflow when the run executes.

​
Input variables and validation

When main_prompt is provided on the run, Cyberdesk uses that prompt for prompt-variable handling on that run. For example, if the override references {account_id}, that variable is treated as part of the run’s prompt even if the workflow’s stored prompt does not currently reference it. If the workflow has an input_schema, the run’s inputs are still validated against the workflow schema. The override only changes the prompt text used by that run; it does not create or change the workflow schema.

​
Interaction with Post-run Checks

Per-run prompt overrides do not change the workflow-level Post-run Check configuration. One important guard stays tied to the stored workflow prompt: a run can only skip Post-run Checks through declare_task_succeeded with skip_post_run_checks=True when the workflow’s stored prompt explicitly authorizes that behavior. Adding those words only in a per-run override does not authorize skipping checks.

​
When to use this

Use per-run prompt overrides when:
  • you keep prompt versions in your own workflow builder
  • you want a run pinned to a specific prompt version
  • you batch concurrent runs of the same workflow with different prompt versions
  • you want the workflow’s stored prompt to remain a mirror or default, not the runtime source of truth for every run
Do not use this when the workflow itself should remain the only editable source of prompt truth. In that case, update the workflow prompt and create runs without main_prompt.