Labels

Labels are colored tags for organizing references. Unlike folders, labels have a flat structure with no hierarchy.

A reference can have multiple labels. Removing a label from a reference or deleting the label does not delete the reference itself. Deleting a label keeps the labeled references by default; pass trash_references=true to move those references to the trash instead.

Labels are best suited for cross-cutting themes like status ("To Read", "Important") or topics that span multiple folders.

The labels list is not paginated — every label is returned in a single response and cursor is always null, so the limit and cursor parameters do not apply. The references carrying a label (GET /labels/{label_id}/references) are paginated like the main references list and return a real cursor. To add or remove a label on references, send the reference IDs in the request body as { "ids": [...] }.

Every label operation is also available scoped to a specific library under /libraries/{library_id}/labels. The non-scoped form operates on your personal library; the scoped form targets one library, such as a shared library.

See the Label object for the full schema.