Read and change Tasks over HTTP: Spaces with their Folders, lists, members, statuses, cycles, milestones and custom fields; tasks with their comments, activity, the Bin and export; and outgoing webhooks that send a Space's events to your own service. Every request uses a developer key as a bearer token on https://api.projecthollow.com.
POST /v1/tasks, the create route for scripts and forms. It does not imply tasks-manage:*.tasks-boards-share:* hold it as an alias.A key without the scope a route needs gets 403 INSUFFICIENT_SCOPE. A key acts as the person who minted it, with their role in each Space: owner, admin, member, guest or viewer.
Wherever a path has :ref, send the task id, its key (WRK-12) or an older key (TSK-AB12CD, or a key from Jira or Linear kept by an import). Keys follow the task when its Space key changes or it moves to another Space.
Boards are now Folders and shared boards are now Spaces. Every /v1/boards and /v1/shared-boards route answers 410; use /v1/task-spaces instead, and version 0.15.0 or later of the Hollow CLI.
HTTP/1.1 410 Gone
{
"error": {
"code": "GONE",
"status": 410,
"message": "Boards are now Folders and shared boards are now Spaces. Use /v1/task-spaces.",
"upgrade": { "cli": ">=0.15.0", "docs": "https://www.projecthollow.com/docs/api/tasks" }
}
}During a planned upgrade every Tasks route answers 503 with reason: "FROZEN" and a Retry-After header in seconds. Retry after that time; nothing you sent was applied.
Every route needs tasks-manage:*. Bodies and answers are JSON; dates are YYYY-MM-DD and times HH:mm. Lists of items are paged with limit and cursor, answering { "items": [ … ], "nextCursor": "…" | null }. Wherever a route takes a Space id (spaceId, spaceIds) you can give the Space's key instead, current or older, in any case, or ME for your personal Space.
spaceId, includeArchive (default true), q (an HEL filter), limit, cursor.{ task, space, via, statuses, people }: the task, a summary of its Space, whether it was found by id, key or an older key, the Space's statuses in workflow order ({ id, label, category }), and the names of the task's assignees, creator and watchers by user id.text, descriptionHtml, priority, dueDate, dueTime, startDate, tags, assigneeIds, estimate, fields, checklist, recurrence and the rest of a task's editable fields, plus status (checked against the Space's statuses and workflow) and listId (a list of the same Space). Answers { task }.{ task, rescheduled: true }.{ on: true | false }: stars or unstars the task for you alone (viewers may). Answers { task }; nothing changes when the star is already as asked. A task in the Bin answers 404.{ archived: true, taskId }.listId when given.{ spaceId, listId, rank? }: to another list or Space. A task moved to another Space gets a key there; the old key keeps working.{ trashed: true, taskId, batchId, restorableUntil }. Anyone but the Space owner can move at most 50 tasks to the Bin in 10 minutes.people, the names of their authors by user id; add one with { body, parentId?, visibility? } (201 { comment }). With an Idempotency-Key header a repeat of your key on the same task writes nothing and answers 200 { comment, duplicate: true } with the first comment; the same key with different text answers 409 IDEMPOTENCY_KEY_REUSED.{ resolved }; delete it.spaceId narrows it.:id is a batch id, an item id, or a task's key, which restores that task alone. Tasks go back to their list, or to the Space's default list when their list is gone.:id as for restore. Deletes forever: { deleted }. Members delete only what they moved to the Bin; owners and admins delete anything.{ spaceIds?, format: "json" | "csv" }. Answers { url, expiresAt }, a download link that works for an hour. JSON holds every Space in full; CSV is one row per task.{ spaceId, taskId, key, alias }; alias is true for an older key.Older clients still read boards, sharedBoards, lists[].boardId, tasks[].ticketKey and subtasksDone and subtasksTotal in the answer of GET /v1/tasks. They are kept until 1 April 2027; use folders, folderId, key and checklistDone and checklistTotal.
Create one task. This route needs tasks:*, so a key for scripts and forms can create tasks without reading or changing anything else. text (or title) is required.
descriptionHtml takes rich text instead.ENG, or ME for your personal Space). Optional: without it the list decides, else your Inbox.listId), by name (listName, matched exactly but in any case, live lists only), or either (list: the list with that id if there is one, else the name). Optional. With spaceId the list is looked up in that Space; without it, across every Space you can add tasks to. An id or name that matches more than one list, in one Space or several, is refused with AMBIGUOUS_LIST and the candidates (see below): send spaceId or the list id to choose. A list that is not found falls back to the Space's default list (your Inbox without spaceId) and the answer says misrouted: true.true the list must be named with listId, listName or list (400 INVALID_REQUEST otherwise), and a list that is not found is refused with 404 NOT_FOUND (LIST_NOT_FOUND) instead of falling back.low, medium, high or urgent; task, bug or epic. Optional.YYYY-MM-DD) and a time (HH:mm). Optional.[{ "text": "…" }], a parent task, an estimate, custom field values by field id, and a repeat rule. Optional.Idempotency-Key header). Optional.Example request
curl -X POST https://api.projecthollow.com/v1/tasks \
-H "Authorization: Bearer hlw_sk_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: deploy-9876" \
-d '{
"text": "Investigate checkout latency regression",
"description": "p95 latency doubled after the last release",
"list": "Engineering",
"priority": "high",
"labels": ["perf"]
}'{ "id": "…", "key": "ENG-42", "spaceId": "…", "folderId": "…", "listId": "…" }, with "misrouted": true when the default list was used."duplicate": true.LIST_NOT_FOUND: with requireListMatch: true, no live list has that id or name. Also a spaceId that names no Space you are in."reason": "AMBIGUOUS_LIST" when the list id or name matches more than one list. details.candidates lists them, each { spaceId, spaceName, listId, listName }; send one of them back as spaceId and listId.{
"error": {
"code": "FAILED_PRECONDITION",
"status": 409,
"message": "That list exists in more than one Space; name the Space",
"reason": "AMBIGUOUS_LIST",
"details": {
"candidates": [
{ "spaceId": "…", "spaceName": "Engineering", "listId": "…", "listName": "Bugs" },
{ "spaceId": "…", "spaceName": "Support", "listId": "…", "listName": "Bugs" }
]
}
}
}A Space holds Folders and lists, its own statuses and workflow, its members and their roles. Lists sit in a Folder or directly in the Space. Every route needs tasks-manage:* except membership, which needs tasks-share:*. Changing a Space's settings, statuses, fields and request types needs the owner or an admin.
{ spaces }. Create one with { name, key?, icon?, color?, preset? } (preset is simple, software or support): 201 { space }.{ space, folders, lists, statuses }; change name, icon, color, description, statuses, workflow or settings; move it to the Bin (the owner): { trashed: true, restorableUntil }.{ deleted }, the number of items deleted.{ key }. Old task keys keep resolving.tasks-share:*. { members: [{ uid, email?, name, role }] }; invite with { email, role }, where role is member, guest or viewer.tasks-share:*. Change a role with { role } (only the owner grants admin), or remove the member.tasks-share:*. Leave the Space, or (the owner) hand it to { uid }.{ folders }; create with { name, icon?, color? }. POST …/folders/reorder takes { orderedFolderIds }.POST …/folders/:folderId/move with { toSpaceId } moves it to another Space.{ lists }; create with { name, folderId?, icon? }. POST …/lists/reorder takes { orderedListIds, folderId? }.folderId (null for the Space itself); move to the Bin with its tasks. With { toSpaceId, folderId? } and nothing else, PATCH moves the list and its tasks to another Space, to its root or to folderId there, after its other lists: { list, tasksMoved }. Send any other change in its own request. The Inbox cannot be moved or trashed.{ name?, goal?, startDate, endDate }; change one at …/cycles/:cycleId.…/milestones/:milestoneId.…/fields/:fieldId.…/request-types/:requestTypeId.A webhook sends a Space's events to your service as a signed POST. Owners and admins manage them in Space settings, Webhooks, or over HTTP with tasks-manage:*. The address must be https and resolve to a public address.
{ webhooks }. The signing secret is never listed.{ url, events, active, description? } with 1 to 20 events. Answers 201 { webhook, secret }: keep the secret, it is shown only here.url, events, active or description: { webhook }. Turning a webhook on again clears its failures. Delete it with its secret.{ secret }, the new secret; the old one stops working at once.event, state (pending, delivered, failed or abandoned), attempts, nextAttemptAt, lastStatus and lastError. Deliveries are kept for 30 days.changedFields names them.from and to carry the statuses and categories.recurring and occurrence.added and removed.from.commentId, commentAuthorId, visibility.restoredFrom).deletedBy, trashBatchId); deleted forever (purgedBy).POST https://hooks.example.com/tasks
Content-Type: application/json
Hollow-Event: tasks.task_completed
Hollow-Delivery: 7f3c…_wh_12
Hollow-Signature: t=1760262000,v1=5d41402abc4b2a76b9719d911017c592…
{
"id": "7f3c…",
"type": "tasks.task_completed",
"createdAt": "2026-10-12T09:40:00.000Z",
"spaceId": "…",
"data": {
"spaceId": "…", "folderId": "…", "listId": "…", "taskId": "…",
"key": "WRK-12", "title": "Ship the release notes",
"status": "completed", "statusCategory": "done", "priority": "high", "type": "task",
"parentId": "", "assigneeIds": ["…"], "createdBy": "…", "dueDate": "2026-10-12",
"actorId": "…", "actorKind": "member",
"recurring": false
}
}id is the event's id, the same for every webhook that receives it; Hollow-Delivery is unique to one webhook and stays the same across retries, so use it to ignore a delivery you have already handled. Empty values in data are "". data.boardId is kept for older filters until 1 April 2027.
Hollow-Signature is t=<unix seconds>,v1=<hex>, where the hex is the HMAC-SHA256 of t + "." + body with the webhook's secret. Compute it over the raw body exactly as received, compare in constant time, and refuse a timestamp more than five minutes old.
import { createHmac, timingSafeEqual } from 'node:crypto'
export function verifyHollowSignature(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const t = Number(parts.t)
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false
const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
const given = Buffer.from(parts.v1 ?? '', 'hex')
return given.length === 32 && timingSafeEqual(given, Buffer.from(expected, 'hex'))
}2xx within 10 seconds. Redirects are not followed and a body larger than 64 KiB is not sent.abandoned) after 8 attempts.taskId.Tasks errors use the standard error body. Where it helps you decide what to do next, reason says why.
{ "error": { "code": "RESOURCE_LIMIT_EXCEEDED", "status": 429, "reason": "BULK_GUARD", "message": "…" } }reason: TRANSITION_NOT_ALLOWED (the Space's workflow does not allow that status change), SPACE_KEY_TAKEN, AMBIGUOUS_KEY, AMBIGUOUS_LIST, INBOX_PROTECTED, PERSONAL_SPACE, SPACE_DELETED. A conflict with another change at the same time can be retried. IDEMPOTENCY_KEY_REUSED: the Idempotency-Key was already used for a different comment; use a new key./v1/task-spaces.reason: "BULK_GUARD" when more than 50 tasks would go to the Bin in 10 minutes (ask the Space owner), "LIMIT" for Spaces, members, lists or Folders.reason: "FROZEN" during an upgrade, with Retry-After.Inbound webhook URL for integrating external services (such as GitHub, Zapier or custom scripts). Create a hook in Tasks under Intake, Hooks, and map incoming JSON paths to task attributes. To send events out of Tasks, see Outgoing webhooks above.
https://api.projecthollow.com/hook/{hookId}?token=hook_…The unguessable security token can be supplied via query parameter or X-Hollow-Token header.
Define automated intake routing rules using HEL expression predicates evaluated against incoming task payloads.
Supported rule fields include title, description, priority, label, emaildomain and source.
title:billing OR title:invoice → Route to "Finance" list priority>=high emaildomain:acme.com → Route to "VIP Support" list