Fairlx Logo

Beta

Sprints API

Manage agile sprints for time-boxed iterations.

Overview

Sprints are time-boxed iterations for agile teams. Each sprint belongs to a project and can contain multiple work items.

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.

Sprint Status

  • PLANNED — Sprint is scheduled but not started
  • ACTIVE — Sprint is in progress
  • COMPLETED — Sprint is finished

List Sprints

Retrieve all sprints for a project with work item counts.

Request
GET /api/sprints?workspaceId=ws_abc123&projectId=proj_xyz789&status=ACTIVE
Response
{
  "data": {
    "documents": [
      {
        "$id": "sprint_001",
        "name": "Sprint 1",
        "status": "ACTIVE",
        "startDate": "2024-01-15T00:00:00Z",
        "endDate": "2024-01-29T00:00:00Z",
        "goal": "Complete authentication flow",
        "position": 1000,
        "workspaceId": "ws_abc123",
        "projectId": "proj_xyz789",
        "workItemCount": 12,
        "totalPoints": 34,
        "completedPoints": 21
      }
    ],
    "total": 1
  }
}

Get Sprint

Retrieve a sprint with all its work items and assignee details.

Request
GET /api/sprints/:sprintId

Create Sprint

Create a new sprint for a project. Requires the project's Create Sprints permission (project.sprints.create).

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

{
  "name": "Sprint 2",
  "workspaceId": "ws_abc123",
  "projectId": "proj_xyz789",
  "status": "PLANNED",
  "startDate": "2024-01-29",
  "endDate": "2024-02-12",
  "goal": "Implement dashboard features"
}

Request Body

FieldTypeRequiredDescription
namestringYesSprint name
workspaceIdstringYesParent workspace
projectIdstringYesParent project
startDatestringNoSprint start date
endDatestringNoSprint end date
goalstringNoSprint goal description

Update Sprint

Update an existing sprint. Status changes require specific permissions.

Request
PATCH /api/sprints/:sprintId
Content-Type: application/json

{
  "status": "ACTIVE"
}

Note

Setting status to ACTIVE requires Start Sprint (project.sprints.start). Setting to COMPLETED requires Complete Sprint (project.sprints.complete).

Complete Sprint

Complete a sprint and optionally move unfinished items to another sprint or backlog.

Request
POST /api/sprints/:sprintId/complete
Content-Type: application/json

{
  "workspaceId": "ws_abc123",
  "projectId": "proj_xyz789",
  "unfinishedDetails": {
    "moveTo": "backlog"
  }
}

To move unfinished items to another sprint:

Move to Sprint
{
  "unfinishedDetails": {
    "moveTo": { "sprintId": "sprint_002" }
  }
}

Delete Sprint

Delete a sprint. All work items are moved to the backlog.

Warning

Requires Delete Sprints (project.sprints.delete). Work items are not deleted—they are moved to the backlog.
Request
DELETE /api/sprints/:sprintId

Additional Endpoints

  • POST /sprints/reorder — Reorder sprints by position