Teams V2 API – LinearB Support

Use the Teams V2 API to create and manage teams programmatically in LinearB. Teams define which contributors belong together for metrics, dashboards, delivery insights, project tracking, and automation analysis.

This API is ideal if you maintain team structure in an HRIS, internal database, or automation layer and want LinearB to stay in sync.

TL;DR

Use GET /api/v2/teams to search and paginate teams.
Use POST /api/v2/teams to create one or more teams (bulk).
Use PATCH /api/v2/teams/{team_id} to rename or reparent a team, or adjust initials/color.
Use DELETE /api/v2/teams/{team_id} to delete a team.
Use PATCH /api/v2/teams/{team_id}/members to add members by ID or email.
Use DELETE /api/v2/teams/{team_id}/members/{user_id_or_email} to remove a specific member.

Before You Begin

Authentication

All Teams V2 API requests require an API token.

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

Authorization: Bearer <your_api_token>

Team model (response fields)

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.

When to use this API

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.

1. Search Teams

GET /api/v2/teams – search & paginate teams

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):

Field	Type	Required?	Description
`offset`	integer	No	Number of items to skip before starting the page. Default: `0`.
`page_size`	integer	No	Number of items per page (min 1, max 50, default 50).
`search_term`	string	No	Optional text to filter teams by name (1–100 characters).
`nonmerged_members_only`	boolean	No	If `true`, excludes member accounts that were merged into others. If `false`, includes all member accounts. Default: `false`.

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": []
    }
  ]
}

2. Create Teams (bulk)

POST /api/v2/teams – create one or more teams

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):

Field	Type	Required?	Description
`name`	string	Yes	Team display name. Must be 3–100 characters and start with a letter.
`parent_team`	string	No	Name of an existing team to use as a parent in a hierarchy.
`initials`	string	No	1–3 character abbreviation of the team name.
`color`	string	No	Hex color code in `#RGB` or `#RRGGBB` format. Default: `#348B83`.

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.

3. Update a Team

PATCH /api/v2/teams/{team_id} – update team properties

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):

Field	Type	Description
`name`	string	New display name (3–100 characters, starts with a letter).
`parent_team`	string	Name of an existing team to use as the new parent.
`initials`	string	Updated 1–3 character abbreviation.
`color`	string	Updated hex color code.

Example request body

{
  "name": "Platform & Developer Experience",
  "initials": "PLT",
  "color": "#348B83"
}

4. Delete a Team

DELETE /api/v2/teams/{team_id} – delete a team

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.

5. Add Members to a Team

PATCH /api/v2/teams/{team_id}/members – add users by ID or email

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

Field	Type	Description
`user_ids`	array of objects	Each object includes: `id` – user ID `joined_at` – optional timestamp
`emails`	array of objects	Each object includes: `email` – user email `joined_at` – optional timestamp

Example: add members by email

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

6. Remove a Member from a Team

DELETE /api/v2/teams/{team_id}/members/{user_id_or_email}

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.

Behavior & Impact on Metrics

Team hierarchy

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.

Contributors & metrics

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

Verify & Troubleshooting

Verify a new or updated team

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

Quick fixes (most common issues)

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.

Advanced troubleshooting (problem → cause → fix)

Problem	Cause	Fix
Team creation job fails	The bulk create request contained invalid team definitions (for example, bad names or duplicate hierarchy).	Inspect the API response for `400`/`422` details. Correct invalid fields (for example, `name`, `parent_team`) and resend.
Members appear duplicated	The same user was added multiple times by both `user_ids` and `emails`, or via multiple automation runs.	Standardize on a single identifier type (ID or email) in your integration. Clean up duplicates by removing redundant entries.
Unexpected 409 Conflict	A concurrent update or a conflicting team definition (for example, duplicate names in a hierarchy).	Re-fetch teams with `GET /api/v2/teams`, adjust your payload, and retry once the source of conflict is resolved.

FAQ

Can a contributor belong to multiple teams?

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

Does deleting a team remove historical data?

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

Can I rename a team later?

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

For additional information, please visit our external API documentation

For additional technical support, please contact LinearB support.