Skip to main content
Documentation

Developer Documentation

HPI provides a REST API and MCP server for creating tasks that require human input. Use it to build human-in-the-loop workflows into your AI agents, automation pipelines, and applications.

Architecture Overview

Your Application
       |
       v
  REST API / MCP Server
       |
       v
  HPI (Database + SSE)
       |
       v
  Operator Dashboard (Real-time SSE)
       |
       v
  Human completes task
       |
       v
  Notification Sinks / Poll for result

Tasks created via the API are persisted to the database and streamed to the operator dashboard in real-time via Server-Sent Events (SSE). Optionally, NATS JetStream can be added for external integrations (event streaming, inbound cancel requests, NATS notification sinks).

Integration Patterns

1. Create and Wait

The simplest pattern — create a task and wait for the human to respond. The server holds the connection open until the task completes (long-poll):

# Create a task
curl -X POST https://your-instance/api/v1/tasks \
  -H "Authorization: Bearer htk_your_token" \
  -H "Content-Type: application/json" \
  -d '{"title": "Review document", "steps": [...]}'

# Wait for completion (long-poll, up to 5 minutes)
curl https://your-instance/api/v1/tasks/TASK_ID/wait?timeout=300 \
  -H "Authorization: Bearer htk_your_token"

With the MCP server, use create_task with wait: true to combine both steps into a single call.

2. Create with Notification Sink

Create a task with a notification sink. HPI will notify your endpoint when the task is completed. Sinks support webhook, email, and NATS:

curl -X POST https://your-instance/api/v1/tasks \
  -H "Authorization: Bearer hk_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Approve deployment",
    "sinks": [{ "type": "webhook", "url": "https://your-app/webhooks/task-complete" }],
    "steps": [...]
  }'

3. MCP Server

If you're building with Claude or another AI assistant that supports the Model Context Protocol, the HPI MCP server provides tools like create_task, ask_approval, ask_question, and more.

Key Concepts

Tasks

A task is a unit of work that requires human input. Each task has:

  • Title — Displayed in the dashboard
  • Steps — One or more form steps the operator works through
  • Blocks — Content elements within each step (form fields, markdown, images, tables)
  • Status — pending, completed, cancelled, or failed

Processes

A process tracks a multi-step workflow. Each step can be automated or require human input (via a linked task). Use processes to give operators visibility into where things stand in a larger workflow.

Organizations

Tasks are scoped to organizations. API tokens are tied to an organization, and operators only see tasks belonging to their active organization.

Next Steps