> ## Documentation Index
> Fetch the complete documentation index at: https://www.scrums.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Tasks & Work Items
> Work items in the delivery pipeline. Tasks are linked to Service Lines, tagged with projects, and synced bidirectionally with connected project management tools.
The Scrums.com API is **planned and not yet publicly available**. Endpoints and behaviour are subject to change before release.
## Overview
Tasks (`TSK-*`) are the work items that flow through delivery on the platform. They represent the discrete units of work being tracked, executed, and completed within a Service Line context.
Tasks are not a generic to-do list. They are delivery-operational records: linked to the `LIN-*` that owns the delivery context, tagged with `PROJ-*` labels for cross-cutting project visibility, synced with connected PM tools (Jira, ClickUp, Linear), and observable through delivery velocity metrics in the [Observability API](/docs/api-reference/core/observability).
## Core Concepts
### Task scope
Tasks are scoped to a workspace. They carry:
* A `service_line_id` indicating which `LIN-*` the work belongs to
* A `project_id` (optional) for cross-platform project grouping
* An `external_id` and `external_source` if synced from a connected PM tool
### Sync with external tools
When a [Jira or ClickUp integration](/docs/api-reference/core/integrations) is active in a workspace, tasks are synced bidirectionally. Status changes made in the Scrums platform propagate to the external tool; updates in the external tool propagate to the platform. The `external_id` and `external_source` fields record the binding.
### Tasks and delivery metrics
Completed tasks feed the `delivery_velocity` metric in the [Observability API](/docs/api-reference/core/observability). The rate of task completion per Service Line, relative to historical baselines, is a primary health signal.
### Tasks and agents
Agents can create, update, and close tasks as part of their execution. Every agent-driven task change is recorded in the [Audit Logs](/docs/api-reference/core/audit-logs) and tagged with the agent's `AGT-*` identifier.
## Endpoints
### GET /v1/tasks
List tasks for a workspace or filtered by Service Line, project, or status.
#### Request
```bash theme={null}
GET /v1/tasks?workspace_id=WS-26-000021&service_line_id=LIN-26-084729&status=in_progress
Authorization: Bearer
```
**Query parameters**
| Parameter | Type | Description |
| ----------------- | ------- | ---------------------------------------------------------- |
| `workspace_id` | string | Required (or `service_line_id`). Workspace scope. |
| `service_line_id` | string | Filter to a specific `LIN-*` |
| `project_id` | string | Filter by project label |
| `assignee_id` | string | Filter by assigned user |
| `status` | enum | `backlog`, `in_progress`, `in_review`, `done`, `cancelled` |
| `priority` | enum | `low`, `medium`, `high`, `critical` |
| `cursor` | string | Pagination cursor |
| `limit` | integer | Results per page (max 100, default 25) |
#### Response
```json theme={null}
{
"data": [
{
"id": "TSK-26-018841",
"workspace_id": "WS-26-000021",
"service_line_id": "LIN-26-084729",
"project_id": "PROJ-26-004281",
"title": "Implement idempotency key validation on payment endpoint",
"status": "in_progress",
"priority": "high",
"assignee_id": "USR-26-000044",
"external_id": "APEX-1042",
"external_source": "jira",
"created_at": "2026-04-10T10:00:00Z",
"updated_at": "2026-04-14T16:00:00Z"
}
],
"meta": {
"cursor": null,
"has_more": false
}
}
```
### POST /v1/tasks
Create a new task.
#### Request
```json theme={null}
{
"workspace_id": "WS-26-000021",
"service_line_id": "LIN-26-084729",
"project_id": "PROJ-26-004281",
"title": "Add distributed tracing to payment service",
"description": "Instrument the payments API with OpenTelemetry spans to support end-to-end trace correlation.",
"priority": "medium",
"assignee_id": "USR-26-000044",
"status": "backlog"
}
```
#### Response
Returns the created task record.
#### Notes
* If the workspace has an active Jira or ClickUp integration with project mapping configured, a corresponding issue is created in the external system automatically.
* `service_line_id` is required unless the workspace setting `require_task_service_line` is disabled.
### GET /v1/tasks/{task_id}
Retrieve a task with full detail.
#### Response
```json theme={null}
{
"data": {
"id": "TSK-26-018841",
"workspace_id": "WS-26-000021",
"service_line_id": "LIN-26-084729",
"project_id": "PROJ-26-004281",
"title": "Implement idempotency key validation on payment endpoint",
"description": "Payment endpoint must reject duplicate requests within 24 hours using the idempotency key.",
"status": "in_progress",
"priority": "high",
"assignee_id": "USR-26-000044",
"external_id": "APEX-1042",
"external_source": "jira",
"external_url": "https://apexdigital.atlassian.net/browse/APEX-1042",
"history": [
{ "at": "2026-04-10T10:00:00Z", "change": "status", "from": "backlog", "to": "in_progress", "by": "USR-26-000044" }
],
"created_at": "2026-04-10T10:00:00Z",
"updated_at": "2026-04-14T16:00:00Z"
}
}
```
### PATCH /v1/tasks/{task_id}
Update a task.
#### Request
```json theme={null}
{
"status": "in_review",
"assignee_id": "USR-26-000081"
}
```
#### Notes
* Status changes propagate to the external PM tool if a sync integration is active.
* Setting `status: "done"` or `status: "cancelled"` triggers a `task.status_changed` event and increments the delivery velocity counter for the linked `LIN-*`.
## Common Workflows
### Reviewing open work for a project
```bash theme={null}
# All open tasks for a project, across all service lines
GET /v1/tasks?workspace_id=WS-26-000021&project_id=PROJ-26-004281&status=in_progress,backlog
# Drill into a specific service line's tasks
GET /v1/tasks?service_line_id=LIN-26-084729&status=in_progress
```
### Agent creating and closing a task
```bash theme={null}
# Agent creates a task based on analysis output
POST /v1/tasks
{ "service_line_id": "LIN-26-091100", "title": "Fix memory leak in worker process - identified by analysis", "priority": "high" }
# Agent closes the task after completing the fix
PATCH /v1/tasks/TSK-26-018901
{ "status": "done" }
```
## Objects
### Task
| Field | Type | Description |
| ----------------- | -------- | ---------------------------------------------------------- |
| `id` | string | `TSK-*` identifier |
| `workspace_id` | string | Scoped workspace |
| `service_line_id` | string | Owning `LIN-*` (delivery context) |
| `project_id` | string | Optional `PROJ-*` label |
| `title` | string | Task title |
| `description` | string | Full task description |
| `status` | enum | `backlog`, `in_progress`, `in_review`, `done`, `cancelled` |
| `priority` | enum | `low`, `medium`, `high`, `critical` |
| `assignee_id` | string | `USR-*` of the assignee |
| `external_id` | string | ID in the connected PM tool |
| `external_source` | string | Source tool identifier (e.g. `jira`) |
| `external_url` | string | Deep link to the external issue |
| `history` | array | Status change log (returned on GET by ID) |
| `created_at` | datetime | Creation timestamp |
| `updated_at` | datetime | Last modification timestamp |
## Best Practices
* **Always set `service_line_id` on tasks.** Unlinked tasks do not contribute to delivery velocity metrics and are invisible to the observability layer. The workspace setting `require_task_service_line` can enforce this automatically.
* **Use `project_id` for cross-cutting visibility, not for filtering by team.** Teams are represented by workspaces. Projects are for initiative-level grouping across teams and product lines.
* **Let the sync integration own external task creation.** When a Jira or ClickUp integration is active, create tasks via the Scrums API and let the sync create the external issue. Do not create issues in both systems manually — you will get duplicates.