POST /api/v1/tasks

Create Task

Create a new task that appears in the operator's dashboard.

Request

curl -X POST https://your-instance/api/v1/tasks \
  -H "Authorization: Bearer htk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review document",
    "steps": [{ "id": "review", "title": "Review", "blocks": [...] }]
  }'

Required scope: tasks:create

Request Body

Field	Type	Required	Description
`title`	string	Yes	Task title (max 200 chars)
`steps`	array	Yes	One or more form steps
`task_id`	string	No	Custom UUID (auto-generated if omitted)
`instructions_mdsvex`	string	No	Markdown instructions shown above the form
`assignee_member_id`	string	No	Assign to an org member by user ID. Use `"me"` to assign to the API token owner.
`assignee_email`	string	No	Assign by email. If the email matches an org member, resolves as member (dashboard link). Otherwise creates an external assignee with OTP verification.
`assignee_name`	string	No	Display name for external assignee
`assignee_phone`	string	No	Phone number for external assignee
`expires_in`	number	No	Link expiration in seconds (60 to 2,592,000)
`corr_id`	string	No	Correlation ID for tracing
`process_id`	string	No	Link to a parent process
`process_step`	string	No	Process step key
`payload`	object	No	Arbitrary metadata
`sinks`	array	No	Notification sinks (webhook, NATS, email)

Step Object

Field	Type	Required	Description
`id`	string	Yes	Unique step identifier
`title`	string	Yes	Step title
`description_mdsvex`	string	No	Markdown description
`blocks`	array	Yes	Content blocks

Notification Sinks

Sinks define where to send notifications when the task completes, is cancelled, or fails.

Webhook sink:

{
	"type": "webhook",
	"url": "https://your-app/webhook",
	"secret": "optional-hmac-secret",
	"events": ["completed", "cancelled", "failed"]
}

NATS sink:

{
	"type": "nats",
	"subject": "my.custom.subject",
	"events": ["completed"]
}

Email sink:

{
	"type": "email",
	"to": "manager@company.com",
	"events": ["completed"]
}

On completion, a PDF of the submitted form data is attached to the email. Cancelled/failed events send a plain email with the reason.

If no secret is provided for webhook sinks, one is auto-generated and returned in the response.

Response

{
	"task_id": "uuid",
	"link_id": "uuid",
	"url": "https://your-instance/t/...",
	"requires_otp": false,
	"sinks": [
		{
			"type": "webhook",
			"url": "https://your-app/webhook",
			"secret": "auto-generated-hex-secret"
		},
		{
			"type": "nats",
			"subject": "my.custom.subject"
		},
		{
			"type": "email",
			"to": "manager@company.com"
		}
	],
	"created_at": "2026-02-24T12:00:00Z"
}

Errors

Status	Meaning
`400`	Invalid request body — check `details` array for field-level errors
`401`	Missing or invalid token
`403`	Token lacks `tasks:create` scope

Example: Feedback Survey

Shows the newer field types — radio, date, range, and rating:

{
	"title": "Product Feedback",
	"steps": [
		{
			"id": "feedback",
			"title": "Your Feedback",
			"blocks": [
				{
					"type": "input",
					"field": {
						"name": "role",
						"label": "Your Role",
						"kind": "radio",
						"options": ["Developer", "Designer", "PM", "Other"]
					}
				},
				{
					"type": "input",
					"field": {
						"name": "start_date",
						"label": "When did you start using the product?",
						"kind": "date",
						"include_time": true
					}
				},
				{
					"type": "input",
					"field": {
						"name": "ease_of_use",
						"label": "Ease of Use",
						"kind": "range",
						"min": 0,
						"max": 10,
						"step": 1
					}
				},
				{
					"type": "input",
					"field": {
						"name": "overall_rating",
						"label": "Overall Rating",
						"kind": "rating",
						"max_rating": 5
					}
				},
				{
					"type": "input",
					"field": {
						"name": "comments",
						"label": "Additional Comments",
						"kind": "textarea",
						"required": false
					}
				}
			]
		}
	]
}

Example: Multi-step Form

{
	"title": "New employee onboarding",
	"steps": [
		{
			"id": "personal",
			"title": "Personal Information",
			"blocks": [
				{
					"type": "input",
					"field": { "name": "full_name", "label": "Full Name", "kind": "text", "required": true }
				},
				{
					"type": "input",
					"field": {
						"name": "department",
						"label": "Department",
						"kind": "select",
						"options": ["Engineering", "Sales", "Marketing", "HR"]
					}
				}
			]
		},
		{
			"id": "documents",
			"title": "Upload Documents",
			"blocks": [
				{
					"type": "callout",
					"severity": "info",
					"content": "Please upload a scan of the signed contract."
				},
				{
					"type": "input",
					"field": {
						"name": "contract",
						"label": "Signed Contract",
						"kind": "file",
						"required": true
					}
				}
			]
		},
		{
			"id": "approval",
			"title": "Manager Approval",
			"blocks": [
				{
					"type": "input",
					"field": { "name": "approved", "label": "Approve onboarding?", "kind": "checkbox" }
				},
				{
					"type": "input",
					"field": {
						"name": "signature",
						"label": "Manager Signature",
						"kind": "signature",
						"required": true
					}
				}
			]
		}
	]
}