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.

createMention API

The createMention API endpoint now requires a verified authentication session. Mentions are no longer an open push channel that trusts caller-supplied identifiers:

• All requests to POST /api/v1/comments with a mentions array now require verification against the signed ht_session.
• The mentionedBy field in the request is ignored; it is derived automatically from the authenticated user’s session.
• The endpoint validates that the task, the initiator, and the recipient all belong to the same board before creating the mention.
• Attempting to forge mentions or cross-board mentions returns an 401 Unauthorized response.

API user routes require authentication

The following API routes have been secured to require authentication:

• POST /api/resetUser â\x80\x94 admin tool for resetting user state. Takes the same x-admin-password header check as the reset-trial endpoint.
• GET /api/users/search â\x80\x94 searches available users by name or email. Requires a signed ht_session cookie.
• GET /api/users/getByEmails â\x80\x94 returns users matching one or more email addresses. Requires a signed ht_session cookie.
• DELETE /api/v1/projects/{projectId}/members â\x80\x94 removes a project member. Now requires a signed ht_session cookie (not available without authentication).
• Account ownership transfer endpoint that previously accepted unauthenticated requests is now blocked: unauthenticated requests return 401 before any ownership change is attempted.

These routes were previously accessible without an authenticated session. Requests made without valid authentication now receive 401 Unauthorized.

Deprecated and removed endpoints

The following endpoints have been removed as they were not actively used by any client:

• GET /api/comments/getAll â\x80\x94 use GET /api/v1/comments instead.
• GET /api/comments/single â\x80\x94 use GET /api/v1/comments with a specific ticket_number or task_id.
• POST /api/notifications/oneOffUpdateScript â\x80\x94 use the standard notification management endpoints under /api/v1/notifications/ or the app’s ability to schedule notification preferences.

Knowing these endpoints were already unused, this change does not affect integrations.

---