Work Items API

Create and manage tasks, bugs, stories, and other work items.

Overview

Work items are the core units of work in Fairlx. They can represent tasks, bugs, stories, epics, or custom types. Each work item belongs to a project and can be assigned to team members.

Work Item Properties

Field	Type	Description
title	string	Work item title
type	string	TASK, BUG, STORY, EPIC, etc.
status	string	BACKLOG, TODO, IN_PROGRESS, IN_REVIEW, DONE
priority	string	LOW, MEDIUM, HIGH, URGENT
assigneeIds	string[]	Array of member IDs
labels	string[]	Array of label strings
sprintId	string	Sprint ID if assigned

List Work Items

Retrieve work items with optional filters.

Request

bash

GET /api/tasks?workspaceId=ws_abc123&projectId=proj_xyz&status=IN_PROGRESS

curl -X GET "https://api.fairlx.com/v1/tasks?workspaceId=ws_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

workspaceId (required) — Filter by workspace
projectId — Filter by project
status — Filter by status
assigneeId — Filter by assignee
priority — Filter by priority
labels — Comma-separated labels
dueDate — Filter by due date

Response

json

{
  "data": {
    "documents": [
      {
        "$id": "wi_001",
        "key": "MOB-1",
        "title": "Implement user authentication",
        "type": "TASK",
        "status": "IN_PROGRESS",
        "priority": "HIGH",
        "description": "Add OAuth2 authentication flow",
        "assigneeIds": ["member_001"],
        "labels": ["auth", "security"],
        "dueDate": "2024-02-15",
        "estimatedHours": 8,
        "storyPoints": 5,
        "flagged": false,
        "sprintId": "sprint_001",
        "projectId": "proj_xyz789",
        "workspaceId": "ws_abc123",
        "project": { ... },
        "assignees": [ ... ],
        "commentCount": 3
      }
    ],
    "total": 1
  }
}

Get Work Item

Retrieve a single work item with full details.

Request

bash

GET /api/tasks/:taskId

curl -X GET "https://api.fairlx.com/v1/tasks/wi_001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Work Item

Create a new work item. Auto-assigns to active sprint if available.

Request

bash

POST /api/tasks
Content-Type: application/json

curl -X POST "https://api.fairlx.com/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Implement user authentication",
    "workspaceId": "ws_abc123",
    "projectId": "proj_xyz789",
    "status": "TODO",
    "priority": "HIGH",
    "assigneeIds": ["member_001"],
    "description": "Add OAuth2 authentication flow",
    "estimatedHours": 8,
    "labels": ["auth", "security"],
    "dueDate": "2024-02-15"
  }'

Note

Work items are automatically assigned a unique key based on the project (e.g., MOB-1, WEB-42).

Update Work Item

Update an existing work item.

Request

bash

PATCH /api/tasks/:taskId
Content-Type: application/json

curl -X PATCH "https://api.fairlx.com/v1/tasks/wi_001" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "DONE",
    "flagged": true
  }'

Tip

Updating a work item triggers notifications to assignees and workspace admins based on what changed.

Delete Work Item

Delete a work item and related time logs.

Request

bash

DELETE /api/tasks/:taskId

curl -X DELETE "https://api.fairlx.com/v1/tasks/wi_001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Bulk Update

Update multiple work items at once. Useful for Kanban board drag operations.

Request

bash

POST /api/tasks/bulk-update
Content-Type: application/json

curl -X POST "https://api.fairlx.com/v1/tasks/bulk-update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [
      { "$id": "wi_001", "status": "IN_PROGRESS", "position": 1000 },
      { "$id": "wi_002", "status": "IN_PROGRESS", "position": 2000 }
    ]
  }'

Warning

All tasks in a bulk update must belong to the same workspace.