Tasks

List tasks

Returns the user's tasks, newest first.

Query parameters

Responses

Request

curl 'https://api.agnt.ai/tasks' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "tasks": [
    {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "type": "type",
      "title": "Send Brightline the contract renewal",
      "description": "Draft it, get Maria to sign off, send it."
    }
  ],
  "page": 1,
  "perPage": 20
}

Create a task

Creates a task for the user. To start it, run the task. A task with `status: "scheduled"` and a future `scheduledFor` starts on its own at that time. The assistant must be one the user has.

Request body

Responses

Request

curl 'https://api.agnt.ai/tasks' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Renew the Brightline Freight service contract",
  "assistant": "6702b1e8f9a0b1c2d3e4f5a6"
}'

Response

{
  "ok": true,
  "task": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "type": "type",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}

Retrieve a task

Retrieves a task with its recent activity. To read the full history, list the task's activities.

Path parameters

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "task": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "type": "type",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}

Update a task

Updates a task the user owns. Only the fields you send change.

Path parameters

Request body

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "paused"
}'

Response

{
  "ok": true,
  "task": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "type": "type",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}

Delete a task

Permanently deletes a task with its activity, subtasks and run history. The owner, an account or organization admin, or an account key can delete it.

Path parameters

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "task": {
    "id": "6660c4a1f2e3b7d8a9c01234"
  }
}

Run a task

Starts a run of the task. Pass `message` to add the user's reply to the task before the run starts.

Path parameters

Request body

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>/process' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Brightline agreed to a 3% increase. Update the draft to match."
}'

Response

{
  "ok": true,
  "process": {
    "success": true,
    "taskId": "6660c4a1f2e3b7d8a9c01234"
  }
}

Stop a task

Stops the current run and sets the status to `on_hold`. The task stays open; run it again to resume. Only the owner can stop a task.

Path parameters

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>/stop' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "task": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "type": "type",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}

Mark a task done

Stops the assistant and sets the status to `done_user_marked`.

Path parameters

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>/mark-done' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "task": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "type": "type",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}

Leave feedback on a task

Records the user's thumbs up (`like`) or down (`dislike`) on the task. `null` clears it. Only people following the task can leave feedback.

Path parameters

Request body

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>/feedback' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "like"
}'

Response

{
  "ok": true,
  "feedback": {
    "success": true,
    "taskId": "6660c4a1f2e3b7d8a9c01234",
    "status": "status",
    "message": "Prefers morning meetings."
  }
}

List a task's activities

Returns the task's timeline of messages, status changes and other events, newest first, up to 100 per page (default 50). While `hasMore` is `true`, pass the returned `cursor` as `before` to get older entries.

Path parameters

Query parameters

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>/activities' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "activities": [
    {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "type": "type",
      "createdAt": "2026-10-15T14:30:00Z"
    }
  ],
  "hasMore": false,
  "cursor": "eyJ0IjoiMjAyNi0xMC0xNSJ9"
}

Retrieve a task's usage

Returns the tokens the task used, per run and in total, and the credits charged for each run.

Path parameters

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>/usage' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "total": {
    "inputTokens": 1840,
    "outputTokens": 1840,
    "cacheReadTokens": 1840,
    "cacheCreationTokens": 1840
  },
  "rows": [
    {
      "runId": "6660c4a1f2e3b7d8a9c01234",
      "seq": 1,
      "modelTier": "modeltier",
      "inputTokens": 1840
    }
  ],
  "credits": {
    "total": 42,
    "runs": [
      {
        "chargedCredits": 5,
        "isBillable": true,
        "createdAt": "2026-10-15T14:30:00Z"
      }
    ]
  }
}

Approve a proposed task

Approves a task the assistant created and is holding for the user. The task starts, or waits for its scheduled time. Call it as a user who owns, follows or works on the task.

Path parameters

Request body

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>/approve' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Approved by Jane"
}'

Response

{
  "ok": true,
  "task": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "type": "type",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}

Decline a proposed task

Declines a task the assistant is holding for the user. The proposed work is not done; the decline and optional `reason` go into the task's conversation, and the assistant follows up.

Path parameters

Request body

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>/decline' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Approved by Jane"
}'

Response

{
  "ok": true,
  "task": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "type": "type",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}

Approve proposed tasks in bulk

Approves up to 100 proposed tasks in one call. Each task is handled on its own; tasks that cannot be approved are listed in `failed`.

Request body

Responses

Request

curl 'https://api.agnt.ai/tasks/approve-batch' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "taskIds": [
    "6660c4a1f2e3b7d8a9c01234"
  ]
}'

Response

{
  "ok": true,
  "batch": {
    "approved": [
      "approved"
    ],
    "failed": [
      {
        "taskId": "6660c4a1f2e3b7d8a9c01234",
        "error": "error"
      }
    ]
  }
}

Reopen a task

Reopens a completed task, or one the user marked done. The status returns to `pending`, and the assistant asks the user how to proceed. Only the task owner can reopen it.

Path parameters

Responses

Request

curl 'https://api.agnt.ai/tasks/<taskId>/mark-not-done' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "task": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "type": "type",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}