color and icon here are the same ones users pick in the app — see Creating & customizing Labels for what they look like there.
Create a label
POST /v1/labels mints a label in the focused project:
color and icon are optional. Use this when you want display metadata before attaching.
Response (201):
List labels
GET /v1/labels returns every label in the project. Pagination fields match other list endpoints, but has_more is always false in v1 because the per-project label cap bounds the list.
chief labels list shows every label in the project.
Attach a label to an asset
POST /v1/assets/{id}/labels resolves a label by name within the project:
label_name is idempotent.
Response (201):
Use labels in chats
Pass label ids inscope.label_ids on POST /v1/chats or POST /v1/chats/{id}/messages to expand associated assets and concepts into the assistant’s context. See Chats.
FAQ
What happens if I attach a label name that does not exist?
What happens if I attach a label name that does not exist?
The API creates a bare label with that name — no color or icon — and attaches it. Create the label first with
POST /v1/labels when you want display metadata.Is attaching the same label twice safe?
Is attaching the same label twice safe?
Yes. Re-sending the same
label_name against the same asset is idempotent.Why is has_more always false when listing labels?
Why is has_more always false when listing labels?
GET /v1/labels returns every label in the project in v1. The per-project label cap bounds the list, so there is never a second page.How do labels affect what the assistant reads?
How do labels affect what the assistant reads?
Passing label ids in
scope.label_ids expands the assets and concepts associated with those labels into the assistant’s context. See Chats.