---
title: "Replace labels assigned to a resource target"
method: PUT
path: "/labels/assignments"
tags: ["labels"]
---

# Replace labels assigned to a resource target

`PUT /labels/assignments`

## Request

- Base URL: `https://api.axiom.co/v2`
- URL: `https://api.axiom.co/v2/labels/assignments`
- Auth: OAuth 2
  - Authorization code: `https://accounts.google.com/o/oauth2/v2/auth`
  - Token URL: `https://www.googleapis.com/oauth2/v4/token`
- TypeScript: <https://skmtc.dev/axiom/apis/axiom-public-api/docs/labels/assignments/put.ts> (a function with typed inputs; its response is checked against the schema)

Replaces the complete label set for one target atomically, ignoring label IDs that do not exist in the caller's organization and removing stale assignments. The response contains only existing label IDs. Concurrent replacements use last-write-wins semantics. The operation requires only the target resource's update permission: dashboards|update, datasets|update, monitors|update, or notifiers|update. Datasets must also be readable, writable, and owned by the caller's organization. Monitor dataset permissions match those required to read the monitor. A target that uses the wrong identifier for its type returns 400. An unknown target type, duplicate label IDs, and more than 500 label IDs fail request validation with 422. A target that does not exist or is not owned by the caller's organization returns 404.

## Request body

- LabelAssignmentsReplace
  - `labelIds` LabelID[], required
  - `target` LabelAssignmentTarget, required: A resource that supports organization labels. Single-identifier targets use id; frontend-generated integration dashboards use templateId and dataset.
    - `dataset` string: Required only for frontend-generated integration dashboards and rejected for other target types. Use the current dataset name. Assignments use the underlying dataset instance, so permanent deletion and recreation do not restore old labels.
    - `id` string: Public identifier for the resource. Use the dashboard UID for a dashboard, the dataset name for a dataset, and the ID returned by the monitor, notifier, or backend-provided integration dashboard APIs.
    - `templateId` string: Stable frontend-owned template key for a frontend-generated integration dashboard, such as k8s.stats. Requires dataset and rejects id. Whitespace and control characters are rejected.
    - `type` 'dashboard' | 'integration_dashboard' | 'dataset' | 'monitor' | 'notifier', required

## Response `200`

The target's complete label set after the atomic replacement.

- LabelAssignmentResult
  - `labelIds` LabelID[], required
  - `target` LabelAssignmentTarget, required: A resource that supports organization labels. Single-identifier targets use id; frontend-generated integration dashboards use templateId and dataset.
    - `dataset` string: Required only for frontend-generated integration dashboards and rejected for other target types. Use the current dataset name. Assignments use the underlying dataset instance, so permanent deletion and recreation do not restore old labels.
    - `id` string: Public identifier for the resource. Use the dashboard UID for a dashboard, the dataset name for a dataset, and the ID returned by the monitor, notifier, or backend-provided integration dashboard APIs.
    - `templateId` string: Stable frontend-owned template key for a frontend-generated integration dashboard, such as k8s.stats. Requires dataset and rejects id. Whitespace and control characters are rejected.
    - `type` 'dashboard' | 'integration_dashboard' | 'dataset' | 'monitor' | 'notifier', required

## Other responses

- `400`: The target uses the wrong identifier for its type.
- `403`: The caller lacks the target resource's update permission, or the dataset is shared or not writable.
- `404`: The target does not exist or is not owned by the caller's organization.
- `422`: Request validation failed. The payload contains an unknown target type, duplicate label IDs, or more than 500 label IDs.

## Changes

- **2026-11-02** (v2) `e3baf3b85e8d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axiom/apis/axiom-public-api/changes/labels/assignments/put.md)

---

[API](https://skmtc.dev/axiom/apis/axiom-public-api.md) - [All operations](https://skmtc.dev/axiom/apis/axiom-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/axiom/apis/axiom-public-api/revisions/7e39a295e3ba?raw)