Tasks API

The Tasks API lets you trigger, monitor, and retrieve results from any deployed agent.

Base URL

https://api.ariftly.io/v1

Create a task

POST /tasks

Triggers a new task on a deployed agent. Returns immediately with a task_id — the agent runs asynchronously.

Request body:

{
  "agent": "ai-readiness",
  "task_type": "questionnaire.respond",
  "input": {
    "document_url": "https://example.com/questionnaire.pdf"
  },
  "priority": "normal"
}

Field	Type	Required	Description
agent	string	✅	Agent slug (e.g., ai-readiness, sales)
task_type	string	✅	Task type declared in the agent's manifest
input	object	✅	Input payload validated against the agent's input schema
priority	string	—	low, normal, high. Default: normal
session_id	string	—	Attach this task to an existing session

Response 202 Accepted:

{
  "task_id": "task_01j9x8k...",
  "agent": "ai-readiness",
  "task_type": "questionnaire.respond",
  "status": "queued",
  "created_at": "2026-04-21T10:00:00Z"
}

Get a task

GET /tasks/{task_id}

Response 200 OK:

{
  "task_id": "task_01j9x8k...",
  "agent": "ai-readiness",
  "task_type": "questionnaire.respond",
  "status": "complete",
  "created_at": "2026-04-21T10:00:00Z",
  "completed_at": "2026-04-21T10:03:42Z",
  "artifacts": [
    {
      "artifact_id": "art_01j9x8m...",
      "type": "ai_readiness.questionnaire_response",
      "created_at": "2026-04-21T10:03:41Z"
    }
  ]
}

Task statuses:

Status	Meaning
queued	Waiting to be dispatched to the agent
running	Agent is actively working
awaiting_approval	Agent is waiting for human approval before proceeding
complete	Agent finished and emitted all artifacts
failed	Agent encountered an unrecoverable error
cancelled	Task was manually cancelled

List tasks

GET /tasks

Query parameters:

Parameter	Type	Description
agent	string	Filter by agent slug
status	string	Filter by status
limit	integer	Max results. Default: 20, max: 100
cursor	string	Pagination cursor from previous response

Response 200 OK:

{
  "tasks": [...],
  "next_cursor": "cursor_abc..."
}

Cancel a task

DELETE /tasks/{task_id}

Cancels a running task. The agent will receive a cancellation signal and stop work.

Response 200 OK:

{ "cancelled": true }

Get task artifacts

GET /tasks/{task_id}/artifacts

Returns all artifacts emitted by a completed task.

Response 200 OK:

{
  "artifacts": [
    {
      "artifact_id": "art_01j9x8m...",
      "type": "ai_readiness.questionnaire_response",
      "data": {
        "answers": [...],
        "confidence_scores": {...}
      },
      "created_at": "2026-04-21T10:03:41Z"
    }
  ]
}