Create, move, resize or delete many items in one draw
POST /boards/{boardId}/items:batch
Up to 100 operations, validated together before anything is drawn, then drawn as one action. Updates in a batch change position and size; replacing an item's data is PATCH /items/{itemId}. The Job's result.itemIds lists the created items, updated and deleted the others.
Authorization
AuthorizationstringheaderrequiredBearer <key>. The key needs boards:write scope. Create and manage keys in the developer console, or use an OAuth app to act for other people; what each scope unlocks is on the scopes page.
Path parameters
boardIdstringpathrequiredHeaders
Idempotency-KeystringheaderA unique key per logical request. Replays within 24 hours return the original response.
Body
callbackUrlstringOptional. When the job this request starts finishes or fails, a short body is POSTed here once: { eventId, status, boardId, boardUrl, imageUrl }, where status is succeeded or failed and imageUrl is a picture of what the job drew, or null. Signed with the workspace's callback secret (GET /webhooks/callback-secret). https to a public host. The full job is on GET /jobs/{jobId}.
operationsobject | object | object[]requiredResponse
idstringkindenum<string>One of item.create, item.update, item.delete, item.batch, item.record, ai.generate, ai.modify, skill.apply or board.export.
statusenum<string>One of queued, running, succeeded or failed.
progressintegermessagestringHuman readable progress, for example "Placing kanban".
resultobject | nullChild attributes
itemIdsstring[]updatedstring[]deletedstring[]creditsUsedintegerboardTitlestring | nullskillstring | nullconvertedFromstringsourceDeletedbooleantargetenum<string>board.export. What was drawn. One of board, frame or item.
formatenum<string>board.export. One of png or mp4.
scaleenum<integer>board.export. One of 1 or 2.
imageUrlstringboard.export. The PNG. Anyone with this URL can open it.
widthintegerboard.export. The image's width in pixels.
heightintegerboard.export. The image's height in pixels.
videoUrlstringboard.export with format mp4. The MP4. Anyone with this URL can open it.
fpsintegerboard.export with format mp4.
durationnumberboard.export with format mp4. Seconds.
bytesintegerboard.export with format mp4. The file's size.
errorerrorChild attributes
codeenum<string>requiredOne of unauthorized, forbidden, not_found, validation_failed, conflict, plan_limit, rate_limited or internal.
messagestringrequireddetailsobject[]docsUrlstringupgradeUrlstringcreatedAtstringfinishedAtstring | nullcallbackUrlstring | nullWhere the job's result is POSTed
callbackobject | nullThe newest delivery to callbackUrl, once the job has finished. Null until then, and when there is no callbackUrl.
Child attributes
urlstringdeliveryIdstringstatusenum<string>One of pending, retrying, succeeded, failed or cancelled.
attemptsintegerresponseStatusinteger | nullerrorstring | nulldeliveredAtstring | nullnextRetryAtstring | nullErrors
validation_failedThe body did not match the schema for this item type.
rate_limitedToo many requests.