Using the REST API

The Task API exposes 5 endpoints under the base URL from the ApiUrl stack output.

Create a task

curl -X POST "$API_URL/tasks" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "owner/repo",
    "task_description": "Add input validation to the /users POST endpoint"
  }'

Example response right after submit (status is SUBMITTED; branch_name is reserved up front; session_id, pr_url, cost, and timing stay null until the orchestrator and agent progress):

curl -X POST "$API_URL/tasks" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "krokoko/agent-plugins", "task_description": "add codeowners field to RFC issue template"}'

{"data":{"task_id":"01KN36YGQV6BEPDD7CVMKP1PF3","status":"SUBMITTED","repo":"krokoko/agent-plugins","issue_number":null,"task_description":"add codeowners field to RFC issue template","branch_name":"bgagent/01KN36YGQV6BEPDD7CVMKP1PF3/add-codeowners-field-to-rfc-issue-template","session_id":null,"pr_url":null,"error_message":null,"created_at":"2026-04-01T00:26:30.011Z","updated_at":"2026-04-01T00:26:30.011Z","started_at":null,"completed_at":null,"duration_s":null,"cost_usd":null,"build_passed":null,"max_turns":null,"max_budget_usd":null,"prompt_version":null}}

To create a task from a GitHub issue:

curl -X POST "$API_URL/tasks" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "owner/repo", "issue_number": 42}'

Request body fields:

Field	Type	Required	Description
`repo`	string	Yes	GitHub repository in `owner/repo` format
`issue_number`	number	One of these	GitHub issue number
`task_description`	string	is required	Free-text task description
`max_turns`	number	No	Maximum agent turns (1–500). Overrides the per-repo Blueprint default. Platform default: 100.
`max_budget_usd`	number	No	Maximum cost budget in USD (0.01–100). When reached, the agent stops regardless of remaining turns. Overrides the per-repo Blueprint default. If omitted, no budget limit is applied.

Idempotency: Include an Idempotency-Key header (alphanumeric, dashes, underscores, max 128 chars) to prevent duplicate task creation on retries:

curl -X POST "$API_URL/tasks" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-123" \
  -d '{"repo": "owner/repo", "task_description": "Fix bug"}'

List tasks

curl "$API_URL/tasks" -H "Authorization: $TOKEN"

Query parameters:

Parameter	Description
`status`	Filter by status (e.g., `RUNNING` or `RUNNING,SUBMITTED`)
`repo`	Filter by repository
`limit`	Max results per page (default: 20, max: 100)
`next_token`	Pagination token from a previous response

Example with filters:

curl "$API_URL/tasks?status=RUNNING,SUBMITTED&limit=10" -H "Authorization: $TOKEN"

Get task detail

curl "$API_URL/tasks/<TASK_ID>" -H "Authorization: $TOKEN"
curl "$API_URL/tasks/01KJDSS94G3VA55CW1M534EC7Q" -H "Authorization: $TOKEN"

Returns the full task record including status, timestamps, PR URL, cost, and error details.

Example (after a successful run — status is COMPLETED, pr_url populated):

curl "$API_URL/tasks/01KN36YGQV6BEPDD7CVMKP1PF3" -H "Authorization: $TOKEN"

{"data":{"task_id":"01KN36YGQV6BEPDD7CVMKP1PF3","status":"COMPLETED","repo":"krokoko/agent-plugins","issue_number":null,"task_description":"add codeowners field to RFC issue template","branch_name":"bgagent/01KN36YGQV6BEPDD7CVMKP1PF3/add-codeowners-field-to-rfc-issue-template","session_id":"3eb8f3fb-808d-47d6-8557-309fb9369ea7","pr_url":"https://github.com/krokoko/agent-plugins/pull/59","error_message":null,"created_at":"2026-04-01T00:26:30.011Z","updated_at":"2026-04-01T00:26:35.350Z","started_at":"2026-04-01T00:26:35.350Z","completed_at":"2026-04-01T00:30:32Z","duration_s":"125.9","cost_usd":"0.15938219999999997","build_passed":null,"max_turns":null,"max_budget_usd":null,"prompt_version":"1c9c10e027a2"}}

Cancel a task

curl -X DELETE "$API_URL/tasks/<TASK_ID>" -H "Authorization: $TOKEN"

Transitions the task to CANCELLED and records a cancellation event. Only tasks in non-terminal states can be cancelled.

Get task events (audit log)

curl "$API_URL/tasks/<TASK_ID>/events" -H "Authorization: $TOKEN"

Returns the chronological event log for a task (e.g., task_created, session_started, task_completed). Supports limit and next_token pagination parameters.