Loops API

Manage automated Loop tasks and their runs. Create Loops, configure triggers, and monitor execution through the REST API.

Endpoints

Method	Path	Scope	Description
`GET`	/loops	loops:read	List all loops
`POST`	/loops	loops:write	Create a new loop
`GET`	/loops/:slug	loops:read	Get loop by slug
`PUT`	/loops/:slug	loops:write	Update a loop
`DELETE`	/loops/:slug	loops:write	Delete a loop
`POST`	/loops/:slug/enable	loops:write	Enable a loop
`POST`	/loops/:slug/disable	loops:write	Disable a loop
`POST`	/loops/:slug/trigger	loops:write	Manually trigger a run
`GET`	/loops/:slug/runs	loops:read	List runs for a loop
`GET`	/loops/:slug/runs/:run_id	loops:read	Get run details
`POST`	/loops/:slug/runs/:run_id/cancel	loops:write	Cancel an active run

Code Examples

Create a scheduled loop

curl -X POST /api/v1/orgs/{org}/loops \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Code Review",
    "agent_type_id": 1,
    "prompt_template": "Review changes in {{branch}} branch",
    "prompt_variables": {"branch": "main"},
    "execution_mode": "autopilot",
    "cron_expression": "0 9 * * *",
    "sandbox_strategy": "persistent",
    "timeout_minutes": 30
  }'

Trigger a run with variables

curl -X POST /api/v1/orgs/{org}/loops/{slug}/trigger \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "branch": "feature/new-api",
      "focus_area": "security"
    }
  }'

Endpoint Details

GET /loops

Retrieve all loops in the organization. Returns loops sorted by creation date.

POST /loops

Create a new loop with the specified configuration.

Request Body

Field	Description
name	Loop name (required, 1-255 characters)
description	Optional description
agent_type_id	Built-in agent type ID to use
custom_agent_type_id	Custom agent type ID (alternative to agent_type_id)
prompt_template	Task prompt with {{variable}} placeholders (required)
prompt_variables	Default values for prompt variables (JSON object)
repository_id	Repository to clone into the sandbox
runner_id	Preferred runner for execution
branch_name	Git branch to check out
execution_mode	autopilot or direct (default: autopilot)
cron_expression	Cron schedule (e.g., '0 9 * * *'). If set, loop triggers on schedule
sandbox_strategy	persistent or fresh (default: persistent)
session_persistence	Keep agent session across runs (default: true)
concurrency_policy	skip, queue, or replace (default: skip)
max_concurrent_runs	Maximum concurrent runs (default: 1)
timeout_minutes	Run timeout in minutes (default: 60)
callback_url	Webhook URL for run completion notifications
autopilot_config	Autopilot parameters (max_iterations, iteration_timeout_sec)

GET /loops/:slug

Retrieve detailed information about a specific loop by its slug.

PUT /loops/:slug

Update an existing loop. All fields are optional — only provided fields will be updated.

DELETE /loops/:slug

Permanently delete a loop and all its run history. This action cannot be undone.

POST /loops/:slug/enable

Enable a disabled loop. Re-enables cron scheduling if configured.

POST /loops/:slug/disable

Disable a loop. Cron scheduling is paused and manual triggers are blocked.

POST /loops/:slug/trigger

Manually trigger a new run. Optionally pass variables to override prompt template defaults.

Request Body

Field	Description
variables	Variable overrides for the prompt template (JSON object)

GET /loops/:slug/runs

Retrieve the run history for a loop, sorted by most recent first.

GET /loops/:slug/runs/:run_id

Retrieve detailed information about a specific run.

POST /loops/:slug/runs/:run_id/cancel

Cancel an active run. Terminates the associated Pod and marks the run as cancelled.