Quickstart

Prerequisites

• A ProductCraft account with an API key
• Any HTTP client (curl, fetch, Postman, etc.)

Step 1

Create a Workspace

A Workspace is the top-level container. It maps to a team, an organization, or a customer in a multi-tenant product. All projects, cards, and labels live inside a Workspace.

curl -X POST https://api.productcraft.co/tack/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-eng",
    "display_name": "Acme Engineering"
  }'

Response:

{
  "id": "ws_01HQ3...",
  "name": "acme-eng",
  "display_name": "Acme Engineering",
  "created_at": "2026-02-20T10:00:00Z"
}

Step 2

Create a Project with Lists

A Project is a named board. You can seed it with Lists (columns) at creation time. Lists define the stages in your workflow.

curl -X POST https://api.productcraft.co/tack/v1/workspaces/acme-eng/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "q1-roadmap",
    "display_name": "Q1 Roadmap",
    "lists": [
      { "name": "backlog", "display_name": "Backlog" },
      { "name": "in-progress", "display_name": "In Progress" },
      { "name": "review", "display_name": "Review" },
      { "name": "done", "display_name": "Done" }
    ]
  }'

Response:

{
  "id": "proj_01HQ3...",
  "workspace_id": "ws_01HQ3...",
  "name": "q1-roadmap",
  "display_name": "Q1 Roadmap",
  "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": "review", "display_name": "Review", "position": 2 },
    { "id": "list_01HQ3D...", "name": "done", "display_name": "Done", "position": 3 }
  ],
  "created_at": "2026-02-20T10:01:00Z"
}

Step 3

Create Labels

Labels are workspace-level tags you can attach to any card. Create a few to categorize your work.

curl -X POST https://api.productcraft.co/tack/v1/workspaces/acme-eng/labels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backend",
    "color": "#3b82f6"
  }'

Response:

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

Step 4

Create a Card

A Card is a unit of work. It lives in a specific List, carries a title and markdown body, and can have assignees, labels, a priority, and a due date.

curl -X POST https://api.productcraft.co/tack/v1/workspaces/acme-eng/projects/q1-roadmap/cards \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Integrate payment provider",
    "body": "Set up Stripe checkout flow for the billing page.\n\n## Acceptance criteria\n- Checkout session creation\n- Webhook handler for payment events\n- Success and failure redirects",
    "list": "backlog",
    "priority": "high",
    "assignees": ["usr_01HQ3..."],
    "labels": ["backend"],
    "due_at": "2026-03-15T00:00:00Z"
  }'

Response:

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

Step 5

Move a Card and Add a Comment

When work starts, move the card to the next list. Add a comment to leave context for your team (or your AI agent).

# Move the card to "In Progress"
curl -X POST https://api.productcraft.co/tack/v1/workspaces/acme-eng/projects/q1-roadmap/cards/card_01HQ3.../move \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "list": "in-progress",
    "position": 0
  }'

# Add a comment
curl -X POST https://api.productcraft.co/tack/v1/workspaces/acme-eng/projects/q1-roadmap/cards/card_01HQ3.../comments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Started implementation. Using Stripe Checkout Sessions API. ETA: 2 days."
  }'

Comment response:

{
  "id": "cmt_01HQ3...",
  "card_id": "card_01HQ3...",
  "author_id": "usr_01HQ3...",
  "body": "Started implementation. Using Stripe Checkout Sessions API. ETA: 2 days.",
  "created_at": "2026-02-20T10:05:00Z"
}

Query the activity feed

Every action you took in this quickstart was recorded in the activity feed. Query it to see the full history of your project.

GET https://api.productcraft.co/tack/v1/workspaces/acme-eng/projects/q1-roadmap/activity?limit=5

The activity feed returns every card creation, move, update, and comment in chronological order. Use it for audit trails, AI agent context, or building your own change log.