REST API

Hypertask’s public REST API is available at https://app.hypertask.ai/api/v1. Use it to list projects, create and update tasks, manage comments, assign users, read inbox notifications, and manage task drafts.

Note

All requests and responses use JSON. Query parameters use snake_case. Some request body fields keep their existing API names, including sectionId and userToAdd; use the names shown in this reference. Task descriptions, comments, and drafts are HTML, not Markdown.

Authentication

Send an API key in the Authorization header:

Authorization: Bearer htk_...

Create API keys in the Hypertask app with Ctrl+K -> REST API. Each user can have up to 10 active keys. The full key is shown once when it is created, and keys can be revoked from the same modal.

export HT_API_KEY=htk_...

curl -s -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/user/context"

Error responses use this general shape:

{
  "success": false,
  "error": "Validation error",
  "message": "project_id must be a positive integer",
  "details": {
    "field": "project_id",
    "code": "invalid_type"
  }
}

Session-validated identity

Previously, several public API routes accepted an unsigned nookies_user cookie as the authenticated user identity. This has been tightened to prevent account takeover via forged cookies:

• Routes that set nookies_user.id now require a valid, matching signed ht_session cookie with the same id value to succeed.

• The following route families are affected:

  • Auth routes (e.g., /api/auth/*)
  • MCP routes (/api/mcp/*)
  • Other 64 public sub-paths previously relying on unsigned nookies_user
  • All associated webhook and logged-out call sites

Verified live on production: forging nookies_user={"id":6} now returns 401 instead of 200+ full data, and forging {"id":1} for any other user also returns 401.

Compatibility: The consensus across the auth, MCP, public, webhook, logged-out, and Bearer-auth request families is that this change does not affect existing integrations or tools:

• Auth requests with standard Authorization: Bearer $HT_API_KEY continue to work.
• MCP tools retain their same param schema.
• Public integrations that already manage ht_session via the app workload continue untouched.
• Work that previously shipped nookies_user directly (e.g., via server-to-server calls) should now explicitly sign or add ht_session with the same id, but it is a rare pattern in practice.

If your pattern relies on unsigned nookies_user outside these call sites, see /api/session/verify to validate the signed session instead.

---

Calling the API Directly from Agents

The Hypertask CLI is a thin wrapper around the REST API. Every CLI command ultimately calls a route under https://app.hypertask.ai/api/mcp/*. You can call those same routes directly with curl or any HTTP client, bypassing the Node.js process startup cost.

Measured from a VPS, the difference is substantial:

Method	Typical latency
curl direct to REST API	~0.21 s
hypertask CLI	~0.84 – 1.06 s

The gap is almost entirely Node.js cold-start time. For agents that issue many sequential calls, this adds up quickly.

How the routes map:

• The api/v1 routes documented on this page are the public, versioned REST API — use these for integrations and scripts.
• The api/mcp/* routes are the same operations that the CLI and MCP server use internally. They accept the same authentication header (Authorization: Bearer htk_...).

For agent workloads that currently shell out to the CLI, switching to direct curl calls against either the api/v1 or api/mcp/* routes is a straightforward way to cut per-operation latency by ~4×.

Tip

The MCP server itself is already a direct API client — if you’re using Hypertask via MCP from Claude, Cursor, or another agent host, you’re already getting REST-speed access. Direct curl is most valuable when you’re scripting in shell or want to avoid the Node.js runtime entirely.

Task Identifiers

Routes that operate on a specific task usually accept exactly one task identifier:

task_id

Use the internal task ID:

{ "task_id": 789 }

ticket_number

Use the project ticket number. Add project_id when ticket numbers may be ambiguous.

{ "ticket_number": "ENG-42", "project_id": 123 }

unique_index

Use the project-scoped task index with project_id.

{ "project_id": 123, "unique_index": 42 }

---

User

Get User Context

Return the authenticated user, accessible teams, projects, and agents.

Endpoint: GET /api/v1/user/context

Parameters: None

Example request:

curl -s -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/user/context"

Response shape:

{
  "success": true,
  "user": {
    "id": 6,
    "email": "valentin@example.com",
    "displayName": "Valentin"
  },
  "connected_agent": null,
  "teams": [
    { "id": "team_uuid", "title": "Product" }
  ],
  "projects": [
    { "id": 123, "title": "Engineering", "labels": [], "sections": [] }
  ],
  "all_agents": [
    { "id": "agent_uuid", "displayName": "Release Agent" }
  ]
}

---

Projects

List Projects

List projects the API key owner can access.

Endpoint: GET /api/v1/projects

Query parameters:

Parameter	Type	Required	Default	Description
status	string	No	Normal	Filter by Normal, Archive, or Deleted
search	string	No	—	Search project title, name, or description
limit	number	No	50	Max results, capped at 100
offset	number	No	0	Pagination offset
sort_by	string	No	title	title, createdAt, or updatedAt
sort_order	string	No	asc	asc or desc

Example request:

curl -s -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/projects?status=Normal&limit=20"

Response shape:

{
  "success": true,
  "projects": [
    {
      "id": 123,
      "title": "Engineering",
      "description": "Product engineering work",
      "memberCount": 5,
      "taskCount": 42,
      "sections": [
        { "id": 456, "section_title": "Todo" }
      ],
      "labels": [
        { "id": "label_uuid", "name": "Customer" }
      ],
      "status": "Normal",
      "createdAt": "2026-03-10T12:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

List Project Sections

List sections for a project board.

Endpoint: GET /api/v1/projects/{projectId}/sections

Path parameters:

Parameter	Type	Required	Description
projectId	number	Yes	Project ID

Query parameters:

Parameter	Type	Required	Default	Description
include_hidden	boolean	No	false	Include hidden sections

Example request:

curl -s -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/projects/123/sections?include_hidden=false"

Response shape:

{
  "success": true,
  "sections": [
    {
      "id": 456,
      "section_title": "Todo",
      "projectId": 123,
      "visibility": true,
      "deleted": false,
      "ranking": "a0",
      "taskCount": 12
    }
  ],
  "projectId": 123
}

Create Project Section

Create a section in a project.

Endpoint: POST /api/v1/projects/{projectId}/sections

Path parameters:

Parameter	Type	Required	Description
projectId	number	Yes	Project ID

Body parameters:

Parameter	Type	Required	Description
title	string	Yes	Section name, 1 to 200 characters
after_section_id	number	No	Insert the new section after this section ID

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"QA","after_section_id":456}' \
  "https://app.hypertask.ai/api/v1/projects/123/sections"

Response shape:

{
  "success": true,
  "section": {
    "id": 457,
    "section_title": "QA",
    "projectId": 123,
    "taskCount": 0
  },
  "message": "Section created successfully"
}

Update Project Section

Rename or reorder a section.

Endpoint: PATCH /api/v1/projects/{projectId}/sections/{sectionId}

Path parameters:

Parameter	Type	Required	Description
projectId	number	Yes	Project ID
sectionId	number	Yes	Section ID

Body parameters:

Parameter	Type	Required	Description
title	string	No	New section name
move_after_section_id	number	No	Move the section after this section ID

Provide at least one body parameter.

Example request:

curl -s -X PATCH -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Ready for QA"}' \
  "https://app.hypertask.ai/api/v1/projects/123/sections/456"

Response shape:

{
  "success": true,
  "section": {
    "id": 456,
    "section_title": "Ready for QA",
    "projectId": 123,
    "taskCount": 4
  },
  "message": "Section updated successfully"
}

Delete Project Section

Delete a section and move its tasks to the first remaining section.

Endpoint: DELETE /api/v1/projects/{projectId}/sections/{sectionId}

Path parameters:

Parameter	Type	Required	Description
projectId	number	Yes	Project ID
sectionId	number	Yes	Section ID

Example request:

curl -s -X DELETE -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/projects/123/sections/456"

Response shape:

{
  "success": true,
  "message": "Section deleted successfully"
}

Create Project Label

Create a label in a project.

Endpoint: POST /api/v1/projects/{projectId}/labels

Path parameters:

Parameter	Type	Required	Description
projectId	number	Yes	Project ID

Body parameters:

Parameter	Type	Required	Description
name	string	Yes	Label name, 1 to 100 characters. Must be unique in the project.

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Customer"}' \
  "https://app.hypertask.ai/api/v1/projects/123/labels"

Response shape:

{
  "success": true,
  "label": {
    "id": "label_uuid",
    "name": "Customer"
  },
  "message": "Label \"Customer\" created successfully"
}

List Project Members

List project members for mentions and assignment.

Endpoint: GET /api/v1/projects/{projectId}/members

Path parameters:

Parameter	Type	Required	Description
projectId	number	Yes	Project ID

Example request:

curl -s -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/projects/123/members"

Response shape:

{
  "success": true,
  "members": [
    {
      "id": 6,
      "email": "valentin@example.com",
      "displayName": "Valentin"
    }
  ],
  "projectId": 123
}

Add Project Member

Invite or add a project member by email or user ID.

Endpoint: POST /api/v1/projects/{projectId}/members

Path parameters:

Parameter	Type	Required	Description
projectId	number	Yes	Project ID

Body parameters:

Parameter	Type	Required	Description
userToAdd	string or number	Yes	Email address or positive integer user ID

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userToAdd":"teammate@example.com"}' \
  "https://app.hypertask.ai/api/v1/projects/123/members"

Response shape:

{
  "success": true,
  "projectId": 123
}

Create Team Board

Create a board under a team from a structured manifest. Find team IDs with GET /api/v1/user/context.

Endpoint: POST /api/v1/teams/{teamId}/boards

Path parameters:

Parameter	Type	Required	Description
teamId	string	Yes	Team UUID

Headers:

Header	Required	Description
Idempotency-Key	No	Replays with the same key and same body return the cached successful response for 24 hours

Body parameters:

Parameter	Type	Required	Description
title	string	Yes	Board title, 1 to 200 characters
description	string	No	Board description
sections	object[]	Yes	1 to 50 sections. Each item: { "title": string }
labels	object[]	No	Up to 100 labels. Each item: { "name": string, "color"?: string }. color is accepted but not persisted.
tasks	object[]	No	Up to 500 starter tasks
tasks[].title	string	Yes	Task title, 1 to 500 characters
tasks[].description	string	No	HTML task description
tasks[].section_index	number	Conditional	Zero-based section index. Provide this or section_title, not both.
tasks[].section_title	string	Conditional	Section title. Provide this or section_index, not both.
tasks[].label_names	string[]	No	Label names defined in the same manifest
tasks[].priority	number	No	0 No Priority, 1 Urgent, 2 High, 3 Medium, 4 Low
tasks[].estimate	number	No	0 none, 2 XS, 3 S, 4 M, 5 L, 6 XL
tasks[].due_date	string	No	ISO 8601 date or datetime

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: board-import-001" \
  -d '{
    "title": "Launch",
    "sections": [
      { "title": "Todo" },
      { "title": "Done" }
    ],
    "labels": [
      { "name": "Docs" }
    ],
    "tasks": [
      {
        "title": "Draft launch plan",
        "section_index": 0,
        "label_names": ["Docs"],
        "priority": 2
      }
    ]
  }' \
  "https://app.hypertask.ai/api/v1/teams/team_uuid/boards"

Response shape:

{
  "success": true,
  "team_id": "team_uuid",
  "board": {
    "id": 123,
    "title": "Launch"
  },
  "sections": [
    { "id": 456, "title": "Todo" }
  ],
  "labels": [
    { "id": "label_uuid", "name": "Docs" }
  ],
  "tasks": [
    { "id": 789, "ticketNumber": "ENG-42", "title": "Draft launch plan" }
  ],
  "message": "Board created successfully"
}

---

Tasks

List or Get Tasks

List tasks with filters, or fetch tasks by identifier.

Endpoint: GET /api/v1/tasks

Query parameters:

Parameter	Type	Required	Default	Description
task_id	number or CSV	No	—	Get one or more tasks by internal ID
ticket_number	string or CSV	No	—	Get one or more tasks by ticket number
unique_index	number	No	—	Get a task by project-scoped index. Requires project_id.
project_id	number	No	—	Filter by project, or scope ticket_number and unique_index lookup
board_id	number	No	—	Alias for project filtering
section	string	No	—	Filter by section title
assigned_to	string	No	—	me, unassigned, or comma-separated user IDs
priority	string	No	—	Priority value, such as High
has_due_date	boolean	No	—	Filter by due date presence
due_date_before	string	No	—	ISO 8601 date or datetime
due_date_after	string	No	—	ISO 8601 date or datetime
status	string	No	Normal	Normal, Archive, or Deleted
labels	string	No	—	Repeat this parameter for label IDs or label names
created_by	number	No	—	Creator user ID
updated_since	string	No	—	ISO 8601 datetime
created_since	string	No	—	ISO 8601 datetime
has_comments	boolean	No	—	Filter tasks with or without comments
has_attachments	boolean	No	—	Filter tasks with or without attachments
search	string	No	—	Search title, description, or ticket number
limit	number	No	50	Max results, capped at 100
offset	number	No	0	Pagination offset
sort_by	string	No	updatedAt	createdAt, updatedAt, dueDate, priority, or title
sort_order	string	No	desc	asc or desc

Tip

For single-task lookup, use exactly one of task_id, ticket_number, or project_id plus unique_index.

Example request:

curl -s -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/tasks?project_id=123&status=Normal&limit=20"

Response shape:

{
  "success": true,
  "tasks": [
    {
      "id": 789,
      "ticketNumber": "ENG-42",
      "title": "Ship API docs",
      "description": "<p>Publish REST API docs.</p>",
      "section": "Todo",
      "sectionId": 456,
      "boardId": 123,
      "boardTitle": "Engineering",
      "projectId": 123,
      "status": "Normal",
      "priority": "High",
      "dueDate": "2026-03-10T00:00:00.000Z",
      "assigneeCount": 1,
      "labelCount": 1,
      "commentCount": 2,
      "createdAt": "2026-03-01T12:00:00.000Z",
      "updatedAt": "2026-03-02T12:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "metadata": {
    "projectCount": 1,
    "sectionCount": 1
  }
}

Single-task lookups return either { "success": true, "tasks": [...] } or, for a legacy single ticket_number lookup, { "success": true, "task": {...} }.

Create Task

Create a task in a project.

Endpoint: POST /api/v1/tasks/create

Body parameters:

Parameter	Type	Required	Description
project_id	number	Yes	Project ID
title	string	Yes	Task title, 1 to 500 characters
description	string	No	HTML description
section_id	number	No	Section ID. Defaults to the project’s first section.
priority	number	No	0 No Priority, 1 Urgent, 2 High, 3 Medium, 4 Low
estimate	number	No	0 none, 2 XS, 3 S, 4 M, 5 L, 6 XL
due_date	string	No	ISO 8601 date or datetime
images	string[]	No	HTTP or HTTPS image URLs to attach
labels	string[] or number[]	No	Label IDs to assign
parent_task_id	number	No	Parent task ID
assignee	number[]	No	Positive integer user IDs to assign

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 123,
    "title": "Ship API docs",
    "description": "<p>Publish the REST API reference.</p>",
    "section_id": 456,
    "priority": 2
  }' \
  "https://app.hypertask.ai/api/v1/tasks/create"

Response shape:

{
  "success": true,
  "task": {
    "id": 789,
    "ticketNumber": "ENG-42",
    "title": "Ship API docs",
    "description": "<p>Publish the REST API reference.</p>",
    "section": "Todo",
    "sectionId": 456,
    "boardId": 123,
    "projectId": 123,
    "priority": {
      "priority_index": 2,
      "Priority_Value": "High"
    },
    "labels": [],
    "assignees": [],
    "totalComments": 0,
    "createdAt": "2026-03-01T12:00:00.000Z",
    "updatedAt": "2026-03-01T12:00:00.000Z"
  },
  "message": "Task created successfully"
}

Update Tasks

Update one or more tasks.

Endpoint: POST /api/v1/tasks/update

Body parameters:

Parameter	Type	Required	Description
task_id	number or number[]	Conditional	Identify task or tasks by internal ID
ticket_number	string or string[]	Conditional	Identify task or tasks by ticket number
unique_index	number	Conditional	Identify a task by project-scoped index. Requires project_id.
project_id	number	Conditional	Required with unique_index; optional scope for ticket_number
title	string	No	New task title
description	string	No	New HTML description
priority	number	No	0 No Priority, 1 Urgent, 2 High, 3 Medium, 4 Low
estimate	number	No	0 none, 2 XS, 3 S, 4 M, 5 L, 6 XL
sectionId	number	No	Move to a section in the same project
status	string	No	Normal, Archive, or Deleted
labels	string[] or number[]	No	Replace all labels with these label IDs
due_date	string or null	No	ISO 8601 date or datetime, or null to clear
assignee	number[]	No	Positive integer user IDs to assign
parent_task_id	number	No	Parent task ID

Provide exactly one task identification method and at least one field to update.

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_number":"ENG-42","project_id":123,"status":"Archive"}' \
  "https://app.hypertask.ai/api/v1/tasks/update"

Response shape:

{
  "success": true,
  "tasks": [
    {
      "id": 789,
      "ticketNumber": "ENG-42",
      "title": "Ship API docs",
      "status": "Archive",
      "section": "Todo",
      "boardId": 123,
      "projectId": 123,
      "updatedAt": "2026-03-02T12:00:00.000Z"
    }
  ],
  "task": {
    "id": 789,
    "ticketNumber": "ENG-42",
    "status": "Archive"
  },
  "message": "1 task(s) updated successfully"
}

Move Task

Move a task to another project or section.

Endpoint: POST /api/v1/tasks/move

Body parameters:

Parameter	Type	Required	Description
task_id	number	Conditional	Identify task by internal ID
ticket_number	string	Conditional	Identify task by ticket number
project_id	number	Conditional	Required with unique_index
unique_index	number	Conditional	Identify task by project-scoped index
target_project_id	number	Yes	Destination project ID
target_section_id	number	No	Destination section ID. Defaults to the first section in the destination project.

Provide exactly one task identification method.

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":789,"target_project_id":124,"target_section_id":501}' \
  "https://app.hypertask.ai/api/v1/tasks/move"

Response shape:

{
  "success": true,
  "task": {
    "id": 789,
    "ticketNumber": "ENG-42",
    "boardId": 124,
    "projectId": 124,
    "sectionId": 501,
    "section": "Backlog"
  },
  "message": "Task moved successfully"
}

Search Tasks

Search tasks by title, description, or ticket number.

Endpoint: GET /api/v1/tasks/search

Query parameters:

Parameter	Type	Required	Default	Description
q	string	Yes	—	Search query, max 200 characters
board_id	number	No	—	Limit to a board
project_id	number	No	—	Limit to a project
assigned_to	string	No	—	me, unassigned, or a user ID
priority	string	No	—	Priority value, such as High
section	string	No	—	Section title
has_due_date	boolean	No	—	Filter by due date presence
status	string	No	Normal	Normal or Archive
limit	number	No	10	Max results, capped at 50

Example request:

curl -s -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/tasks/search?q=docs&project_id=123&limit=10"

Response shape:

{
  "success": true,
  "tasks": [
    {
      "id": 789,
      "ticketNumber": "ENG-42",
      "title": "Ship API docs",
      "description": "<p>Publish REST API docs.</p>",
      "boardId": 123,
      "boardTitle": "Engineering",
      "projectId": 123,
      "section": "Todo",
      "createdAt": "2026-03-01T12:00:00.000Z"
    }
  ],
  "total": 1,
  "boardId": 123
}

Get Task Tree

Return a task’s family tree from the topmost parent.

Endpoint: GET /api/v1/tasks/tree

Query parameters:

Parameter	Type	Required	Default	Description
task_id	number	Conditional	—	Identify task by internal ID
ticket_number	string	Conditional	—	Identify task by ticket number
depth	number	No	Full subtree	Number of descendant levels to include. 0 returns the root only.

Provide exactly one of task_id or ticket_number.

Example request:

curl -s -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/tasks/tree?ticket_number=ENG-42&depth=2"

Response shape:

{
  "success": true,
  "tree": {
    "id": 700,
    "ticketNumber": "ENG-1",
    "title": "Launch project",
    "uniqueIndex": 1,
    "children": [
      {
        "id": 789,
        "ticketNumber": "ENG-42",
        "title": "Ship API docs",
        "uniqueIndex": 42,
        "children": []
      }
    ]
  }
}

Upload Task Attachments

Upload attachments to a task description, or to a comment when comment_id is provided.

Endpoint: POST /api/v1/tasks/attachments

Body parameters:

Parameter	Type	Required	Description
task_id	number	Conditional	Identify task by internal ID
ticket_number	string	Conditional	Identify task by ticket number
comment_id	number	No	Attach to this comment instead of the task description
files	object[]	Yes	1 to 10 files
files[].filename	string	Yes	Filename, max 255 characters. Must not include path segments.
files[].content_type	string	Yes	One of image/png, image/jpeg, image/webp, image/gif, application/pdf, text/markdown, text/plain
files[].data	string	Conditional	Raw base64 file data
files[].url	string	Conditional	HTTP or HTTPS URL to fetch

Each file must provide exactly one of data or url. Decoded or fetched file size is limited to 15 MB.

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": 789,
    "files": [
      {
        "filename": "brief.txt",
        "content_type": "text/plain",
        "data": "SGVsbG8="
      }
    ]
  }' \
  "https://app.hypertask.ai/api/v1/tasks/attachments"

Response shape:

{
  "success": true,
  "attachments": [
    {
      "id": 9001,
      "fileName": "brief.txt",
      "fileType": "text/plain",
      "fileSize": 5,
      "url": "https://..."
    }
  ]
}

---

Comments

List Comments

List user comments for a task. Activity log entries are excluded.

Endpoint: GET /api/v1/comments

Query parameters:

Parameter	Type	Required	Default	Description
task_id	number	Conditional	—	Identify task by internal ID
ticket_number	string	Conditional	—	Identify task by ticket number
unique_index	number	Conditional	—	Identify task by project-scoped index. Requires project_id.
project_id	number	Conditional	—	Required with unique_index; optional scope for ticket_number
limit	number	No	50	Max results, capped at 100
offset	number	No	0	Pagination offset
sort_order	string	No	desc	asc or desc

Example request:

curl -s -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/comments?ticket_number=ENG-42&project_id=123"

Response shape:

{
  "success": true,
  "comments": [
    {
      "id": 321,
      "text": "<p>Looks good.</p>",
      "commentText": "<p>Looks good.</p>",
      "createdAt": "2026-03-02T12:00:00.000Z",
      "creatorId": 6,
      "creator": {
        "id": 6,
        "email": "valentin@example.com",
        "displayName": "Valentin"
      },
      "attachments": [],
      "reactions": []
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Add Comment

Add a comment to a task. Comment text is HTML.

Endpoint: POST /api/v1/comments

Body parameters:

Parameter	Type	Required	Description
task_id	number	Conditional	Identify task by internal ID
ticket_number	string	Conditional	Identify task by ticket number
unique_index	number	Conditional	Identify task by project-scoped index. Requires project_id.
project_id	number	Conditional	Required with unique_index; optional scope for ticket_number
text	string	Yes	HTML comment text, max 5000 characters
images	string[]	No	HTTP or HTTPS image URLs
mentions	object[]	No	Optional mention metadata. Each item: { "user_id": number, "display_name": string }

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":789,"text":"<p>Looks good.</p>"}' \
  "https://app.hypertask.ai/api/v1/comments"

Response shape:

{
  "success": true,
  "comment": {
    "id": 321,
    "text": "<p>Looks good.</p>",
    "createdAt": "2026-03-02T12:00:00.000Z",
    "creatorId": 6,
    "attachments": []
  }
}

Update Comment

Update your own comment.

Endpoint: PATCH /api/v1/comments/{comment_id}

Path parameters:

Parameter	Type	Required	Description
comment_id	number	Yes	Comment ID

Body parameters:

Parameter	Type	Required	Description
text	string	Yes	HTML comment text, max 5000 characters
mentions	object[]	No	Optional mention metadata. Each item: { "user_id": number, "display_name": string }

Example request:

curl -s -X PATCH -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"<p>Updated comment.</p>"}' \
  "https://app.hypertask.ai/api/v1/comments/321"

Response shape:

{
  "success": true,
  "comment": {
    "id": 321,
    "text": "<p>Updated comment.</p>",
    "createdAt": "2026-03-02T12:00:00.000Z",
    "creatorId": 6
  }
}

Delete Comment

Delete your own comment.

Endpoint: DELETE /api/v1/comments/{comment_id}

Path parameters:

Parameter	Type	Required	Description
comment_id	number	Yes	Comment ID

Example request:

curl -s -X DELETE -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/comments/321"

Response shape:

{
  "success": true,
  "message": "Comment deleted"
}

---

Assignees

Assign or Unassign Users

Assign or unassign one or more project members on a task.

Endpoint: POST /api/v1/assignees/assign

Body parameters:

Parameter	Type	Required	Description
task_id	number	Conditional	Identify task by internal ID
ticket_number	string	Conditional	Identify task by ticket number
project_id	number	Conditional	Required with unique_index; optional scope for ticket_number
unique_index	number	Conditional	Identify task by project-scoped index
user_id	number	Conditional	Single user to assign or unassign
user_ids	number[]	Conditional	Multiple users. Requires mode: "multiple".
mode	string	Conditional	Use multiple with user_ids
intent	string	No	assign or unassign. Defaults to assign.

Provide exactly one task identifier and either user_id or user_ids.

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":789,"user_ids":[12,34],"mode":"multiple","intent":"assign"}' \
  "https://app.hypertask.ai/api/v1/assignees/assign"

Response shape:

{
  "success": true,
  "assignees": [
    { "userId": 12 },
    { "userId": 34 }
  ],
  "assignStatus": "Assigned"
}

---

Inbox

List Inbox Notifications

Return inbox notifications for the user and, when the token is agent-bound, the connected agent.

Endpoint: GET /api/v1/inbox/list

Parameters: None

Example request:

curl -s -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/inbox/list"

Response shape:

{
  "success": true,
  "user_notifications": [
    {
      "id": 1001,
      "status": "Normal",
      "taskId": 789
    }
  ],
  "agent_notifications": []
}

For user-only API keys, agent_notifications may be omitted.

Archive Inbox Notifications

Archive inbox notifications by ID.

Endpoint: POST /api/v1/inbox/archive

Body parameters:

Parameter	Type	Required	Description
notification_ids	number[]	Yes	Non-empty array of notification IDs

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notification_ids":[1001,1002]}' \
  "https://app.hypertask.ai/api/v1/inbox/archive"

Response shape:

{
  "success": true,
  "archived_count": 2
}

---

Drafts

List Drafts

List drafts for a task.

Endpoint: GET /api/v1/drafts

Query parameters:

Parameter	Type	Required	Default	Description
task_id	number	Conditional	—	Identify task by internal ID
ticket_number	string	Conditional	—	Identify task by ticket number
unique_index	number	Conditional	—	Identify task by project-scoped index. Requires project_id.
project_id	number	Conditional	—	Required with unique_index; optional scope for ticket_number

Example request:

curl -s -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/drafts?task_id=789"

Response shape:

{
  "success": true,
  "drafts": [
    {
      "id": 555,
      "taskId": 789,
      "ticketNumber": "ENG-42",
      "draftType": "comment",
      "text": "<p>Draft response.</p>",
      "status": "Draft",
      "updatedAt": "2026-03-02T12:00:00.000Z",
      "createdBy": {
        "id": 6,
        "email": "valentin@example.com",
        "displayName": "Valentin"
      }
    }
  ]
}

Create Draft

Create or replace a description or comment draft for a task.

Endpoint: POST /api/v1/drafts

Body parameters:

Parameter	Type	Required	Description
task_id	number	Conditional	Identify task by internal ID
ticket_number	string	Conditional	Identify task by ticket number
unique_index	number	Conditional	Identify task by project-scoped index. Requires project_id.
project_id	number	Conditional	Required with unique_index; optional scope for ticket_number
draft_type	string	Yes	description or comment
text	string	Yes	HTML draft content

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":789,"draft_type":"comment","text":"<p>Draft response.</p>"}' \
  "https://app.hypertask.ai/api/v1/drafts"

Response shape:

{
  "success": true,
  "draft": {
    "id": 555,
    "taskId": 789,
    "ticketNumber": "ENG-42",
    "draftType": "comment",
    "text": "<p>Draft response.</p>",
    "status": "Draft",
    "updatedAt": "2026-03-02T12:00:00.000Z"
  },
  "message": "Draft created successfully"
}

Update Draft

Update your own draft text.

Endpoint: PATCH /api/v1/drafts/{draft_id}

Path parameters:

Parameter	Type	Required	Description
draft_id	number	Yes	Draft ID

Body parameters:

Parameter	Type	Required	Description
text	string	Yes	HTML draft content

Example request:

curl -s -X PATCH -H "Authorization: Bearer $HT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"<p>Updated draft.</p>"}' \
  "https://app.hypertask.ai/api/v1/drafts/555"

Response shape:

{
  "success": true,
  "draft": {
    "id": 555,
    "taskId": 789,
    "ticketNumber": "ENG-42",
    "draftType": "comment",
    "text": "<p>Updated draft.</p>",
    "status": "Draft",
    "updatedAt": "2026-03-02T12:05:00.000Z"
  },
  "message": "Draft updated successfully"
}

Delete Draft

Delete your own draft.

Endpoint: DELETE /api/v1/drafts/{draft_id}

Path parameters:

Parameter	Type	Required	Description
draft_id	number	Yes	Draft ID

Example request:

curl -s -X DELETE -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/drafts/555"

Response shape:

{
  "success": true,
  "message": "Draft deleted successfully"
}

Publish Draft

Publish a draft into a task description or comments, depending on the draft type.

Endpoint: POST /api/v1/drafts/{draft_id}/publish

Path parameters:

Parameter	Type	Required	Description
draft_id	number	Yes	Draft ID

Example request:

curl -s -X POST -H "Authorization: Bearer $HT_API_KEY" \
  "https://app.hypertask.ai/api/v1/drafts/555/publish"

Response shape:

{
  "success": true,
  "message": "Draft published - comment added to ENG-42"
}