Tasks & Work Items

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.

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

GET /v1/tasks?workspace_id=WS-26-000021&service_line_id=LIN-26-084729&status=in_progress
Authorization: Bearer <token>

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

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

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

Retrieve a task with full detail.

Response

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

Update a task.

Request

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

# 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

# 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.

Overview

Organizations

Workspaces

Service Lines

Core Platform

Observability & Metrics

ODS

Talent Marketplace

AI Agent Gateway

Product Lines

Machine-Readable Company Data

CLI

Overview

Core Concepts

Task scope

Sync with external tools

Tasks and delivery metrics

Tasks and agents

Endpoints

GET /v1/tasks

Request

Response

POST /v1/tasks

Request

Response

Notes

GET /v1/tasks/

Response

PATCH /v1/tasks/

Request

Notes

Common Workflows

Reviewing open work for a project

Agent creating and closing a task

Objects

Task

Best Practices

​Overview

​Core Concepts

​Task scope

​Sync with external tools

​Tasks and delivery metrics

​Tasks and agents

​Endpoints

​GET /v1/tasks

​Request

​Response

​POST /v1/tasks

​Request

​Response

​Notes

​GET /v1/tasks/

​Response

​PATCH /v1/tasks/

​Request

​Notes

​Common Workflows

​Reviewing open work for a project

​Agent creating and closing a task

​Objects

​Task

​Best Practices

Overview

Core Concepts

Task scope

Sync with external tools

Tasks and delivery metrics

Tasks and agents

Endpoints

GET /v1/tasks

Request

Response

POST /v1/tasks

Request

Response

Notes

GET /v1/tasks/

Response

PATCH /v1/tasks/

Request

Notes

Common Workflows

Reviewing open work for a project

Agent creating and closing a task

Objects

Task

Best Practices