agentRunner

Start an agent run on a site

Changed on

Starts an agent run on the site.

post/sites/{site_id}/agent_runners

Request

  • Base URL
    https://api.netlify.com/api/v1
  • URL
    https://api.netlify.com/api/v1/sites/{site_id}/agent_runners
  • Auth
    OAuth 2
    Implicit: https://app.netlify.com/authorize

Request body

promptstring required
branchstring

Branch to start from. Defaults to the site's production branch.

deploy_idstring

Deploy to start from. Takes precedence over branch.

agentstring

Agent to run, for example claude or codex.

modelstring

Model for the agent to use. Omit to let Netlify choose.

effort'low' | 'medium' | 'high'

Reasoning effort. Omit to let the agent decide.

mode'normal' | 'ask'

normal (the default) changes code; ask answers questions without changing code.

Response

OK

idstring
site_idstring
parent_agent_runner_idstring
statestring

One of new, running, await_input, interrupted, error, done, cancelled or archived.

created_atstring dateTime
updated_atstring dateTime
done_atstring dateTime
titlestring
branchstring
result_branchstring
pr_urlstring
pr_branchstring
pr_statestring

One of open, draft, merged or closed.

pr_numberinteger
pr_is_being_createdboolean
pr_errorstring
current_taskstring

What the agent is working on in the active session.

result_diffstring
shastring
merge_commit_shastring
merge_commit_errorstring
merge_commit_is_being_createdboolean
base_deploy_idstring
attached_file_keysstring[]
active_session_created_atstring dateTime
has_result_diffboolean

Whether the run has changes, available from GET /agent_runners/{agent_runner_id}/diff.

latest_session_deploy_idstring
latest_session_deploy_urlstring
preview_statestring

State of the deploy building the latest preview. Null until that deploy exists; ready once the preview is live.

Changes