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.

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

bash

GET /api/sprints?workspaceId=ws_abc123&projectId=proj_xyz789&status=ACTIVE

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

Response

json

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

bash

GET /api/sprints/:sprintId

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

Create Sprint

Create a new sprint for a project. Requires SPRINT_CREATE permission.

Request

bash

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

curl -X POST "https://api.fairlx.com/v1/sprints" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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

Field	Type	Required	Description
name	string	Yes	Sprint name
workspaceId	string	Yes	Parent workspace
projectId	string	Yes	Parent project
startDate	string	No	Sprint start date
endDate	string	No	Sprint end date
goal	string	No	Sprint goal description

Update Sprint

Update an existing sprint. Status changes require specific permissions.

Request

bash

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

curl -X PATCH "https://api.fairlx.com/v1/sprints/sprint_001" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ACTIVE"
  }'

Note

Setting status to ACTIVE requires SPRINT_START permission. Setting to COMPLETED requires SPRINT_COMPLETE permission.

Complete Sprint

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

Request

bash

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

curl -X POST "https://api.fairlx.com/v1/sprints/sprint_001/complete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "ws_abc123",
    "projectId": "proj_xyz789",
    "unfinishedDetails": {
      "moveTo": "backlog"
    }
  }'

To move unfinished items to another sprint:

Move to Sprint

json

{
  "unfinishedDetails": {
    "moveTo": { "sprintId": "sprint_002" }
  }
}

Delete Sprint

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

Warning

Requires SPRINT_DELETE permission. Work items are not deleted—they are moved to the backlog.

Request

bash

DELETE /api/sprints/:sprintId

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

Additional Endpoints

POST /sprints/reorder — Reorder sprints by position