API and Webhooks

Truetask exposes a full REST API for programmatic access and outgoing webhooks for event-driven integrations. Between them, you can automate data flows, build dashboards, forward events to other tools, and connect Truetask to the rest of your stack.

Pro or Enterprise required

API tokens and webhooks are available with a Pro or Enterprise license.

API Tokens

API tokens authenticate programmatic requests. They're tied to a user and carry that user's permissions.

Creating a token

1. Open Settings → Integrations → API Tokens
2. Click Create Token
3. Give it a name
4. Set an optional expiration date (the default is no expiration)
5. Choose a scope:
   • Read — list and read data only
   • Read + Write — create, update, and delete too
6. Click Create
7. Copy the token — it's shown only once

Using a token

Include the token in the Authorization header of every request:

Authorization: Bearer YOUR_TOKEN_HERE

Requests without a token, or with an invalid or expired token, receive 401 Unauthorized.

Example request

curl https://your-instance.com/v1/boards \
  -H "Authorization: Bearer tt_your_token_here"

Response:

{
  "items": [
    { "id": "abc123", "name": "Website Redesign", "active": true },
    { "id": "def456", "name": "Q2 Marketing", "active": true }
  ]
}

Managing tokens

The token list shows all active tokens with name, scope, creation date, and expiration. Click the delete icon to revoke a token — revocation takes effect immediately.

REST API

The API follows REST conventions and returns JSON responses.

Base URL

https://your-instance.com/v1/

Available endpoints

Full CRUD operations for every major entity:

Resource	Endpoint
Boards	/v1/boards
Lists	/v1/lists
Cards (tasks)	/v1/cards
Tags	/v1/tags
Comments	/v1/comments
Checklists	/v1/checklists
Files	/v1/files
Members	/v1/users
Custom fields	/v1/xattr
Automations	/v1/automations
Time entries	/v1/time_entries
Saved filters	/v1/saved_filters
Milestones	/v1/milestones
Search	/v1/search

Interactive Docs

Truetask ships with interactive API documentation:

• Swagger UI — https://your-instance.com/v1/docs
• ReDoc — https://your-instance.com/v1/redoc

Both show every endpoint with request/response schemas and let you try calls directly in the browser.

Rate Limiting

When enabled, rate-limited requests receive 429 Too Many Requests with a Retry-After header telling you how long to wait. Defaults are generous — most applications won't hit them in normal use.

Errors

Standard HTTP status codes:

Code	Meaning
200	Success
201	Created
400	Invalid request (malformed JSON, missing required fields)
401	Unauthorized (missing or invalid token)
403	Forbidden (valid token, but no permission for this action)
404	Not found
429	Rate limited
500	Server error

Errors return a JSON body with error and message fields when possible.

Webhooks

Webhooks let Truetask notify your systems when things happen — new tasks, status changes, comments, and more. Each event fires an HTTP POST to the URL you configure.

Creating a webhook

1. Open Settings → Integrations → Webhooks
2. Click Create Webhook
3. Enter the target URL (must be HTTPS in production)
4. Select the events to subscribe to
5. Optionally restrict to specific boards
6. Save

Event types

Category	Events
Cards	Created, updated, completed, moved, archived, deleted
Comments	Created, updated, deleted
Lists	Created, updated, deleted
Members	Added, removed
Tags	Added, removed
Boards	Updated, deleted
Checklists	Item created, completed, deleted
Files	Uploaded, deleted
Automations	Executed

Payload format

Every webhook delivery includes:

{
  "event": "card.created",
  "timestamp": "2026-04-17T14:23:00Z",
  "actor": {
    "id": "user_abc123",
    "name": "Alice",
    "email": "[email protected]"
  },
  "data": {
    "id": "card_xyz789",
    "title": "Review pull request",
    "board_id": "board_123",
    "list_id": "list_456",
    ...
  }
}

Security

Webhook payloads are signed with HMAC-SHA256. The signature is sent in the X-Webhook-Signature header.

To verify a delivery, compute HMAC-SHA256(request_body, your_webhook_secret) on your server and compare it to the header value. Discard any request where the signatures don't match.

Example (Node.js):

const crypto = require('crypto')

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Delivery logs

Each webhook shows a delivery history with:

• Timestamp
• HTTP status code from your endpoint
• Response time
• Full payload (expandable)

Failed deliveries are retried automatically with exponential backoff.

SIEM Forwarding

For audit-focused deployments, webhooks can forward security-relevant events to your SIEM. Subscribe to events like login, member changes, and board access and pipe the payloads into Splunk, Datadog, or similar.

Tips

• Use Read tokens for dashboards and monitoring — they can't modify anything even if accidentally exposed
• Rotate tokens regularly by setting expiration dates on automated systems
• Test webhooks with a service like webhook.site or ngrok before pointing them at production endpoints
• Webhook delivery logs are retained based on your workspace's data retention settings
• Use the interactive API docs to explore available fields before integrating