Tasks & Runs

Base URL: https://agent-api.auteryn.ai

A task (also called a thread) is a conversation. Each turn produces a run — a single agent execution. All endpoints require a JWT (Authorization: Bearer <jwt> or the auth_session cookie) and, unless noted, the X-Agent-Id header.

List tasks — `GET /api/tasks`

GET https://agent-api.auteryn.ai/api/tasks?limit=50
Authorization: Bearer <jwt>
X-Agent-Id: your-agent-uuid

Param	Description
`limit`	Number of tasks (default: 50)

There is no offset parameter on this endpoint.

Get a task — `GET /api/tasks/{task_id}`

Returns the full task object including run summaries.

Stream task events — `GET /api/tasks/{task_id}/stream`

SSE stream of live events for an in-progress or completed task. Emits the same AG-UI event types as POST /api/run. Use this to follow a run started with stream: false or /api/run/async.

Run events — `GET /api/runs/{run_id}/events`

Paginated JSON history of a run’s events (durable — survives disconnects):

{
  "run_id": "run_abc",
  "events": [
    {
      "id": "evt_1",
      "run_id": "run_abc",
      "event_type": "TEXT_MESSAGE_CONTENT",
      "event_name": "TEXT_MESSAGE_CONTENT",
      "payload": {},
      "created_at": "2026-07-03T12:00:00Z"
    }
  ],
  "next_cursor": null,
  "count": 1
}

Param	Description
`cursor`	Opaque pagination cursor — pass the previous response’s `next_cursor` to continue.
`limit`	Page size.

A null next_cursor means you have reached the tail.

Delete a task — `DELETE /api/tasks/{task_id}`

Permanently deletes the task and all its runs and messages.

{ "status": "ok", "message": "Task task_abc deleted" }

Run control

Endpoint	Method	Purpose
`/api/tasks/{task_id}/cancel`	POST	Cancel the active run for the task.
`/api/tasks/{task_id}/pause`	POST	Pause the active run.
`/api/tasks/{task_id}/resume`	POST	Resume a paused run.
`/api/tasks/{task_id}/runs/{run_id}/comment`	POST	Add a mid-execution comment (steers a running agent). Body: `{"content": "..."}` (max 2000 chars).

Human-in-the-loop (HITL)

When an agent calls a tool like request_user_input or ask_user_question — or hits a plan/action approval gate — it blocks and stops streaming until the user’s answer is submitted. A programmatic caller that ignores this will hang.

The flow:

On the run stream you receive a CUSTOM event with name: "USER_INPUT_REQUIRED". Its data carries a request_id, run_id, and an input_type (confirmation, text, number, choice, multiline, plan_approval, action_approval, or structured_questions).
Submit the user’s answer with POST /api/tasks/{task_id}/input.
The agent resumes and the stream continues.

If your client reconnects (e.g. page refresh) and needs to know whether the agent is currently waiting, poll GET /api/tasks/{task_id}/pending-input first.

Is the agent waiting? — `GET /api/tasks/{task_id}/pending-input`

{
  "pending": true,
  "request": {
    "request_id": "req_abc",
    "input_type": "confirmation",
    "prompt": "Delete the 3 stale branches?"
  }
}

{"pending": false} when nothing is awaiting input.

Respond to a HITL request

POST /api/tasks/{task_id}/input

POST https://agent-api.auteryn.ai/api/tasks/{task_id}/input
Authorization: Bearer <jwt>
Content-Type: application/json

Body — always include request_id, run_id, and input_type from the USER_INPUT_REQUIRED event, then the fields matching the type:

`input_type`	Answer fields
`confirmation`	`confirmed` (bool), optional `response_text`
`text` / `number` / `choice` / `multiline`	`value` (string)
`plan_approval`	`approved` (bool), optional `modified_steps`, `feedback`
`action_approval`	`approved` (bool); optional `approve_always`, `approve_run_scope`, `feedback`
`structured_questions`	`answers` — a map keyed by question text
(any)	`cancelled: true` to dismiss the request

{
  "request_id": "req_abc",
  "run_id": "run_abc",
  "input_type": "confirmation",
  "confirmed": true
}

Response:

{ "success": true, "message": "Input received successfully" }

Sensitive-class action_approval requests can only be approved by an org owner or admin (a member token gets 403).

Approvals inbox — `GET /api/approvals`

Org-scoped list of pending approvals across your agents (defaults to ?status=pending). Members see only approvals for agents they can access.

{ "approvals": [ /* … */ ], "count": 0 }

Respond by approval id — `POST /api/approvals/{approval_id}/respond`

Machine/external approver path (same resolution as the workspace card).

{ "decision": "approve", "feedback": "optional note" }

decision must be "approve" or "reject".

Status values

The task/run lifecycle:

Task-level run_status: idle → pending → running → completed | failed

Individual run status: pending → planning → awaiting_approval → executing → completed | failed | cancelled | paused

Note: individual runs use executing, not running. A run sits in awaiting_approval while a plan/action gate is open (see HITL).

Tasks & Runs

List tasks — GET /api/tasks

Get a task — GET /api/tasks/{task_id}

Stream task events — GET /api/tasks/{task_id}/stream

Run events — GET /api/runs/{run_id}/events

Delete a task — DELETE /api/tasks/{task_id}