---
title: "Replace Team PM Scopes"
method: POST
path: "/api/v1/pm/config/teams/scope"
tags: ["PM Configuration"]
---

# Replace Team PM Scopes

`POST /api/v1/pm/config/teams/scope`

## Request

- Base URL: `https://public-api.linearb.io`
- URL: `https://public-api.linearb.io/api/v1/pm/config/teams/scope`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/linearb/apis/linearb-api/docs/api/v1/pm/config/teams/scope/post.ts> (a function with typed inputs; its response is checked against the schema)

Replaces the team's document on each integration an item names, and no other; a key the item omits is cleared. Each item must name at least one scope key; clearing a whole document is a DELETE of the team's scope

## Request body

- TeamScopeReplaceRequestModel: A replace: every item names at least one scope key, so clearing a whole document is never implicit.
  - `teams` TeamScopeReplaceTeamModel[], required: The teams to write. At most 25 team-and-integration items and 1000 entities per request, counted across all teams.
    - `team_id` integer, required: The team whose scope is written
    - `items` TeamScopeReplaceItemModel[], required: One per integration
      - `integration_id` integer, required: The integration the document belongs to
      - `scope` TeamScopeWriteDocumentModel, required: The published shape of a written scope: jira `boards`, `epics`, `labels`, `fields`; azure `project_team_areas`
        - `boards` ScopeEntityWriteModel[]
          - `entity_provider_id` string, required
          - `name` string, nullable: Returned by the read; accepted and ignored on a write
        - `epics` ScopeEpicWriteModel[]
          - `entity_provider_id` string, required
          - `provider_key` string, nullable: Returned by the read; accepted and ignored on a write
        - `labels` ScopeLabelWriteModel[]
          - `name` string, required
        - `fields` ScopeFieldWriteModel[]
          - `entity_provider_id` string, required
          - `value` string[]
        - `project_team_areas` ProjectTeamAreasWriteModel[]
          - `project` ScopeEntityWriteModel, required: A board, or an azure project / team / area: accepts the `name` its read returns.
            - `entity_provider_id` string, required
            - `name` string, nullable: Returned by the read; accepted and ignored on a write
          - `team` ScopeEntityWriteModel, required: A board, or an azure project / team / area: accepts the `name` its read returns.
            - `entity_provider_id` string, required
            - `name` string, nullable: Returned by the read; accepted and ignored on a write
          - `areas` ScopeEntityWriteModel[], required
            - `entity_provider_id` string, required
            - `name` string, nullable: Returned by the read; accepted and ignored on a write
      - `methodology` 'Scrum' | 'Kanban' | 'null', nullable: The team's methodology on this integration. Omitted leaves it unchanged
      - `provider` string, nullable: Returned by the read; accepted and ignored on a write
      - `integration_name` string, nullable: Returned by the read; accepted and ignored on a write
    - `team_name` string, nullable: Returned by the read; accepted and ignored on a write

## Response `200`

Successful Response

- TeamScopeWriteResponseModel
  - `applied` TeamScopeAppliedModel[], required
    - `team_id` integer, required
    - `integration_id` integer, required
  - `rejected` TeamScopeRejectedModel[], required
    - `team_id` integer, required
    - `integration_id` integer, required
    - `status` integer, required: The HTTP status this document alone would have been refused with
    - `code` 'team_not_found' | 'integration_not_found' | 'provider_not_supported' | 'integration_read_only' | 'scope_key_not_writable' | 'invalid_scope' | 'entity_not_found' | 'license_limit' | 'write_failed', required: Why one (team, integration) document of a scope write was not applied.
    - `message` string, required

## Other responses

- `400`: Bad Request, or every document was refused for different reasons
- `401`: Unauthorized
- `403`: The caller may not change PM configuration, or the license limit
- `404`: Every document named a team or integration that was not found
- `405`: Method Not Allowed
- `409`: Conflict
- `500`: Internal Server Error
- `504`: Gateway Timeout

---

[API](https://skmtc.dev/linearb/apis/linearb-api.md) - [All operations](https://skmtc.dev/linearb/apis/linearb-api/llms.txt) - [OpenAPI document](https://skmtc.dev/linearb/apis/linearb-api/revisions/3aea06710db6?raw)