API reference

Labels

The workspace's label catalogue.

A label is global within the workspace: there is no project label and no epic label, and it does not cross workspaces.

GET/api/tags

Role: ViewerWorkspace

The label catalogue of a workspace.

Query parameters

Field	Type	Description
`tenant`	`cuid`	When absent: todos os espaços da pessoa

Request

curl -s "http://localhost:3000/api/tags?tenant=cmsp4djx60002p801o7ybpkv7" \
  -H "Authorization: Bearer $TOKEN"

Response200

[
  {
    "id": "cmttg1vnk0011lf01q0eswms5",
    "name": "api",
    "color": "mint"
  }
]

Error responses

Code	When it happens
`401`	No credential, or one that no longer holds. Send the session cookie or the `Authorization: Bearer` header.
`403`	The account does not reach the resource's workspace. It is 403 and not 404 on purpose: the answer reveals no workspace.

POST/api/tags

Role: MemberWorkspace

Creates a label.

Request body

Field	Type	Description
`tenantId`required	`cuid`
`name`required	`string`
`color`	`acento`	Accent token only, no free hex, unlike project and workspace.When absent: sugerido pelo servidor

Request

curl -s -X POST http://localhost:3000/api/tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "cmsp4djx60002p801o7ybpkv7",
    "name": "api",
    "color": "mint"
  }'

Response201

{
  "id": "cmttg1vnk0011lf01q0eswms5",
  "name": "api",
  "color": "mint"
}

Error responses

Code	When it happens
`401`	No credential, or one that no longer holds. Send the session cookie or the `Authorization: Bearer` header.
`403`	The account does not reach the resource's workspace. It is 403 and not 404 on purpose: the answer reveals no workspace.
`409`	A record with that name already exists in the same workspace.
`422`	The body did not pass the schema. The `details` field carries zod's `fieldErrors` and `formErrors`, field by field.

PATCH/api/tags/[id]

Role: MemberWorkspace

Renames or recolours a label.

Path parameters

Field	Type	Description
`id`required	`cuid`

Request body

Field	Type	Description
`name`	`string`
`color`	`acento`

Request

curl -s -X PATCH http://localhost:3000/api/tags/cmttg1vnk0011lf01q0eswms5 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "color": "sage" }'

Response200

{
  "id": "cmttg1vnk0011lf01q0eswms5",
  "name": "api",
  "color": "sage"
}

Error responses

Code	When it happens
`401`	No credential, or one that no longer holds. Send the session cookie or the `Authorization: Bearer` header.
`403`	The account does not reach the resource's workspace. It is 403 and not 404 on purpose: the answer reveals no workspace.
`404`	The resource does not exist, or has already been deleted.
`409`	A record with that name already exists in the same workspace.
`422`	The body came empty. An absent field means do not touch, so a `PATCH` with no field would have no effect at all.

DELETE/api/tags/[id]

Role: MemberWorkspace

Deletes the label, taking it off the cards that used it.

Path parameters

Field	Type	Description
`id`required	`cuid`

Request

curl -s -X DELETE http://localhost:3000/api/tags/cmttg1vnk0011lf01q0eswms5 \
  -H "Authorization: Bearer $TOKEN"

Response200

{ "deleted": true }

Error responses

Code	When it happens
`401`	No credential, or one that no longer holds. Send the session cookie or the `Authorization: Bearer` header.
`403`	The account does not reach the resource's workspace. It is 403 and not 404 on purpose: the answer reveals no workspace.
`404`	The resource does not exist, or has already been deleted.