Fairlx Logo

Beta

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.

Note

These are the web app's own routes under https://app.fairlx.com/api. They accept only a signed-in session and may change. Programmatic access goes through the Fairlx MCP endpoint.

Work Item Properties

FieldTypeDescription
titlestringWork item title
typestringTASK, BUG, STORY, EPIC, etc.
statusstringTODO, ASSIGNED, IN_PROGRESS, IN_REVIEW, DONE, or a custom status
prioritystringLOW, MEDIUM, HIGH, URGENT
assigneeIdsstring[]Array of member IDs
labelsstring[]Array of label strings
sprintIdstringSprint ID if assigned

List Work Items

Retrieve work items with optional filters.

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

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
{
  "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
GET /api/tasks/:taskId

Create Work Item

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

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

{
  "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
PATCH /api/tasks/:taskId
Content-Type: application/json

{
  "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
DELETE /api/tasks/:taskId

Bulk Update

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

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

{
  "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.