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
| Field | Type | Description |
|---|---|---|
| title | string | Work item title |
| type | string | TASK, BUG, STORY, EPIC, etc. |
| status | string | TODO, ASSIGNED, IN_PROGRESS, IN_REVIEW, DONE, or a custom status |
| 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
GET /api/tasks?workspaceId=ws_abc123&projectId=proj_xyz&status=IN_PROGRESSQuery Parameters
workspaceId(required) — Filter by workspaceprojectId— Filter by projectstatus— Filter by statusassigneeId— Filter by assigneepriority— Filter by prioritylabels— Comma-separated labelsdueDate— 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/:taskIdCreate 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/:taskIdBulk 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.
