Sign in
Agents

post/projects/{project_id}/agents/{slug}/trigger

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}/agents/{slug}/trigger
  • Auth: HTTP bearer

Path parameters

project_idinteger required

Project ID

slugstring required

Agent slug

Request body

trigger_source_idinteger nullable
trigger_source_typestring nullable
user_contextstring nullable

Optional context from the user (e.g. a research topic, bug description, or instructions).

Response

Agent 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 50 revisions of this API.