Resource and endpoint conventions

Your personal library or a library you name

Paths without a library act on your personal library: GET /references, POST /folders, and so on. Every reference, folder, label, file, and search endpoint also has a long form that names the library, for working in a shared library or a shared folder:

GET /references                          → your personal library
GET /libraries/{library_id}/references   → the library you name

Apart from library_id, the two forms take the same parameters and request bodies and return the same responses. personal is a valid library_id, so GET /libraries/personal/references is the same as GET /references. This reference documents the short form only; GET /libraries lists the libraries you can name.

File endpoints with a reference in the path

File endpoints also accept a reference in the path, /references/{reference_id}/files/…:

• GET /references/{reference_id}/files lists that reference's files, the same as GET /files?reference={reference_id}.
• The single-file endpoints, /references/{reference_id}/files/{file_id} and below, find the file by its ID and answer exactly like their /files/{file_id} form.
• Uploading only exists with a reference, POST /references/{reference_id}/files, because every file belongs to one.

Query filters and nested paths

Some lists can be reached through a query filter or through a nested path:

Query filter	Nested path
GET /folders?parent={id}	GET /folders/{folder_id}/folders
GET /references?folder={id}	GET /folders/{folder_id}/references
GET /references?label={id}	GET /labels/{label_id}/references
GET /files?reference={id}	GET /references/{reference_id}/files

Each pair returns the same items, in the same envelope, with one exception: GET /folders/{folder_id}/folders returns a bare array rather than the { data, total, cursor } envelope of GET /folders?parent={id}.