> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/development/api-reference-app/label.md).
# Label
A **label** is a free tag on a ticket, defined per tenant and identified by its `name`. Tickets carry any number of them, and `PATCH /v1/tickets/{ticketId}` replaces the whole set at once.
`autoAssign` opens a label to automatic classification: only labels with it switched on are candidates, and then `assignmentContext` is what the classification reads — `description` stays the human-facing text.
## List labels
> Returns the tenant's labels, ordered by \`id\` unless \`sort\` says otherwise.\
> \
> \*\*Filterable\*\* — \`id\`, \`tenantId\`, \`name\`, \`description\`, \`color\`, \`autoAssign\`,\
> \`assignmentContext\`, \`createdAt\`, \`updatedAt\`.\
> \
> \*\*Sortable\*\* — \`id\`, \`name\`, \`createdAt\`, \`updatedAt\`.\
> \
> \*\*Searchable\*\* — nothing yet; use \`filter\` with \`contains\` on \`name\`.
```json
{"openapi":"3.1.0","info":{"title":"Solvio REST API","version":"1.0.0-beta"},"tags":[{"description":"A **label** is a free tag on a ticket, defined per tenant and identified by its `name`. Tickets carry\nany number of them, and `PATCH /v1/tickets/{ticketId}` replaces the whole set at once.\n\n`autoAssign` opens a label to automatic classification: only labels with it switched on are\ncandidates, and then `assignmentContext` is what the classification reads — `description` stays the\nhuman-facing text.\n","name":"label"}],"servers":[{"description":"The host serving this document","url":"/api"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Token issued by the central equipme authentication, sent as `Bearer `.","scheme":"bearer","type":"http"},"ApiKeyAuth":{"description":"Static key for machine-to-machine access. Alternative to BearerAuth.","in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"v1.ListLabelsResponse-domain_Label":{"properties":{"count":{"type":"integer"},"data":{"items":{"$ref":"#/components/schemas/domain.Label"},"type":"array","uniqueItems":false}},"type":"object"},"domain.Label":{"properties":{"assignmentContext":{"type":"string"},"autoAssign":{"description":"AutoAssign / AssignmentContext gate AI label classification: a label is a candidate only\nwhen AutoAssign is on, and then AssignmentContext must be non-empty. Description stays\nhuman-facing — the model reads AssignmentContext.","type":"boolean"},"color":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"tenant":{"$ref":"#/components/schemas/domain.Tenant"},"tenantId":{"type":"integer"},"updatedAt":{"format":"date-time","type":"string"}},"type":"object"},"domain.Tenant":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"middleware.ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/middleware.ErrorBody"}},"type":"object"},"middleware.ErrorBody":{"properties":{"code":{"description":"Code is the stable, machine-readable reason. Clients match on this, not on the message.","type":"string"},"details":{"description":"Details carries structured context where an error has any — a conflict names what it\ncollided with. Absent otherwise."},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v1/labels":{"get":{"description":"Returns the tenant's labels, ordered by `id` unless `sort` says otherwise.\n\n**Filterable** — `id`, `tenantId`, `name`, `description`, `color`, `autoAssign`,\n`assignmentContext`, `createdAt`, `updatedAt`.\n\n**Sortable** — `id`, `name`, `createdAt`, `updatedAt`.\n\n**Searchable** — nothing yet; use `filter` with `contains` on `name`.\n","operationId":"listLabels","parameters":[{"description":"JSON filter expression","in":"query","name":"filter","schema":{"type":"string"}},{"description":"Free-text term — no effect here","in":"query","name":"search","schema":{"type":"string"}},{"description":"Comma-separated field:direction terms","in":"query","name":"sort","schema":{"type":"string"}},{"description":"Selection of fields and relations","in":"query","name":"fields","schema":{"type":"string"}},{"description":"Number of entries to skip","in":"query","name":"offset","schema":{"default":0,"type":"integer"}},{"description":"Page size, 1 to 100","in":"query","name":"limit","schema":{"default":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.ListLabelsResponse-domain_Label"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Internal Server Error"}},"summary":"List labels","tags":["label"]}}}}
```
## Create labels
> Creates labels — several at once, since they are usually set up as a set. Each entry needs a \`name\`,\
> which identifies the label within the tenant.\
> \
> A name that already exists is \*\*kept as it is\*\*: the request succeeds and returns the existing label\
> unchanged, rather than failing or overwriting its description and colour. Use \`PATCH\` to change one.
```json
{"openapi":"3.1.0","info":{"title":"Solvio REST API","version":"1.0.0-beta"},"tags":[{"description":"A **label** is a free tag on a ticket, defined per tenant and identified by its `name`. Tickets carry\nany number of them, and `PATCH /v1/tickets/{ticketId}` replaces the whole set at once.\n\n`autoAssign` opens a label to automatic classification: only labels with it switched on are\ncandidates, and then `assignmentContext` is what the classification reads — `description` stays the\nhuman-facing text.\n","name":"label"}],"servers":[{"description":"The host serving this document","url":"/api"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Token issued by the central equipme authentication, sent as `Bearer `.","scheme":"bearer","type":"http"},"ApiKeyAuth":{"description":"Static key for machine-to-machine access. Alternative to BearerAuth.","in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"v1.AddLabelsRequest":{"properties":{"labels":{"items":{"$ref":"#/components/schemas/v1.AddLabelsRequestItem"},"minItems":1,"type":"array","uniqueItems":false}},"required":["labels"],"type":"object"},"v1.AddLabelsRequestItem":{"properties":{"assignmentContext":{"type":"string"},"autoAssign":{"type":"boolean"},"color":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"}},"required":["name"],"type":"object"},"v1.AddLabelsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/domain.Label"},"type":"array","uniqueItems":false}},"type":"object"},"domain.Label":{"properties":{"assignmentContext":{"type":"string"},"autoAssign":{"description":"AutoAssign / AssignmentContext gate AI label classification: a label is a candidate only\nwhen AutoAssign is on, and then AssignmentContext must be non-empty. Description stays\nhuman-facing — the model reads AssignmentContext.","type":"boolean"},"color":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"tenant":{"$ref":"#/components/schemas/domain.Tenant"},"tenantId":{"type":"integer"},"updatedAt":{"format":"date-time","type":"string"}},"type":"object"},"domain.Tenant":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"middleware.ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/middleware.ErrorBody"}},"type":"object"},"middleware.ErrorBody":{"properties":{"code":{"description":"Code is the stable, machine-readable reason. Clients match on this, not on the message.","type":"string"},"details":{"description":"Details carries structured context where an error has any — a conflict names what it\ncollided with. Absent otherwise."},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v1/labels":{"post":{"description":"Creates labels — several at once, since they are usually set up as a set. Each entry needs a `name`,\nwhich identifies the label within the tenant.\n\nA name that already exists is **kept as it is**: the request succeeds and returns the existing label\nunchanged, rather than failing or overwriting its description and colour. Use `PATCH` to change one.\n","operationId":"addLabels","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"$ref":"#/components/schemas/v1.AddLabelsRequest","summary":"request","description":"Labels to create"}]}}},"description":"Labels to create","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.AddLabelsResponse"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Create labels","tags":["label"]}}}}
```
## Get a label
> Returns a single label by its id.
```json
{"openapi":"3.1.0","info":{"title":"Solvio REST API","version":"1.0.0-beta"},"tags":[{"description":"A **label** is a free tag on a ticket, defined per tenant and identified by its `name`. Tickets carry\nany number of them, and `PATCH /v1/tickets/{ticketId}` replaces the whole set at once.\n\n`autoAssign` opens a label to automatic classification: only labels with it switched on are\ncandidates, and then `assignmentContext` is what the classification reads — `description` stays the\nhuman-facing text.\n","name":"label"}],"servers":[{"description":"The host serving this document","url":"/api"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Token issued by the central equipme authentication, sent as `Bearer `.","scheme":"bearer","type":"http"},"ApiKeyAuth":{"description":"Static key for machine-to-machine access. Alternative to BearerAuth.","in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"v1.GetLabelResponse-domain_Label":{"properties":{"data":{"$ref":"#/components/schemas/domain.Label"}},"type":"object"},"domain.Label":{"properties":{"assignmentContext":{"type":"string"},"autoAssign":{"description":"AutoAssign / AssignmentContext gate AI label classification: a label is a candidate only\nwhen AutoAssign is on, and then AssignmentContext must be non-empty. Description stays\nhuman-facing — the model reads AssignmentContext.","type":"boolean"},"color":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"tenant":{"$ref":"#/components/schemas/domain.Tenant"},"tenantId":{"type":"integer"},"updatedAt":{"format":"date-time","type":"string"}},"type":"object"},"domain.Tenant":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"middleware.ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/middleware.ErrorBody"}},"type":"object"},"middleware.ErrorBody":{"properties":{"code":{"description":"Code is the stable, machine-readable reason. Clients match on this, not on the message.","type":"string"},"details":{"description":"Details carries structured context where an error has any — a conflict names what it\ncollided with. Absent otherwise."},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v1/labels/{labelId}":{"get":{"description":"Returns a single label by its id.\n","operationId":"getLabel","parameters":[{"description":"Label id","in":"path","name":"labelId","required":true,"schema":{"type":"integer"}},{"description":"Selection of fields and relations","in":"query","name":"fields","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.GetLabelResponse-domain_Label"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Not Found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Get a label","tags":["label"]}}}}
```
## Delete a label
> Deletes a label and detaches it from every ticket that carried it. The tickets themselves are\
> untouched. Answers with \`204\` and no body.
```json
{"openapi":"3.1.0","info":{"title":"Solvio REST API","version":"1.0.0-beta"},"tags":[{"description":"A **label** is a free tag on a ticket, defined per tenant and identified by its `name`. Tickets carry\nany number of them, and `PATCH /v1/tickets/{ticketId}` replaces the whole set at once.\n\n`autoAssign` opens a label to automatic classification: only labels with it switched on are\ncandidates, and then `assignmentContext` is what the classification reads — `description` stays the\nhuman-facing text.\n","name":"label"}],"servers":[{"description":"The host serving this document","url":"/api"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Token issued by the central equipme authentication, sent as `Bearer `.","scheme":"bearer","type":"http"},"ApiKeyAuth":{"description":"Static key for machine-to-machine access. Alternative to BearerAuth.","in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"middleware.ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/middleware.ErrorBody"}},"type":"object"},"middleware.ErrorBody":{"properties":{"code":{"description":"Code is the stable, machine-readable reason. Clients match on this, not on the message.","type":"string"},"details":{"description":"Details carries structured context where an error has any — a conflict names what it\ncollided with. Absent otherwise."},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v1/labels/{labelId}":{"delete":{"description":"Deletes a label and detaches it from every ticket that carried it. The tickets themselves are\nuntouched. Answers with `204` and no body.\n","operationId":"deleteLabel","parameters":[{"description":"Label id","in":"path","name":"labelId","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"No Content"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Not Found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Delete a label","tags":["label"]}}}}
```
## Change a label
> Changes a label. The body follows JSON Merge Patch semantics: an absent field stays as it is, \`null\`\
> clears it, a value sets it.\
> \
> Renaming a label keeps it attached to its tickets — they refer to it by id, not by name.
```json
{"openapi":"3.1.0","info":{"title":"Solvio REST API","version":"1.0.0-beta"},"tags":[{"description":"A **label** is a free tag on a ticket, defined per tenant and identified by its `name`. Tickets carry\nany number of them, and `PATCH /v1/tickets/{ticketId}` replaces the whole set at once.\n\n`autoAssign` opens a label to automatic classification: only labels with it switched on are\ncandidates, and then `assignmentContext` is what the classification reads — `description` stays the\nhuman-facing text.\n","name":"label"}],"servers":[{"description":"The host serving this document","url":"/api"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Token issued by the central equipme authentication, sent as `Bearer `.","scheme":"bearer","type":"http"},"ApiKeyAuth":{"description":"Static key for machine-to-machine access. Alternative to BearerAuth.","in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"v1.PatchLabelRequest":{"properties":{"assignmentContext":{"type":"string"},"autoAssign":{"type":"boolean"},"color":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"}},"type":"object"},"v1.PatchLabelResponse":{"properties":{"data":{"$ref":"#/components/schemas/domain.Label"}},"type":"object"},"domain.Label":{"properties":{"assignmentContext":{"type":"string"},"autoAssign":{"description":"AutoAssign / AssignmentContext gate AI label classification: a label is a candidate only\nwhen AutoAssign is on, and then AssignmentContext must be non-empty. Description stays\nhuman-facing — the model reads AssignmentContext.","type":"boolean"},"color":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"tenant":{"$ref":"#/components/schemas/domain.Tenant"},"tenantId":{"type":"integer"},"updatedAt":{"format":"date-time","type":"string"}},"type":"object"},"domain.Tenant":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"middleware.ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/middleware.ErrorBody"}},"type":"object"},"middleware.ErrorBody":{"properties":{"code":{"description":"Code is the stable, machine-readable reason. Clients match on this, not on the message.","type":"string"},"details":{"description":"Details carries structured context where an error has any — a conflict names what it\ncollided with. Absent otherwise."},"message":{"type":"string"}},"type":"object"}}},"paths":{"/v1/labels/{labelId}":{"patch":{"description":"Changes a label. The body follows JSON Merge Patch semantics: an absent field stays as it is, `null`\nclears it, a value sets it.\n\nRenaming a label keeps it attached to its tickets — they refer to it by id, not by name.\n","operationId":"patchLabel","parameters":[{"description":"Label id","in":"path","name":"labelId","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"$ref":"#/components/schemas/v1.PatchLabelRequest","summary":"request","description":"Fields to change"}]}}},"description":"Fields to change","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.PatchLabelResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Not Found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/middleware.ErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Change a label","tags":["label"]}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://hub.equipme.io/development/api-reference-app/label.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.