Workspaces - Scrums.com Docs

The Scrums.com API is planned and not yet publicly available. Endpoints and behaviour are subject to change before release.

Overview

A workspace (WS-*) is the operational unit within an organization. It is where delivery happens: Service Lines are activated within workspaces, teams are assembled within workspaces, and integrations connect at the workspace level. The platform hierarchy is ORG-* owns WS-* which activates LIN-*. Workspaces are not projects. Projects are labels applied to work; workspaces are structural operational containers.

Core Concepts

Workspace scope

Most resource operations are scoped to a workspace. API tokens can be narrowed to a single workspace to enforce isolation between teams or business units.

Workspace membership

Users are added to workspaces with a role. Workspace roles are: admin, member, viewer. Organization-level owner and admin members implicitly have access to all workspaces in the org.

Service Lines and workspaces

A workspace activates Service Lines. Every LIN-* belongs to exactly one workspace. Usage, capacity, and observability queries are most commonly filtered by workspace_id.

Multiple workspaces per organization

Large organizations typically run multiple workspaces representing business units, product areas, or engineering tribes. Each workspace has its own: team, Service Lines, integrations, and budget visibility. Billing rolls up to the organization.

Endpoints

GET /v1/workspaces

List workspaces accessible to the authenticated token.

Request

GET /v1/workspaces?organization_id=ORG-26-090500
Authorization: Bearer <token>

Response

{
  "data": [
    {
      "id": "WS-26-000021",
      "organization_id": "ORG-26-090500",
      "name": "Platform Engineering",
      "slug": "platform-engineering",
      "status": "active",
      "member_count": 14,
      "active_service_lines": 6,
      "created_at": "2024-03-15T10:00:00Z",
      "updated_at": "2026-04-01T09:00:00Z"
    }
  ],
  "meta": {
    "cursor": null,
    "has_more": false
  }
}

POST /v1/workspaces

Create a new workspace within an organization.

Request

{
  "organization_id": "ORG-26-090500",
  "name": "Platform Engineering",
  "slug": "platform-engineering"
}

Response

Returns the created workspace with status: "active".

Notes

slug must be unique within the organization.
The creating user is automatically added as a workspace admin.

GET /v1/workspaces/

Retrieve a workspace with current summary metrics.

Response

{
  "data": {
    "id": "WS-26-000021",
    "organization_id": "ORG-26-090500",
    "name": "Platform Engineering",
    "slug": "platform-engineering",
    "status": "active",
    "settings": {
      "default_currency": "USD",
      "require_task_service_line": true
    },
    "member_count": 14,
    "active_service_lines": 6,
    "health_score": 87,
    "cost_mtd": 142650.00,
    "currency": "USD",
    "created_at": "2024-03-15T10:00:00Z",
    "updated_at": "2026-04-01T09:00:00Z"
  }
}

PATCH /v1/workspaces/

Update a workspace.

Request

{
  "name": "Platform & Infrastructure Engineering",
  "settings": {
    "require_task_service_line": true
  }
}

GET /v1/workspaces//members

List workspace members.

Response

{
  "data": [
    {
      "user_id": "USR-26-000044",
      "name": "Sam Rivera",
      "email": "sam@apexdigital.com",
      "role": "admin",
      "status": "active",
      "joined_at": "2024-03-15T10:00:00Z"
    }
  ]
}

POST /v1/workspaces//members

Add a user to a workspace.

Request

{
  "user_id": "USR-26-000081",
  "role": "member"
}

Notes

User must already exist in the organization (via POST /v1/orgs/{org_id}/members).
A user cannot be added to a workspace with a role higher than their organization role.

DELETE /v1/workspaces//members/

Remove a user from a workspace.

Common Workflows

Creating a workspace for a new team

# Create the workspace
POST /v1/workspaces
{ "organization_id": "ORG-26-090500", "name": "Data Engineering", "slug": "data-engineering" }

# Add team members
POST /v1/workspaces/WS-26-000091/members
{ "user_id": "USR-26-000081", "role": "admin" }

# Connect integrations
POST /v1/integrations
{ "workspace_id": "WS-26-000091", "type": "github", "config": { "org": "apex-digital" } }

Objects

Workspace

Field	Type	Description
`id`	string	`WS-*` identifier
`organization_id`	string	Parent organization (`ORG-*`)
`name`	string	Display name
`slug`	string	URL-safe identifier, unique within the org
`status`	enum	`active`, `archived`
`settings`	object	Workspace-level configuration
`member_count`	integer	Number of active workspace members
`active_service_lines`	integer	Active `LIN-*` count
`health_score`	integer	Current observability health score (0-100)
`cost_mtd`	number	Month-to-date spend across all Service Lines
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last modification timestamp

Best Practices

Align workspaces with operational teams, not business entities. A workspace is where a team works day-to-day. Use project labels and Service Line tags to represent business groupings.
Scope API tokens to workspaces. For integrations that operate within a single team, issue tokens scoped to that workspace. This prevents cross-team data access and simplifies debugging.
Do not archive workspaces with active Service Lines. Close all Service Lines first. Archiving a workspace with active LIN-* will block further metering and may cause invoicing gaps.

​Overview

​Core Concepts

​Workspace scope

​Workspace membership

​Service Lines and workspaces

​Multiple workspaces per organization

​Endpoints

​GET /v1/workspaces

​Request

​Response

​POST /v1/workspaces

​Request

​Response

​Notes

​GET /v1/workspaces/

​Response

​PATCH /v1/workspaces/

​Request

​GET /v1/workspaces//members

​Response

​POST /v1/workspaces//members

​Request

​Notes

​DELETE /v1/workspaces//members/

​Common Workflows

​Creating a workspace for a new team

​Objects

​Workspace

​Best Practices

Overview

Core Concepts

Workspace scope

Workspace membership

Service Lines and workspaces

Multiple workspaces per organization

Endpoints

GET /v1/workspaces

Request

Response

POST /v1/workspaces

Request

Response

Notes

GET /v1/workspaces/

Response

PATCH /v1/workspaces/

Request

GET /v1/workspaces//members

Response

POST /v1/workspaces//members

Request

Notes

DELETE /v1/workspaces//members/

Common Workflows

Creating a workspace for a new team

Objects

Workspace

Best Practices