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. Send Last-Event-ID to resume after the last event you received. The stream closes after RUN_FINISHED or RUN_ERROR.

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": "1842",
      "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 (default 500, max 5000).

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}/resume`	POST	Continue a stopped run. Starts a new run that continues from where the stopped one ended. Body (optional): `{"instructions": "..."}`. Answers `409` when there is no stopped 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 asks the user a question, reaches a plan or action approval, or an Integration asks for details mid-call, it stops and waits until the 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, structured_questions, elicitation_form, or elicitation_url).
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-inputs first.

An agent token cannot do step 2: POST /api/tasks/{task_id}/input answers 403. The run waits up to 72 hours for a member of your organization to answer in the workspace, then counts as rejected. See Waiting for a person.

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

Several runs on one task can wait at once. The response lists one entry per open request:

{
  "pending": [
    {
      "request_id": "req_abc",
      "run_id": "run_abc",
      "input_type": "confirmation",
      "prompt": "Delete the 3 stale branches?"
    }
  ]
}

{"pending": []} when nothing is awaiting input. The older GET /api/tasks/{task_id}/pending-input returns only the newest request, as {"pending": true, "request": {…}}.

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
`elicitation_form` / `elicitation_url`	`answers`: the fields the Integration asked for (`{}` once the user has finished on the link)
(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`

Lists up to 50 pending approvals across your organization’s agents. Members see only approvals for agents they can access; guests and customers get 403.

{ "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". An approval that was already answered returns {"ok": false, "status": "already_resolved"}.

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}