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

### Publishing from plain rule text

`text` is single-label DSL by default. If your rules are written in plain
language and you do not want to construct DSL, set `text_format` and send the
rule as-is:

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

```json theme={null}
{
  "text_format": "TEXT_FORMAT_PLAIN_TEXT",
  "text": "Block memos the sender marked \"confidential\""
}
```

The rule is stored as a single signal. Quotes, newlines, and backslashes in your
text are preserved. Everything else is unchanged: the same immutability, the
same duplicate handling, and the same response shape.

Omitting `text_format`, or sending `TEXT_FORMAT_DSL`, keeps the DSL behavior.

Reading the version back returns the compiled DSL, not the text you submitted,
so keep your own copy of the original rule if you need it.

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.