← Tack Docs

API Reference

Every Tack endpoint documented with request and response examples. All paths are relative to the base URL: https://api.productcraft.co/tack

Common headers

  • Authorization: Bearer YOUR_API_KEY for all operations
  • Content-Type: application/json for all request bodies

Error responses

All errors follow a consistent shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title is required",
    "details": [
      { "field": "title", "reason": "required" }
    ]
  }
}

HTTP status codes follow standard conventions: 400 for validation errors, 401 for missing or invalid credentials, 403 for insufficient permissions, 404 for not found, 409 for conflicts (e.g., duplicate names), and 429 for rate limiting.

Filtering cards

The list cards endpoint accepts query parameters for filtering:

  • list - Filter by list name or ID
  • label - Filter by label name (repeatable for multiple labels)
  • priority - Filter by priority level
  • assignee - Filter by assignee user ID
  • completed - Filter by completion status (true/false)
  • q - Full-text search across card titles and bodies
GET /v1/workspaces/acme-eng/projects/q1-roadmap/cards?label=backend&priority=high&completed=false

Workspaces

Manage top-level containers. Each Workspace is an isolated namespace containing its own projects, labels, and activity.

POST
/v1/workspaces

Create a new Workspace

GET
/v1/workspaces

List all Workspaces

GET
/v1/workspaces/:workspace

Get a Workspace by name or ID

PATCH
/v1/workspaces/:workspace

Update a Workspace

DELETE
/v1/workspaces/:workspace

Archive a Workspace

Example: Create a Workspace

Request

POST /v1/workspaces
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "name": "acme-eng",
  "display_name": "Acme Engineering",
  "metadata": {
    "plan": "team",
    "region": "us-east-1"
  }
}

Response

{
  "id": "ws_01HQ3KXFG6...",
  "name": "acme-eng",
  "display_name": "Acme Engineering",
  "metadata": {
    "plan": "team",
    "region": "us-east-1"
  },
  "created_at": "2026-02-20T10:00:00Z",
  "updated_at": "2026-02-20T10:00:00Z"
}

Projects

Manage boards within a Workspace. Each Project contains Lists and Cards.

POST
/v1/workspaces/:ws/projects

Create a project (optionally with initial lists)

GET
/v1/workspaces/:ws/projects

List projects in a Workspace

GET
/v1/workspaces/:ws/projects/:project

Get a project by name or ID

PATCH
/v1/workspaces/:ws/projects/:project

Update a project

DELETE
/v1/workspaces/:ws/projects/:project

Archive a project

Example: Create a project with lists

Request

POST /v1/workspaces/acme-eng/projects
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "name": "q1-roadmap",
  "display_name": "Q1 Roadmap",
  "lists": [
    { "name": "backlog", "display_name": "Backlog" },
    { "name": "in-progress", "display_name": "In Progress" },
    { "name": "done", "display_name": "Done" }
  ]
}

Response

{
  "id": "proj_01HQ3KXFG6...",
  "workspace_id": "ws_01HQ3KXFG6...",
  "name": "q1-roadmap",
  "display_name": "Q1 Roadmap",
  "status": "active",
  "lists": [
    { "id": "list_01HQ3A...", "name": "backlog", "display_name": "Backlog", "position": 0 },
    { "id": "list_01HQ3B...", "name": "in-progress", "display_name": "In Progress", "position": 1 },
    { "id": "list_01HQ3C...", "name": "done", "display_name": "Done", "position": 2 }
  ],
  "created_at": "2026-02-20T10:01:00Z",
  "updated_at": "2026-02-20T10:01:00Z"
}

Lists

Manage columns within a Project. Lists have a position that determines their order on the board.

POST
/v1/workspaces/:ws/projects/:proj/lists

Create a list

GET
/v1/workspaces/:ws/projects/:proj/lists

List all lists in a project

PATCH
/v1/workspaces/:ws/projects/:proj/lists/:list

Update a list (name, position)

DELETE
/v1/workspaces/:ws/projects/:proj/lists/:list

Delete a list (cards must be moved first)

Example: Create a list

Request

POST /v1/workspaces/acme-eng/projects/q1-roadmap/lists
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "name": "blocked",
  "display_name": "Blocked",
  "position": 2
}

Response

{
  "id": "list_01HQ3E...",
  "project_id": "proj_01HQ3KXFG6...",
  "name": "blocked",
  "display_name": "Blocked",
  "position": 2,
  "created_at": "2026-02-20T10:05:00Z"
}

Cards

Create and manage units of work. Cards live in Lists and carry titles, descriptions, assignees, labels, priorities, and due dates.

POST
/v1/workspaces/:ws/projects/:proj/cards

Create a card

GET
/v1/workspaces/:ws/projects/:proj/cards

List cards (filterable by list, label, priority, assignee)

GET
/v1/workspaces/:ws/projects/:proj/cards/:card_id

Get a card by ID

PATCH
/v1/workspaces/:ws/projects/:proj/cards/:card_id

Update a card

DELETE
/v1/workspaces/:ws/projects/:proj/cards/:card_id

Archive a card

POST
/v1/workspaces/:ws/projects/:proj/cards/:card_id/move

Move a card to a different list or position

POST
/v1/workspaces/:ws/projects/:proj/cards/batch-move

