> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clavata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Labels via API

> Create, read, update, and delete labels over the public API, and publish immutable label versions from rule text.

<Note>
  This is Moonbounce's label-first experience. If you're looking for the
  policy-first experience, switch using the version selector above.
</Note>

Use these endpoints to manage labels programmatically — for example, when a
platform customer stores many downstream rules in a single Moonbounce account.
Authenticate with an [API key](/integrations_and_developer_tools/api-docs-sdks/api_key_management)
for that account. There is no tenant or customer field on these requests;
labels live flat in the authenticated account.

Exact request and response shapes are in the [API Reference](/api-reference/labels/create-a-label).

## Labels

A **label** is a mutable container: a name, an optional description, and an
optional dataset of examples. Examples attach to the label, not to a version,
so every version of a label is measured against the same accumulated set.

A label may have **zero versions**. That is a valid state — you can create a
bare label, attach examples later, and add rule text when you are ready.

| Method   | Path                   | What it does                                                                       |
| -------- | ---------------------- | ---------------------------------------------------------------------------------- |
| `POST`   | `/v1/labels`           | Create a label. Optionally publish an initial version from `initial_version_text`. |
| `GET`    | `/v1/labels/{labelId}` | Read a label, including a page of versions in stable order.                        |
| `GET`    | `/v1/labels`           | List labels, newest first. Defaults to 100 per page (`page_size` max 1000).        |
| `PATCH`  | `/v1/labels/{labelId}` | Update **metadata only**: `name`, `description`, `disabled`.                       |
| `DELETE` | `/v1/labels/{labelId}` | Soft-delete a label that has **no** versions.                                      |

Cross-account IDs return `NOT_FOUND`.

### Create

```http theme={null}
POST /v1/labels
```

```json theme={null}
{
  "name": "ingestion-deny-pii",
  "initial_version_text": "LABEL \"ingestion-deny-pii\" {\n  \"Contains personally identifiable information\"?\n}"
}
```

Creating with only `name` is supported. On create, `description` is stored on
the **initial version** when `initial_version_text` is also sent. To set the
label's own human-facing description, `PATCH` the label after create.

### Patch is metadata only

```http theme={null}
PATCH /v1/labels/{labelId}
```

```json theme={null}
{
  "name": "ingestion-deny-pii",
  "description": "Customer rule: block PII before memory ingest"
}
```

`PATCH` cannot create, mutate, or delete versions. Unknown JSON fields such as
rule `text` are ignored. To change a rule, create a new version.

### Delete does not cascade versions

`DELETE` fails with `FAILED_PRECONDITION` if the label has any versions
(including soft-deleted versions). Versions are immutable and have no delete
RPC. Archive the label in the dashboard when it still has versions you need to
keep.

## Label versions

A **version** is the evaluable artifact: the rule text and its compiled form.
Versions are **immutable**. There is no update, delete, or promote/publish-as-live
operation. There is no "current" version — evaluation always uses an explicit
version ID that you store on your side.

| Method | Path                                             | What it does                                                               |
| ------ | ------------------------------------------------ | -------------------------------------------------------------------------- |
| `POST` | `/v1/labels/{labelId}/versions`                  | Compile `text` (single-label DSL) and publish an immutable version.        |
| `GET`  | `/v1/labels/{labelId}/versions/{labelVersionId}` | Read a version.                                                            |
| `GET`  | `/v1/labels/{labelId}/versions`                  | List versions on a label. Defaults to 100 per page (`page_size` max 1000). |

List and get-label return versions in **stable order**: `sequential_version`
ascending (oldest first), then version ID. A label with zero versions returns
an empty list. When a label has more versions than fit in one page, responses
include `next_page_token`; continue with `GET /v1/labels/{labelId}/versions`.

Reading a version at any later time returns the same rule content and compiled
form. Changing behavior means creating a new version and pointing your own
`customer → version ID` mapping at it.

## Evaluation

Evaluate by **version ID**, never by label ID:

```http theme={null}
POST /v1/labels/evaluate
```

`label_version_ids` is required. A label with no versions has nothing to
evaluate; sending an empty `label_version_ids` list is rejected as invalid
argument. See [Integrating a Label](/v2/integrating_a_label).

## Where to next

<CardGroup cols={2}>
  <Card title="Integrating a Label" icon="plug" href="/v2/integrating_a_label">
    Evaluate content against published version IDs.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/labels/create-a-label">
    Request and response shapes for every label endpoint.
  </Card>
</CardGroup>

***

## We'd Love to Hear From You

Whether you have a suggestion, feedback, or a bug to report, here are the best ways to get in touch:

* **In the App:** Use the **Feedback button** for direct suggestions.
* **On Slack:** Reach out to the team in your shared channel.
* **With your AM:** Talk to your dedicated account manager.
* **Via Email:** Send a message to [**support@moonbounce.io**](mailto:support@moonbounce.io).
* **Security, availability, or other incidents:** Use the in-app **Feedback button** or email [**support@moonbounce.io**](mailto:support@moonbounce.io). See [Customer Feedback](/feedback/customer_feedback) for what to include.