Favorite
One pinned item in the caller's own sidebar. You only ever see, create and delete your own.
type decides what resourceId points at, and two of the types also need a projectId:
type | resourceId | projectId |
|---|---|---|
project, projectEmbed | required | required |
document, file, fileFolder, documentFolder | required | — |
personalNotes, personalTasks, createdByMe | — | — |
The last three are standing personal views rather than a pinned item.
name is a label you supply and the server never refreshes it, so a renamed project keeps its old favorite label until you update it.
List Favorites
List favorites. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by order unless you pass sort.
Required scope: favorites:read
query Parameters
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: order.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
type[eq]Filter where type equals.
type[in]Filter where type is one of (comma-separated list).
favoriteFolderId[eq]Filter where favoriteFolderId equals.
favoriteFolderId[in]Filter where favoriteFolderId is one of (comma-separated list).
projectId[eq]Filter where projectId equals.
projectId[in]Filter where projectId is one of (comma-separated list).
List Favorites › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Create Favorite
Create a Favorite. Server-assigned fields are ignored if sent.
Required scope: favorites:write
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create Favorite › Request Body
nameThe label shown in the sidebar. It is a snapshot you supply, NOT a live mirror — rename the project and the favorite keeps the old label until you update it yourself.
typeWhat kind of thing is favorited, and therefore what resourceId must point at: project (a project id, plus projectId), document (a document id), file (a file id), fileFolder / documentFolder (a folder id), projectEmbed (an embed id, plus projectId). personalNotes, personalTasks and createdByMe are standing personal views rather than a specific item — they take no resourceId. Set once: re-pointing a favorite means deleting it and creating another.
orderRank within the sidebar. Omit it on create to append at the end (the server assigns the next rank); supply one to place it explicitly. Settable on update for drag-and-drop reordering — pick a value between the two neighbours you are dropping between.
resourceIdThe id of the favorited item. Required for every type except the three standing personal views (personalNotes, personalTasks, createdByMe), which take none. Set once — a favorite cannot be re-pointed.
projectIdThe project a project or projectEmbed favorite lives in. Required for those two types, ignored for the rest.
favoriteFolderIdFolder grouping this favorite. Null = top-level (not in any folder). Mutable — favorites move between folders.
Create Favorite › Responses
Created
idUnique identifier for this resource.
createdAtCreation timestamp.
nameThe label shown in the sidebar. It is a snapshot you supply, NOT a live mirror — rename the project and the favorite keeps the old label until you update it yourself.
typeWhat kind of thing is favorited, and therefore what resourceId must point at: project (a project id, plus projectId), document (a document id), file (a file id), fileFolder / documentFolder (a folder id), projectEmbed (an embed id, plus projectId). personalNotes, personalTasks and createdByMe are standing personal views rather than a specific item — they take no resourceId. Set once: re-pointing a favorite means deleting it and creating another.
memberIdThe team member this favorite belongs to. Set by the server from whoever is calling — you only ever see your own.
updatedAtLast update timestamp.
orderRank within the sidebar. Omit it on create to append at the end (the server assigns the next rank); supply one to place it explicitly. Settable on update for drag-and-drop reordering — pick a value between the two neighbours you are dropping between.
resourceIdThe id of the favorited item. Required for every type except the three standing personal views (personalNotes, personalTasks, createdByMe), which take none. Set once — a favorite cannot be re-pointed.
projectIdThe project a project or projectEmbed favorite lives in. Required on create for those two types and ignored for the rest. Set once — a favorite cannot be re-pointed.
favoriteFolderIdFolder grouping this favorite. Null = top-level (not in any folder). Mutable — favorites move between folders.
The related Team Member, present only when you pass ?expand=member.
The related Favorite Folder, present only when you pass ?expand=favoriteFolder.
The related Project, present only when you pass ?expand=project.
Get Favorite
Retrieve a single Favorite by id.
Required scope: favorites:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Favorite.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Favorite › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
nameThe label shown in the sidebar. It is a snapshot you supply, NOT a live mirror — rename the project and the favorite keeps the old label until you update it yourself.
typeWhat kind of thing is favorited, and therefore what resourceId must point at: project (a project id, plus projectId), document (a document id), file (a file id), fileFolder / documentFolder (a folder id), projectEmbed (an embed id, plus projectId). personalNotes, personalTasks and createdByMe are standing personal views rather than a specific item — they take no resourceId. Set once: re-pointing a favorite means deleting it and creating another.
memberIdThe team member this favorite belongs to. Set by the server from whoever is calling — you only ever see your own.
updatedAtLast update timestamp.
orderRank within the sidebar. Omit it on create to append at the end (the server assigns the next rank); supply one to place it explicitly. Settable on update for drag-and-drop reordering — pick a value between the two neighbours you are dropping between.
resourceIdThe id of the favorited item. Required for every type except the three standing personal views (personalNotes, personalTasks, createdByMe), which take none. Set once — a favorite cannot be re-pointed.
projectIdThe project a project or projectEmbed favorite lives in. Required on create for those two types and ignored for the rest. Set once — a favorite cannot be re-pointed.
favoriteFolderIdFolder grouping this favorite. Null = top-level (not in any folder). Mutable — favorites move between folders.
The related Team Member, present only when you pass ?expand=member.
The related Favorite Folder, present only when you pass ?expand=favoriteFolder.
The related Project, present only when you pass ?expand=project.
Delete Favorite
Permanently delete this Favorite. This cannot be undone.
Required scope: favorites:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Favorite.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Favorite › Responses
No Content
Update Favorite
Partially update a Favorite. Only the fields you send are changed.
Required scope: favorites:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Favorite.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Update Favorite › Request Body
nameThe label shown in the sidebar. It is a snapshot you supply, NOT a live mirror — rename the project and the favorite keeps the old label until you update it yourself.
orderRank within the sidebar. Omit it on create to append at the end (the server assigns the next rank); supply one to place it explicitly. Settable on update for drag-and-drop reordering — pick a value between the two neighbours you are dropping between.
favoriteFolderIdFolder grouping this favorite. Null = top-level (not in any folder). Mutable — favorites move between folders.
expectedUpdatedAtOptional concurrency guard: the updatedAt you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh updatedAt.
Update Favorite › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
nameThe label shown in the sidebar. It is a snapshot you supply, NOT a live mirror — rename the project and the favorite keeps the old label until you update it yourself.
typeWhat kind of thing is favorited, and therefore what resourceId must point at: project (a project id, plus projectId), document (a document id), file (a file id), fileFolder / documentFolder (a folder id), projectEmbed (an embed id, plus projectId). personalNotes, personalTasks and createdByMe are standing personal views rather than a specific item — they take no resourceId. Set once: re-pointing a favorite means deleting it and creating another.
memberIdThe team member this favorite belongs to. Set by the server from whoever is calling — you only ever see your own.
updatedAtLast update timestamp.
orderRank within the sidebar. Omit it on create to append at the end (the server assigns the next rank); supply one to place it explicitly. Settable on update for drag-and-drop reordering — pick a value between the two neighbours you are dropping between.
resourceIdThe id of the favorited item. Required for every type except the three standing personal views (personalNotes, personalTasks, createdByMe), which take none. Set once — a favorite cannot be re-pointed.
projectIdThe project a project or projectEmbed favorite lives in. Required on create for those two types and ignored for the rest. Set once — a favorite cannot be re-pointed.
favoriteFolderIdFolder grouping this favorite. Null = top-level (not in any folder). Mutable — favorites move between folders.
The related Team Member, present only when you pass ?expand=member.
The related Favorite Folder, present only when you pass ?expand=favoriteFolder.
The related Project, present only when you pass ?expand=project.
Search Favorites
Full-text ranked search across favorites. Ranked by relevance; pages are capped at 200 results. Filterable by 4 fields.
Required scope: favorites:read
query Parameters
qFull-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
type[eq]Filter where type equals.
type[in]Filter where type is one of (comma-separated list).
favoriteFolderId[eq]Filter where favoriteFolderId equals.
favoriteFolderId[in]Filter where favoriteFolderId is one of (comma-separated list).
projectId[eq]Filter where projectId equals.
projectId[in]Filter where projectId is one of (comma-separated list).
Search Favorites › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.