Move up to 100 cards in a single request

POST
/v1/workspaces/:ws/projects/:proj/cards/:card_id/complete

Mark a card as complete

Example: Create a card

Request

POST /v1/workspaces/acme-eng/projects/q1-roadmap/cards
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "title": "Integrate payment provider",
  "body": "Set up Stripe checkout flow for the billing page.",
  "list": "backlog",
  "priority": "high",
  "assignees": ["usr_01HQ3..."],
  "labels": ["backend", "billing"],
  "due_at": "2026-03-15T00:00:00Z"
}

Response

{
  "id": "card_01HQ3KXFG6...",
  "project_id": "proj_01HQ3KXFG6...",
  "list_id": "list_01HQ3A...",
  "title": "Integrate payment provider",
  "body": "Set up Stripe checkout flow for the billing page.",
  "priority": "high",
  "position": 0,
  "assignees": ["usr_01HQ3..."],
  "labels": ["backend", "billing"],
  "due_at": "2026-03-15T00:00:00Z",
  "completed_at": null,
  "metadata": {},
  "created_at": "2026-02-20T10:03:00Z",
  "updated_at": "2026-02-20T10:03:00Z"
}

Comments

Post and retrieve comments on Cards. Comments are append-only and markdown-formatted.

POST
/v1/workspaces/:ws/projects/:proj/cards/:card_id/comments

Add a comment to a card

GET
/v1/workspaces/:ws/projects/:proj/cards/:card_id/comments

List comments on a card

Example: Add a comment

Request

POST /v1/workspaces/acme-eng/projects/q1-roadmap/cards/card_01HQ3.../comments
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "body": "Stripe integration complete. Moving to review."
}

Response

{
  "id": "cmt_01HQ3KXFG6...",
  "card_id": "card_01HQ3KXFG6...",
  "author_id": "usr_01HQ3...",
  "body": "Stripe integration complete. Moving to review.",
  "created_at": "2026-02-20T14:30:00Z"
}

Labels

Manage workspace-level tags that can be applied to cards across all projects.

POST
/v1/workspaces/:ws/labels

Create a label

GET
/v1/workspaces/:ws/labels

List all labels in a Workspace

PATCH
/v1/workspaces/:ws/labels/:label

Update a label

DELETE
/v1/workspaces/:ws/labels/:label

Delete a label

Example: Create a label

Request

POST /v1/workspaces/acme-eng/labels
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "name": "backend",
  "color": "#3b82f6"
}

Response

{
  "id": "lbl_01HQ3KXFG6...",
  "workspace_id": "ws_01HQ3KXFG6...",
  "name": "backend",
  "color": "#3b82f6",
  "created_at": "2026-02-20T10:02:00Z"
}

Activity

Query the immutable activity log. Every card creation, move, update, and comment is recorded.

GET
/v1/workspaces/:ws/projects/:proj/activity

List activity for a project (paginated, filterable)

GET
/v1/workspaces/:ws/projects/:proj/cards/:card_id/activity

List activity for a specific card

Example: Query project activity

Request

GET /v1/workspaces/acme-eng/projects/q1-roadmap/activity?action=card.moved&limit=10
Authorization: Bearer YOUR_API_KEY

Response

{
  "data": [
    {
      "id": "act_01HQ3KXFG6...",
      "project_id": "proj_01HQ3KXFG6...",
      "card_id": "card_01HQ3KXFG6...",
      "actor_id": "usr_01HQ3...",
      "action": "card.moved",
      "changes": {
        "list_id": {
          "from": "list_01HQ3A...",
          "to": "list_01HQ3B..."
        }
      },
      "timestamp": "2026-02-20T11:00:00Z"
    }
  ],
  "pagination": {
    "total": 23,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Webhooks

Register endpoints to receive real-time event notifications when cards are created, moved, completed, or commented on.

POST
/v1/workspaces/:ws/webhooks

Register a webhook endpoint

GET
/v1/workspaces/:ws/webhooks

List registered webhooks

PATCH
/v1/workspaces/:ws/webhooks/:webhook_id

Update a webhook (URL, events, active status)

DELETE
/v1/workspaces/:ws/webhooks/:webhook_id

Delete a webhook

Example: Register a webhook

Request

POST /v1/workspaces/acme-eng/webhooks
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "url": "https://your-app.com/webhooks/tack",
  "events": ["card.created", "card.moved", "card.completed"],
  "secret": "whsec_your_signing_secret"
}

Response

{
  "id": "whk_01HQ3KXFG6...",
  "workspace_id": "ws_01HQ3KXFG6...",
  "url": "https://your-app.com/webhooks/tack",
  "events": ["card.created", "card.moved", "card.completed"],
  "active": true,
  "created_at": "2026-02-20T10:10:00Z"
}

Rate Limiting

API requests are rate limited per API key. Current limits:

  • Write endpoints: 200 requests per minute
  • Read endpoints: 600 requests per minute
  • Batch operations: 30 requests per minute

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Pagination

List endpoints support offset-based pagination with the following query parameters:

  • limit - Number of items per page (default 50, max 100)
  • offset - Number of items to skip (default 0)

All list responses include a pagination object with total, limit, offset, and has_more.

Quickstart guideIntegration guides