Taskbox

Docs

Step-by-step walkthroughs for working with Taskbox.

Create tasks via API

External systems - agents, n8n flows, scripts - push work into a Taskbox workspace by POSTing to /api/v1/tasks. Each task carries a callback URL that Taskbox calls back when a workspace member resolves it.

Authentication

Requests are authenticated with a workspace API key. Create one from Settings → API keys; the key and its HMAC signing secret are shown once on creation - store them somewhere safe.

Authorization: Bearer YOUR_API_KEY

Endpoint

POST /api/v1/tasks
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: optional-client-generated-id

Request payload

title string, 1–255 chars Required

Short summary shown in the task list.

callback_url absolute URL Required

Where Taskbox POSTs the resolution. Must start with http:// or https://. HMAC-signed with your API key's secret.

assigned_to_emails string[], at least 1 Required

Workspace members allowed to resolve the task. All emails must already belong to the workspace, otherwise the request is rejected with 400. Any assignee can resolve - first wins.

description string Optional

Longer context shown on the task detail page.

priority low | medium | high | urgent Optional

Defaults to medium when omitted.

expires_at RFC3339 timestamp Optional

Optional deadline. Once it passes, the task is marked expired on next read and no callback fires.

metadata JSON object, max 64KB Optional

Freeform key/value bag. Pass anything your workflow needs - order IDs, customer details, links - and Taskbox echoes it back on the callback.

Idempotency

Send an Idempotency-Key header (any string, max 255 chars) to make retries safe. If the same key was already processed, Taskbox returns the original task with 200 OK instead of creating a duplicate.

Example request

curl -X POST https://taskbox.dev/api/v1/tasks \
  -H "Authorization: Bearer $TASKBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Approve refund for order #4821",
    "description": "Customer requested a $240 refund. Policy - $200 without review.",
    "priority": "high",
    "assigned_to_emails": ["[email protected]"],
    "callback_url": "https://n8n.acme.com/webhook/Qmf4ug",
    "metadata": {
      "order_id": "4821",
      "amount_usd": 240
    }
  }'

Successful response

201 Created on a new task, 200 OK on an idempotent replay.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "0193c8e1-1aa4-7b21-9f31-2c6b8d4e0a10",
  "workspace_id": "0193c8e0-9cf2-7b21-9f31-1f4b8d4e0a10",
  "title": "Approve refund for order #4821",
  "description": "Customer requested a $240 refund...",
  "callback_url": "https://n8n.acme.com/webhook/Qmf4ug",
  "priority": "high",
  "status": "pending",
  "assigned_to_emails": ["[email protected]"],
  "metadata": {"order_id": "4821", "amount_usd": 240},
  "created_at": "2026-05-03T14:32:00Z"
}

Errors

  • 400 - validation failed (missing field, unknown assignee, bad URL, invalid metadata JSON).
  • 401 - missing, invalid, or revoked API key.
  • 403 - workspace is archived or inactive.
  • 413 - metadata exceeds 64KB.
  • 429 - per-minute rate limit or open-task cap hit. Honor the Retry-After header.

Error bodies are JSON: {"error": "..."}.

Next steps

After a task is created, watch your callback_url for the resolution payload. Failed deliveries surface on the in-app Monitoring page once you sign in.