Tasks Overview

Tasks are the core resource in HPI. Each task represents a unit of work that requires human input.

Task Lifecycle

Created (pending)
    |
    +---> Completed (operator submitted the form)
    |
    +---> Cancelled (creator or admin cancelled it)
    |
    +---> Failed (system error)

Once a task leaves the pending state, it's final — there's no going back.

Task Data Model

Field	Type	Description
`task_id`	string	Unique identifier (UUID)
`title`	string	Display title (max 200 chars)
`status`	string	`pending`, `completed`, `cancelled`, `failed`
`steps`	array	Form steps with blocks
`data`	object	Submitted form data (only when completed)
`created_at`	string	ISO 8601 timestamp
`completed_at`	string	ISO 8601 timestamp (when completed)
`org_id`	string	Organization identifier
`corr_id`	string	Correlation ID for tracing
`process_id`	string	Linked process (optional)
`process_step`	string	Process step key (optional)

Integration Patterns

Long-Poll Wait

Create a task, then call GET /api/v1/tasks/{task_id}/wait?timeout=300. The server holds the connection open until the task reaches a terminal state or the timeout expires. Returns the full task data including status and data. Returns 408 with timed_out: true on timeout.

With the MCP server, set wait: true on create_task to do this in a single call.

Poll for Completion

Alternatively, poll GET /api/v1/tasks/{task_id} until the status changes from pending.

Notification Sinks

Create a task with one or more notification sinks — webhook, NATS, or email. HPI will notify you when the task completes, is cancelled, or fails. Email sinks include a PDF attachment of the submitted form data on completion.

SSE Stream

Connect to the Server-Sent Events stream at /api/tasks/stream to receive real-time notifications for all task events.

Process Tracking

Link tasks to processes for multi-step workflow visibility. When a linked task completes, the parent process step auto-completes.