---
title: "Upsert Label"
method: PUT
path: "/agent/custom/label/{label_id}"
---

# Upsert Label

`PUT /agent/custom/label/{label_id}`

## Request

- Base URL: `https://api.tellers.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tellers.ai/agent/custom/label/{label_id}`
- Auth: none declared

Create a label, or rename one and change who may attach it.

The only route that creates vocabulary, and reviewer-gated like everything
else in this module — which is why nothing here screens what a label is
called. An owner picks from what this produced; they never add to it.

``label_id`` is normalised into a slug and then never rewritten: it is what
every filter and every existing attachment names. Renaming is a
``display_name`` change.

## Path parameters

- `label_id` string, required

## Headers

- `x-api-key` string, nullable
- `authorization` string, nullable

## Request body

- APILabelUpsertRequest: Create a label, or rename one / change who may attach it. The slug is the path parameter and is never rewritten by this: renaming is a ``display_name`` change, because the slug is what every existing filter and attachment names.
  - `display_name` string, required
  - `set_by` 'OWNER' | 'REVIEWER': Who may *attach* a label to an assistant. Creating one is reviewer-only either way: the vocabulary is curated, and an owner picks from it rather than inventing an entry — which is the whole reason nothing here has to screen what a label is called. OWNER says an author may put this label on their own assistant; REVIEWER reserves it, which is what keeps a ``featured`` from being self-awarded.

## Response `200`

Successful Response

- APILabel: One entry in the label vocabulary.
  - `id` string, required
  - `display_name` string, required
  - `set_by` 'OWNER' | 'REVIEWER', required: Who may *attach* a label to an assistant. Creating one is reviewer-only either way: the vocabulary is curated, and an owner picks from it rather than inventing an entry — which is the whole reason nothing here has to screen what a label is called. OWNER says an author may put this label on their own assistant; REVIEWER reserves it, which is what keeps a ``featured`` from being self-awarded.

## Other responses

- `422`: Validation Error

---

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