PM Configuration

These endpoints let you read and change your project management (PM) configuration without the LinearB app: which PM integrations you have, which boards and projects are collected, and which PM entities each team is scoped to.

Providers: Jira and Azure Boards.

Authentication: an API key, sent as the x-api-key header (see Overview). Only an admin can create an API key, and every key acts as an admin of your organization on these endpoints - it can read, and change what is collected and each team's scope.

Every endpoint that acts on an integration takes its id explicitly, because an organization can have several PM integrations. Start with List Integrations to get those ids.

List Integrations

Lists your organization's integrations: PM (Jira and Azure Boards) and git. Use type=pm to list only the PM integrations these endpoints take.

HTTP request

GET  https://public-api.linearb.io/api/v1/integrations?type=pm

Query parameters

Responses

200 - Successful Response

{
 "items": [
    {"id": 1001, "type": "pm", "provider": "jira", "name": "Jira", "state": "ok", "auth_type": "oauth2"},
    {"id": 1002, "type": "pm", "provider": "azure_boards", "name": "Azure Boards", "state": "failing", "auth_type": "token",
     "failing_reason": "PM integration failure. Review this integration in Settings > Project Management."}
  ]
}

• id is the integration id that every other endpoint takes. type says whether it is a pm or a git integration.
• state is ok, failing, insufficient-permission, in-progress, inactive, cleanup-requested, cleanup-in-progress or cleanup-failed. Every integration that is not deleted is listed and can be read.
• An ok, failing or insufficient-permission PM integration can be changed. One that is still being connected (in-progress), inactive, or being removed (cleanup-*) is read-only: a write that names it returns 400 saying why.

400 - Bad Request (for example, type other than pm / git, or an unknown provider)

403 - Forbidden

List PM Entities

Reads the PM entities of one type, across your integrations.

HTTP request

GET  https://public-api.linearb.io/api/v2/pm/entities/{entity_type}

Path parameters

Query parameters

Responses

200 - Successful Response

{
 "total": 1,
 "offset": 0,
 "type": "boards",
 "integrations": [
    {
     "integration_id": 1001,
     "provider": "jira",
     "integration_name": "Jira",
     "entities": [
        {
         "entity_provider_id": "109",
         "name": "Payments Scrum Board",
         "state": "accessible",
         "is_selected_for_collection": true,
         "selected_last_updated_at": "2026-08-06T10:04:31.327Z",
         "used_by": {"teams": [{"id": 4412, "name": "Payments"}], "projects": []}
        }
      ]
    }
  ]
}

• entity_provider_id is the provider's id. The write endpoints take it.
• is_selected_for_collection and selected_last_updated_at appear only on Jira boards / projects and Azure projects.
• used_by (boards and projects only) lists what depends on the entity. A deselect is refused while it is not empty.
• Azure teams carry their parent_project, and Azure areas carry their teams. That is what a team scope's project_team_areas needs.

400 - Bad Request (for example, a type the provider does not have)

403 - Forbidden

404 - Not Found (an integration id that is not a live PM integration of your organization)

Select PM Entities for Collection

Selects or deselects boards / projects of one integration for collection. Same as Settings > Project Management in the app.

HTTP request

PATCH  https://public-api.linearb.io/api/v2/pm/integrations/{integration_id}/entities/{entity_type}

Path parameters

Body parameters

{
 "entities": [
    {"entity_provider_id": "109", "is_selected_for_collection": true},
    {"entity_provider_id": "332", "is_selected_for_collection": false}
  ]
}

Responses

200 - At least one entry was applied. Valid entries apply even when others are rejected.

{
 "integration_id": 1001,
 "type": "boards",
 "applied": [{"entity_provider_id": "109", "is_selected_for_collection": true}],
 "rejected": [
    {"entity_provider_id": "332", "is_selected_for_collection": false, "code": "entity_in_use",
     "message": "332 is still in use and was left selected",
     "used_by": {"teams": [{"id": 4413, "name": "Platform"}], "projects": []}}
  ]
}

