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
Scope
canvas:read
Query parameters
projectIdstring
Filter by project ID
includeArchivedboolean
Include archived canvases when true. A request with updatedSince always includes them.
updatedSincenumber|string
Only canvases changed after this time, as Unix milliseconds or an ISO 8601 time with a timezone. The time is exclusive, and results come back oldest change first. To poll, send the largest updatedAt you have seen minus 5 seconds and skip canvases whose id and updatedAt you already have.
includeDeletedboolean
Include deleted canvases. Each carries deletedAt, which is null for a live one. A deleted canvas is reported for 30 days. The response also has removed: the canvases that were made private or moved out of reach of the caller, and the canvases that moved out of the project you asked for, as id, updatedAt, and deletedAt.
limitnumber
Number of canvases (max 100, default 50)
cursorstring
nextCursor from the previous page
fieldsstring
Comma-separated fields to return. id is always included. See Choosing fields in Conventions.
{"items":[{"id":"itm_abc123","type":"note","x":120,"y":80,"width":240,"height":160,"zIndex":null,"layerOrderKey":"a1","taskId":null,"postId":null,"frameId":null,"frameKind":null,"groupId":null,"autoLayout":null,"autoLayoutGap":null,"autoLayoutPadding":null,"autoLayoutAlign":null,"content":"Check the launch copy","richContent":null,"color":null,"backgroundColor":null,"backgroundFill":null,"backgroundBorder":null,"backgroundRadius":null,"textAlign":null,"shapeKind":null,"drawKind":null,"drawPoints":null,"drawRoute":null,"strokeWidth":null,"strokeStyle":null,"fillStyle":null,"opacity":null,"rotation":null,"url":null,"urlLabel":null,"frameTitle":null,"borderStyle":null,"locked":false,"createdAt":1779680000000,"updatedAt":1779680000000}],"hasMore":false,"nextCursor":null}
Scope
canvas:write
Path parameters
idstringrequired
Canvas ID (URL path)
Body parameters
namestring
New name
descriptionstring
New description
visibilitystring
private or shared
expectedUpdatedAtnumber
The updatedAt you last read for this canvas. If the canvas has changed since, the request returns 412 and nothing is written. An If-Match header with the canvas ETag does the same.
{"id":"itm_abc123","type":"note","x":120,"y":80,"width":240,"height":160,"zIndex":null,"layerOrderKey":"a1","taskId":null,"postId":null,"frameId":null,"frameKind":null,"groupId":null,"autoLayout":null,"autoLayoutGap":null,"autoLayoutPadding":null,"autoLayoutAlign":null,"content":"Check the launch copy","richContent":null,"color":null,"backgroundColor":null,"backgroundFill":null,"backgroundBorder":null,"backgroundRadius":null,"textAlign":null,"shapeKind":null,"drawKind":null,"drawPoints":null,"drawRoute":null,"strokeWidth":null,"strokeStyle":null,"fillStyle":null,"opacity":null,"rotation":null,"url":null,"urlLabel":null,"frameTitle":null,"borderStyle":null,"locked":false,"createdAt":1779680000000,"updatedAt":1779680000000}
Scope
canvas:write
Path parameters
idstringrequired
Canvas ID (URL path)
itemIdstringrequired
Item ID on that canvas (URL path)
Body parameters
xnumber
New left edge
ynumber
New top edge
widthnumber
New width, greater than 0
heightnumber
New height, greater than 0
contentstring
New plain text
richContentarray
New Plate JSON blocks for a text item
colorstring
Item color
backgroundColorstring
Background color. none clears it.
backgroundFillstring
none, subtle, or solid
backgroundBorderboolean
Show a border around the background
backgroundRadiusstring
sharp, rounded, or pill
textAlignstring
left, center, or right
shapeKindstring
rectangle, roundedRectangle, ellipse, diamond, triangle, or line
strokeWidthstring
thin, medium, or thick
strokeStylestring
sketch, solid, dashed, or dotted
fillStylestring
none, subtle, or solid
opacitynumber
0 to 100
rotationnumber
Rotation in radians, for shapes
drawPointsnumber[]
Flat list of x, y pairs scaled from 0 to 1, 4 to 4,096 numbers
drawRoutestring
straight, curved, or elbow
urlLabelstring
Display label for a url item
frameTitlestring
Frame title
borderStylestring
dashed or solid, for frames
urlstring
New link. An empty string clears it.
frameIdstring|null
Frame on the same canvas to place the item in. null takes it out of its frame.
groupIdstring|null
Group ID, up to 128 characters. null removes the item from its group.
lockedboolean
true locks the item and false unlocks it. A locked item can only be unlocked.
layerstring
front, back, forward, or backward. Moves the item in the stacking order.
autoLayoutstring|null
horizontal, vertical, or grid, for frames only. null turns auto layout off.
autoLayoutGapnumber
Space between children, 0 or more
autoLayoutPaddingnumber
Space inside the frame edge, 0 or more
autoLayoutAlignstring
Alignment of children, from start-start to end-end
expectedUpdatedAtnumber
The updatedAt you last read for this item. If the item has changed since, the request returns 412 and nothing is written. An If-Match header with the item's ETag does the same.
{"id":"itm_abc123","type":"note","x":120,"y":80,"width":240,"height":160,"zIndex":null,"layerOrderKey":"a1","taskId":null,"postId":null,"frameId":null,"frameKind":null,"groupId":null,"autoLayout":null,"autoLayoutGap":null,"autoLayoutPadding":null,"autoLayoutAlign":null,"content":"Check the launch copy","richContent":null,"color":null,"backgroundColor":null,"backgroundFill":null,"backgroundBorder":null,"backgroundRadius":null,"textAlign":null,"shapeKind":null,"drawKind":null,"drawPoints":null,"drawRoute":null,"strokeWidth":null,"strokeStyle":null,"fillStyle":null,"opacity":null,"rotation":null,"url":null,"urlLabel":null,"frameTitle":null,"borderStyle":null,"locked":false,"createdAt":1779680000000,"updatedAt":1779680000000}
The updatedAt you last read for this connector. If it has changed since, the request returns 412 and nothing is written. An If-Match header with the connector's ETag does the same.
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.