Workspace Labels

Labels are colored tags scoped to a workspace. They can be assigned to library items (and, in the future, other entities like rooms). Only workspace owners and admins can create, update, or delete labels. All workspace members can read labels and assign them to items.

---

The Label Object

{
  "id": 3,
  "workspace_id": 2,
  "name": "Marketing",
  "color": "#22c55e",
  "created_by": 5,
  "created_by_name": "Jane Smith",
  "created_at": 1711000000
}

Field	Type	Description
id	integer	Unique label ID
workspace_id	integer	Owning workspace
name	string	Label name (unique within the workspace)
color	string	Hex color code (e.g. #22c55e)
created_by	integer	User ID of the creator (null if user deleted)
created_by_name	string	Display name of the creator
created_at	integer	Unix timestamp

---

List Labels

Returns all labels for a workspace, ordered by creation date. Any workspace member can list labels.

GET /api/workspaces/:id/labels

Response:

{
  "labels": [
    {
      "id": 3,
      "name": "Marketing",
      "color": "#22c55e",
      "created_by_name": "Jane Smith",
      "created_at": 1711000000
    },
    {
      "id": 4,
      "name": "Internal",
      "color": "#6366f1",
      "created_by_name": "Jane Smith",
      "created_at": 1711000001
    }
  ]
}

---

Create a Label

Creates a new label for the workspace. Owner or admin only.

POST /api/workspaces/:id/labels

Request body:

{
  "name": "Marketing",
  "color": "#22c55e"
}

Field	Type	Required	Description
name	string	Yes	Label name (must be unique within the workspace)
color	string	No	Hex color code (defaults to #6366f1)

Response:

{
  "label": {
    "id": 3,
    "name": "Marketing",
    "color": "#22c55e",
    "created_at": 1711000000
  }
}

Errors:

Status	Error
400	Name is required
403	Only owners and admins can create labels
409	A label with this name already exists

---

Update a Label

Rename a label or change its color. Owner or admin only.

PATCH /api/workspaces/:id/labels/:labelId

Request body:

{
  "name": "Brand",
  "color": "#f59e0b"
}

Both fields are optional — only send the fields you want to change.

Response:

{
  "label": {
    "id": 3,
    "name": "Brand",
    "color": "#f59e0b",
    "created_at": 1711000000
  }
}

Errors:

Status	Error
403	Only owners and admins can update labels
404	Label not found
409	A label with this name already exists

---

Delete a Label

Deletes a label and removes all its assignments from items. Owner or admin only.

DELETE /api/workspaces/:id/labels/:labelId

Response:

{ "ok": true }

warning

Deleting a label cascades — all assignments of that label to library items (or other entities) are permanently removed.

Errors:

Status	Error
403	Only owners and admins can delete labels
404	Label not found

---

Assigning Labels to Items

Labels are assigned to library items via the Media Library endpoints:

• Assign: POST /api/workspaces/:id/library/:itemId/labels
• Remove: DELETE /api/workspaces/:id/library/:itemId/labels/:labelId