Skip to main content
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
ParameterTypeDescription
workspace_idstringRequired (or service_line_id). Workspace scope.
service_line_idstringFilter to a specific LIN-*
project_idstringFilter by project label
assignee_idstringFilter by assigned user
statusenumbacklog, in_progress, in_review, done, cancelled
priorityenumlow, medium, high, critical
cursorstringPagination cursor
limitintegerResults 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

FieldTypeDescription
idstringTSK-* identifier
workspace_idstringScoped workspace
service_line_idstringOwning LIN-* (delivery context)
project_idstringOptional PROJ-* label
titlestringTask title
descriptionstringFull task description
statusenumbacklog, in_progress, in_review, done, cancelled
priorityenumlow, medium, high, critical
assignee_idstringUSR-* of the assignee
external_idstringID in the connected PM tool
external_sourcestringSource tool identifier (e.g. jira)
external_urlstringDeep link to the external issue
historyarrayStatus change log (returned on GET by ID)
created_atdatetimeCreation timestamp
updated_atdatetimeLast 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.
Last modified on April 15, 2026