Skip to content

Canvases API

List, create, edit, archive, and delete canvases, and manage the items and connectors on them.

Native session clients can subscribe to mobile:canvases and mobile:canvas with organizationId. The list accepts projectId, cursor and limit. A view-only canvas read includes up to 120 items and 240 connectors, with typed text and media-proxy URLs. A true truncated flag means the full canvas needs the web viewer. To read a whole canvas, page through mobile:canvasItems and mobile:canvasConnectors with canvasId, cursor and limit (up to 200 rows a page). Each page stays live, and items carry the updatedAt revision that edits send back. Hidden embeds and their connectors are omitted.

Session tokens accept the canvas list, a canvas, its items, and one item with canvas:read. Members can also create, rename, archive, and unarchive canvases, and create, edit, and delete items and connectors. Send Authorization: Bearer with X-Project-Feed-Workspace. Viewers can read accessible canvases but get 403 on writes. Private canvases and project access keep the same restrictions. Send expectedUpdatedAt or If-Match on edits so a newer change returns 412 instead of being overwritten. Deleting a canvas, frame exports, and linked cards still require an API credential.

Endpoints

Permissions

Reading needs canvas:read and writing needs canvas:write. A private canvas is visible only to its creator. A canvas you cannot see, including one in a project you cannot open, returns 404. Workspace viewers can read shared canvases but cannot change them.

Canvas reads, item reads and item write responses preserve stored content, richContent, url and urlLabel on task and post items when you can read the referenced resource. Otherwise those fields are null, while layout and taskId/postId references remain. These responses do not resolve task or post titles or bodies. The linked-content endpoint checks each resource and returns null for an inaccessible task or post. It still requires an API credential.

Only the canvas creator and workspace owners and admins can update, archive, restore, or delete a canvas. Other callers get 403. Writes also need write access to the canvas's project. A deleted canvas cannot be restored through the API.

An archived canvas is read-only. Changing it returns 409 until it is restored with POST /canvases/:id/unarchive.

When Canvases is turned off for the workspace, canvas requests return 403.

Lists and limits

The list returns the most recently updated canvases first and pages with nextCursor. See API conventions for cursor handling. A page can hold fewer canvases than the limit, or none, when many canvases in a row are private to someone else. The limit is clamped to 1 to 100.

GET /canvases/:id returns up to 2,000 items and 4,000 connectors, oldest first. When a canvas has more, the response sets truncated to true. A canvas holds at most 5,000 items; adding one past that returns 409.

Canvas items

Item responses use the same fields as each entry in the items array of GET /canvases/:id. The fields frameTitle and borderStyle are set on frames, drawRoute on drawings, and rotation on shapes. They are null on other items. On frames, autoLayout, autoLayoutGap, autoLayoutPadding, and autoLayoutAlign describe how the frame arranges its children. They are null on other items. Anyone who can edit the canvas can add, change, and delete its items. Workspace viewers cannot, and a private canvas accepts item changes only from its creator. Items on an archived canvas return 409.

  • A draw item needs drawKind and drawPoints, and a url item needs url.
  • A frameId that is not a frame on the same canvas is ignored. Frames and stacks can only be placed inside a section.
  • The item ID must belong to the canvas in the path, or the request returns 404. Locked items return 409 on update and delete.
  • Deleting a frame keeps the items inside it on the canvas. It returns 409 when one of those items is locked.
  • The request fields are limited to 256 KB. Larger bodies return 400. Text follows the same length limits as the app.
  • Images, videos, and other files cannot be added as items here. Upload them with a canvas destination through the Files API.

Frames, groups, and layers

The item update takes these structure fields along with position and style:

  • frameId is the ID of a frame on the same canvas, or null to take the item out of its frame. A frame can only go inside a section, and a section cannot go inside anything. An item cannot be placed in itself. A rejected placement returns 400.
  • groupId is a string of up to 128 characters, or null to leave the group.
  • layer is front, back, forward, or backward, and moves the item in the stacking order.
  • autoLayout is horizontal, vertical, grid, or null, and only frames accept it. autoLayoutGap and autoLayoutPadding are numbers of 0 or more. autoLayoutAlign runs from start-start to end-end.
  • locked is true or false. A locked item returns 409 on any change except unlocking it. Send locked: false to unlock. It can be combined with other changes and is applied first. Send locked: true to lock, and it is applied last, after the other changes in the request.

Changes to frameId, groupId, and layer update updatedAt like any other edit, so the item's ETag changes. Use GET /canvases/:id/frames/:frameId to read what a frame holds. It returns the frame's bounds and the item IDs inside it, up to itemLimit. overflowReason says why a long list was cut: frame_too_large or search_too_dense.

Connectors

A connector joins two items on the same canvas. Create one with sourceItemId and targetItemId. Both must be items on the canvas in the path, or the request returns 404. They must differ, and neither can be a drawing. Either returns 400. Creating a connector accepts an idempotencyKey, and the response carries an ETag.

The style fields are style, color, route, strokePattern, startCap, endCap, startEdge, and endEdge. Setting endCap to none makes the style line. Update moves an end with sourceItemId or targetItemId. Send expectedUpdatedAt or an If-Match header to get 412 instead of overwriting a newer change. Connectors need canvas:write. A read-only key or a viewer gets 403.

GET /canvases/:id/linked lists the task and post cards on a canvas with their current details. A card shows null where you cannot open the task or post.

Image preview
100%