Workflows

post/projects/{project_id}/workflows/dry-run

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/projects/{project_id}/workflows/dry-run
  • Auth: HTTP bearer

Path parameters

project_idinteger required

Project ID

Request body

cpu_limitnumber double nullable

Optional CPU override applied after parsing YAML (clamped server-side). When Some, this takes precedence over cpu_limit inside the YAML — lets the CLI pass --cpu without rewriting the YAML text.

error_group_idinteger nullable

Optional error group to link this dry-run to. When set, the executor's load_error_context path injects {{error_type}} / {{error_message}} / {{stack_trace}} into the prompt — same behaviour as a committed workflow triggered with trigger_source_type = "error_group". Must belong to project_id (handler enforces).

memory_limit_mbinteger nullable

Optional memory override in MB (clamped server-side). Same precedence rule as cpu_limit.

user_contextstring nullable

Optional context appended to the prompt (e.g. "test against staging only"). Mirrors TriggerAgentRequest.user_context.

yamlstring required

Full WorkflowYamlConfig as YAML text. Server validates and re-serializes before storing on the run row.

Response

Ephemeral run created and queued

agent_namestring nullable

Name of the agent that created this run, if available.

agent_slugstring nullable

Slug of the agent that created this run, if available.

ai_modelstring nullable
ai_outputstring nullable
ai_providerstring nullable

AI provider slug that executed this run (e.g. claude_cli, codex_cli, opencode).

ai_reasoningstring nullable
ai_session_idstring nullable

Claude CLI session UUID for resuming conversations via --resume.

analysisstring nullable

Report / analysis text produced by the agent (used for report/notification deliverables).

branch_namestring nullable
commit_shastring nullable
completed_atstring nullable
config_idinteger nullable

Optional. NULL for ephemeral CLI runs (source = "cli_ephemeral") and historical autofixer runs that pre-date the agent_id column.

created_atstring required
ephemeral_yamlstring nullable

Full WorkflowYamlConfig as YAML text. Populated only when source = "cli_ephemeral". Used by the web UI to show a "View YAML" modal so the user can see exactly what the executor ran.

error_messagestring nullable
estimated_cost_centsinteger required
files_changedinteger required
idinteger required
phasestring nullable

Autofixer phase: "analyzing", "analyzed", "fixing", "fix_ready", "no_fix", "pr_created", or NULL for non-autofixer runs.

pr_numberinteger nullable
pr_urlstring nullable
preview_urlstring nullable
project_idinteger required
prompt_textstring nullable

Final assembled prompt the AI CLI actually saw (trigger context block + YAML prompt, with error-group fields interpolated). Captured once per run. None for pre-migration rows.

sandbox_enabledboolean required

Legacy field — all runs now execute in a sandbox. Kept for backwards-compatible JSON shape; always true.

sourcestring required

committed (the run's config lives in project_agents) or cli_ephemeral (the config was uploaded via the CLI for a one-off dry run; see ephemeral_yaml).

started_atstring nullable
statusstring required
tokens_inputinteger required
tokens_outputinteger required
trigger_source_idinteger nullable
trigger_source_typestring nullable
trigger_typestring required
user_contextstring nullable

User-provided context for this run (e.g. webhook payload, manual instructions).

Changes

No recorded changes to this operation across all 54 revisions of this API.