Trigger agent run

Asks an AI coding agent to work on a project. Returns an AgentRun record with a streaming URL.

POST /v1/agents/run

Trigger an agent run

cURL

curl --request POST \
  --url https://api.vly.ai/v1/agents/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "projectId": "<string>",
  "prompt": "Add a settings page where users can change their email and password."
}
'

202

{
  "id": "run_01JFA8N3Z1B6Y2K7Q3X4M5R8",
  "project_id": "<string>",
  "agent": "claude-code",
  "mode": "agent",
  "status": "queued",
  "stream_url": "<string>",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z"
}

Triggers an agent run from outside vly’s UI. Useful for automating common tasks (regenerate weekly report, run a maintenance prompt nightly).

Agent runs cost credits. Track usage via Get usage.

The stream_url returned is a Server-Sent Events endpoint streaming agent output as it generates.

Authorizations

Authorization · string · header · required

Workspace-scoped API key. Generate from Workspace settings → API keys.

Body

application/json

projectId · string · required

prompt · string · required

Example:

"Add a settings page where users can change their email and password."

agent · enum<string> · default: claude-code

Available options: claude-code, openai-codex, gemini-cli

mode · enum<string> · default: agent

Available options: agent, plan, code

Response

202 - application/json

Accepted

id · string

Example:

"run_01JFA8N3Z1B6Y2K7Q3X4M5R8"

project_id · string

agent · enum<string>

Available options: claude-code, openai-codex, gemini-cli

mode · enum<string>

Available options: agent, plan, code

status · enum<string>

Available options: queued, running, completed, failed, cancelled

stream_url · string<uri>

started_at · string<date-time>

completed_at · string<date-time> | null