API - Teams v2

All Teams V2 API requests require an API token.

1. In LinearB, go to Company Settings → API Tokens.
2. Create (or reuse) an API token with access to the LinearB API.
3. Send it with every request in the Authorization header:

Authorization: Bearer <your_api_token>

When you search teams, each team object can include:

• id – integer, unique ID of the team in LinearB.
• organization_id – integer, ID of the LinearB organization.
• name – string, team display name.
• created_at – string, creation timestamp.
• initials – string, 1–3 character abbreviation of the team name.
• color – string, hex color code (for example, #3B48B3).
• extra – object, reserved for future metadata.
• parent_id – integer or null, parent team ID for hierarchical structures.
• contributors – array of contributor objects, each including:
  • id – contributor ID.
  • name – contributor name.
  • parent_id – parent relationship (if applicable).
  • provider_id – provider identifier for the contributor.
  • roles – array of role objects.

Contributor identities must already exist in LinearB for membership updates to succeed.

• You manage team structure in an external system (HRIS, IAM, internal DB).
• You want automated provisioning and updates of teams.
• You need to add/remove members at scale based on external events.
• You are migrating from Teams V1 and want to align with the new Teams V2 model.

Retrieves a paginated list of teams within the LinearB platform.

HTTP request

GET https://public-api.linearb.io/api/v2/teams

Body parameters (sent as JSON in the request body):

Example: search teams by name

{

            "offset": 0,

            "page_size": 25,

            "search_term": "platform",

            "nonmerged_members_only": true

          }

Successful response (200)

{

            "total": 2,

            "items": [

              {

                "id": 1,

                "organization_id": 123,

                "name": "Platform Team",

                "created_at": "2024-01-01T10:00:00Z",

                "initials": "PLT",

                "color": "#3B48B3",

                "extra": {},

                "parent_id": null,

                "contributors": []

              }

            ]

          }

Creates one or more teams in LinearB in a single request.

HTTP request

POST https://public-api.linearb.io/api/v2/teams

Body parameters (array of team definitions):

Example request body

[

            {

              "name": "Platform Team",

              "parent_team": "Engineering",

              "initials": "PLT",

              "color": "#3B48B3"

            }

          ]

Successful response (200)

{

            "job_id": "abcd-1234",

            "message": "Teams creation job created."

          }

Team creation is processed asynchronously. Use the Jobs API if you need to track the job status.

Updates properties of a team based on the provided team_id.

HTTP request

PATCH https://public-api.linearb.io/api/v2/teams/{team_id}

Body parameters (all optional, but at least one field is required):

Example request body

{

            "name": "Platform & Developer Experience",

            "initials": "PLT",

            "color": "#348B83"

          }

Deletes a team identified by the provided team_id.

HTTP request

DELETE https://public-api.linearb.io/api/v2/teams/{team_id}

A successful response returns 200 or 204. Historical data is not deleted, but the team is no longer available as an active entity.

Adds one or more users to a team. You can reference users by user_id or by email.

HTTP request

PATCH https://public-api.linearb.io/api/v2/teams/{team_id}/members

Body parameters

Example: add members by email

{

            "emails": [

              { "email": "alice@acme.com", "joined_at": "2024-01-10T09:00:00Z" },

              { "email": "bob@acme.com" }

            ]

          }

Removes a specific member from a team using their user ID or email.

HTTP request

DELETE https://public-api.linearb.io/api/v2/teams/{team_id}/members/{user_id_or_email}

Path parameters

• team_id – integer ID of the team.
• user_id_or_email – string user ID or email.

When you use parent_team while creating or updating teams, you create a hierarchy. Parent teams can aggregate metrics from child teams in LinearB’s UI.

• All contributors returned in contributors count toward that team’s metrics.
• Membership changes affect dashboards and reports after the next data processing cycle.
• Members added via user IDs or emails must exist as users in LinearB (see Users V2 API).

1. Create or update the team via POST /api/v2/teams or PATCH /api/v2/teams/{team_id}.
2. Confirm you receive a 200 response and, for creates, note the job_id.
3. Call GET /api/v2/teams with an appropriate search_term to confirm the team appears.
4. In LinearB, open team-based views and verify the team and its members appear as expected.

• Team not created
  – Check for 400 or 422 errors (for example, invalid name or missing required fields).
  – Ensure the request body is an array of team objects, not a single object.
  – Validate that name is 3–100 characters and starts with a letter.
• Team not visible in search
  – Confirm you are not filtering it out with search_term.
  – Try a broader search or page_size large enough to include it.
• Members not added
  – Ensure the users exist in LinearB and that IDs/emails are correct.
  – Confirm the payload uses the user_ids / emails object format (not just strings).
• 401 / 403 errors
  – Verify the Authorization header is present and token is valid.
  – Confirm the token belongs to the correct LinearB organization and has API access.

Yes. A contributor can be a member of multiple teams, and their activity is counted in each team’s metrics.

No. Deleting a team removes it as an active entity, but historical data remains in LinearB.

Yes. Use PATCH /api/v2/teams/{team_id} to update the team’s name, initials, or color.