400 - Nothing was applied (same body), a bad request, or the integration is read-only (still being connected, inactive or being removed)

403 - Forbidden, or the selection would exceed your organization's board / project limit (nothing is written)

404 - Not Found

A newly selected board or project is collected on the next scheduled run, usually within the hour.

Get Team PM Scope

Reads what a team is scoped to, one item per integration. Same as Team Settings > Project Management in the app.

HTTP request

GET  https://public-api.linearb.io/api/v1/pm/config/teams/{team_id}/scope

Path parameters

Query parameters

Responses

200 - Successful Response

{
 "team_id": 4412,
 "team_name": "Payments",
 "items": [
    {
     "integration_id": 1001, "provider": "jira", "integration_name": "Jira",
     "scope": {"boards": [{"entity_provider_id": "109", "name": "Payments Scrum Board"}],
               "epics": [], "labels": [], "fields": []},
     "methodology": "Scrum"
    },
    {
     "integration_id": 1002, "provider": "azure_boards", "integration_name": "Azure Boards",
     "scope": {"project_team_areas": [
        {"project": {"entity_provider_id": "9d09f4a3-6b23-46e3-8c9f-559d8e016ef5", "name": "Payments"},
         "team":    {"entity_provider_id": "f8732cf3-4aab-4bb4-a5e8-7a8099076109", "name": "Payments Team"},
         "areas":  [{"entity_provider_id": "395", "name": "Payments\\Backend"}]}]},
     "methodology": "Kanban"
    }
  ]
}

• Jira scope keys: boards, epics, labels, fields. Azure Boards scope key: project_team_areas.
• "scope": {} means the team is not scoped on that integration, so it sees everything the integration collects.
• methodology is Scrum or Kanban.

403 - Forbidden

404 - Not Found (the team, or an integration id, is not in your organization)

Write Team PM Scopes

Writes the PM scope of one or more teams.

• PATCH (Update Team PM Scope Keys) writes the keys you send and leaves every other key as it is. Its mode query parameter says what happens to each key you send:
  • mode=merge (the default): the list you send replaces that key's list. A key sent as [] is cleared.
  • mode=add: the entries you send are added to that key's list. Entries already there are kept, nothing is removed, and a key sent as [] changes nothing.
• POST (Replace Team PM Scopes) replaces each (team, integration) scope you name. Every item must name at least one scope key; to clear a whole scope, use Clear a Team PM Scope.

Scopes you do not name are never touched.

HTTP request

PATCH  https://public-api.linearb.io/api/v1/pm/config/teams/scope?mode={merge|add}
POST   https://public-api.linearb.io/api/v1/pm/config/teams/scope

Query parameters

Body parameters

{
 "teams": [
    {"team_id": 4412, "items": [
       {"integration_id": 1001, "scope": {"boards": [{"entity_provider_id": "109"}]}, "methodology": "Scrum"},
       {"integration_id": 1002, "scope": {"project_team_areas": [
          {"project": {"entity_provider_id": "9d09f4a3-6b23-46e3-8c9f-559d8e016ef5"},
           "team":    {"entity_provider_id": "f8732cf3-4aab-4bb4-a5e8-7a8099076109"},
           "areas":  [{"entity_provider_id": "395"}]}]}}
    ]}
  ]
}

Scope key shapes:

• boards, epics: {"entity_provider_id": "109"}
• labels: {"name": "urgent"} - a label's name is its id
• fields: {"entity_provider_id": "customfield_10010", "value": ["Payments", "Billing"]}
• project_team_areas: {"project": {"entity_provider_id": "..."}, "team": {"entity_provider_id": "..."}, "areas": [{"entity_provider_id": "..."}]}

For example, a team scoped to boards 101 and 102 on integration 1001, sent {"integration_id": 1001, "scope": {"boards": [{"entity_provider_id": "109"}]}}:

• with PATCH (or PATCH ?mode=merge) ends up on board 109 only;
• with PATCH ?mode=add ends up on boards 101, 102 and 109.

Rules:

