Skip to main content
Documentation

Quick Start

Create your first human-in-the-loop task in 5 minutes.

Step 1: Get an API Token

  1. Log into HPI
  2. Go to Settings > API Tokens
  3. Create a token with the tasks:create scope
  4. Copy the token (starts with htk_)

Step 2: Create a Task

curl -X POST https://your-instance/api/v1/tasks \
  -H "Authorization: Bearer htk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Approve deployment to production",
    "steps": [{
      "id": "approval",
      "title": "Review and Approve",
      "blocks": [
        {
          "type": "mdsvex",
          "content": "A new deployment is ready for **production**. Please review the changes and approve."
        },
        {
          "type": "input",
          "field": {
            "name": "decision",
            "label": "Decision",
            "kind": "select",
            "options": ["Approve", "Reject"],
            "required": true
          }
        },
        {
          "type": "input",
          "field": {
            "name": "comments",
            "label": "Comments",
            "kind": "textarea",
            "required": false,
            "placeholder": "Any additional notes..."
          }
        }
      ]
    }]
  }'

Response:

{
	"task_id": "a1b2c3d4-...",
	"link_id": "e5f6g7h8-...",
	"url": "https://your-instance/t/e5f6g7h8-...",
	"requires_otp": false,
	"created_at": "2026-02-24T12:00:00Z"
}

Step 3: Check the Dashboard

Open HPI in your browser. The task appears in the Pending tab immediately.

Step 4: Complete the Task

Click the task, fill out the form, and submit.

Step 5: Wait for the Result

Use the long-poll wait endpoint — the server holds the connection open until the task is completed:

curl https://your-instance/api/v1/tasks/a1b2c3d4-.../wait?timeout=300 \
  -H "Authorization: Bearer htk_your_token_here"

Response (completed):

{
	"task_id": "a1b2c3d4-...",
	"status": "completed",
	"data": {
		"decision": "Approve",
		"comments": "Looks good, ship it!"
	},
	"completed_at": "2026-02-24T12:05:00Z"
}

You can also poll GET /api/v1/tasks/{task_id} if you prefer, or use notification sinks for push-based delivery.

Next Steps