• Fields that Get Team PM Scope returns but a write does not take (team_name, provider, integration_name, the name of a board, project, team or area, an epic's provider_key) are accepted and ignored, so each item of a Get response can be sent back as is, under its team_id in teams. They are not needed: the shapes above are enough. A label's name and a field's value are part of the scope, not display fields: keep them. With POST, leave out the items whose scope is {}.
• Up to 25 team-and-integration items and 1000 entities per call. Naming a team twice, or an integration twice under one team, is a 400.
• Only the provider's scope keys are accepted: Jira boards, epics, labels, fields; Azure Boards project_team_areas. Any other key is rejected with scope_key_not_writable.
• Every entity must exist and be reachable on that integration. An Azure Boards project_team_areas entry needs a project, a team in that project, and at least one area of that team.
• Each (team, integration) item is applied or rejected as a whole.
• Emptying a team's Jira boards switches the team to Kanban, unless the same item sends methodology.
• A scope write also selects for collection what it names (Jira boards and epics, Azure projects), the same as saving in the app. That selection counts against your board / project limit, which is why a scope write can be rejected with license_limit. Removing an entity from a scope does not deselect it: use Select PM Entities for Collection to stop collecting it.

Responses

200 - At least one item was applied

{
 "applied": [{"team_id": 4412, "integration_id": 1001}],
 "rejected": [
    {"team_id": 4412, "integration_id": 1002, "status": 400, "code": "entity_not_found",
     "message": "These do not exist on integration 1002 or are no longer reachable: areas 999"}
  ]
}

400 / 403 / 404 / 500 - Nothing was applied: the status all rejections share, or 400 if they differ (same body)

Clear a Team PM Scope Key

Clears one key of a team's scope on one integration. Same as a PATCH with that key set to [], with the same response.

HTTP request

DELETE  https://public-api.linearb.io/api/v1/pm/config/teams/{team_id}/scope/{scope_key}?integration_id={integration_id}

Parameters

Responses

200 - Successful Response

{"applied": [{"team_id": 4412, "integration_id": 1001}], "rejected": []}

400 / 403 / 404 / 500 - As for Write Team PM Scopes

Clear a Team PM Scope

Clears every key of a team's scope on one integration. The team's scopes on other integrations are not touched. On Jira this also switches the team to Kanban. A team that has no scope on that integration gets 200 and nothing changes.

HTTP request

DELETE  https://public-api.linearb.io/api/v1/pm/config/teams/{team_id}/scope?integration_id={integration_id}

Parameters

Responses

200 - Successful Response

{"applied": [{"team_id": 4412, "integration_id": 1001}], "rejected": []}

400 / 403 / 404 / 500 - As for Write Team PM Scopes

Errors and auditing

• A request the endpoint cannot accept returns 400: malformed input, or any query parameter or body field the endpoint does not know. Misspelled fields are refused, never ignored.
• In a write, a problem with one entry or (team, integration) item does not fail the request: that entry comes back under rejected with its own code, and the rest is applied.
• A query parameter given more than once returns 400. Send each parameter once, with several values comma-separated.
• A team or integration that is not in your organization returns 404, never an empty list.
• Every change made through these endpoints is recorded in your organization's audit log, like a change made in the app. See Audit Log.

Error responses

An error comes back in one of three shapes, so check the body as well as the status:

• Nothing applied (the write endpoints): every entry was rejected, each with its own code and message.

  {"applied": [], "rejected": [{"team_id": 4412, "integration_id": 1001, "status": 400, "code": "entity_not_found", "message": "These do not exist on integration 1001 or are no longer reachable: boards 999"}]}
  

• Refused request: a message.

  {"detail": "Unsupported entity type 'sprints'; valid types - Azure Boards: areas, projects, teams; Jira: boards, epics, fields, labels, projects"}
  

• Invalid request (a missing, malformed or unknown parameter or field): a list of validation errors.

  {"detail": [{"type": "missing", "loc": ["query", "integration_id"], "msg": "Field required"}]}
  

A missing or invalid API key returns 403. A 500 means something failed on our side; retry.