Export as an image

POST /boards/{boardId}/export

Updated 9 Nov 20264 min read

POST/boards/{boardId}/exportTry it

Basehttps://api.mockflow.com/v1Scopesboards:read

Request

curl https://api.mockflow.com/v1/boards/brd_3f9e2a/export \
  -X POST \
  -H "Authorization: Bearer $MOCKFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "item",
  "itemId": "itm_p4"
}'

const response = await fetch("https://api.mockflow.com/v1/boards/brd_3f9e2a/export", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MOCKFLOW_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "target": "item",
  "itemId": "itm_p4"
})
});

const data = await response.json();

import os, requests

response = requests.post(
    "https://api.mockflow.com/v1/boards/brd_3f9e2a/export",
    headers={"Authorization": f"Bearer {os.environ['MOCKFLOW_API_KEY']}"},
    json={
  "target": "item",
  "itemId": "itm_p4"
},
)

response.raise_for_status()
data = response.json()

Response

{
  "id": "job_7hd2",
  "kind": "item.create",
  "status": "queued",
  "progress": 0,
  "message": "Interview 5 users",
  "result": {
    "itemIds": [
      "string"
    ],
    "updated": [
      "string"
    ],
    "deleted": [
      "string"
    ],
    "creditsUsed": 0,
    "boardTitle": "Q4 Launch Planning",
    "skill": "string"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "docsUrl": "https://mockflow.com/developers/concepts/errors#rate_limited"
  },
  "requestId": "req_45d49816999bac40"
}

With format: mp4, a video_maker item is rendered on the server as an H.264 MP4 (up to 10 minutes, up to 3840 x 2160) and the finished job's result carries videoUrl, width, height, fps, duration and bytes. Server video renders are on paid plans.

A PNG of the whole board, one frame with everything inside it, or one item on its own, drawn by the same renderer as the editor's Export. Drawing takes a browser, so this answers 202 with a Job; poll it, and the finished job's result carries imageUrl, width and height.

board is every item except comment pins, cropped to what they cover.
frame is a frame (a section, design frame, diagram frame, mood board and the like) and the items fully inside it. A design frame is cropped to its canvas, under its title bar.
item is one item alone, with nothing behind it.

The background is transparent. The image is published at an unguessable address: anyone with the URL can open it, so treat the URL like the board content it shows. Very large areas are refused before rendering: 20,000 x 20,000 pixels at scale 1, 10,000 x 10,000 at scale 2.

Authorization

Authorizationstringheaderrequired

Bearer <key>. The key needs boards:read 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

boardIdstringpathrequired

Headers

Idempotency-Keystringheader

A unique key per logical request. Replays within 24 hours return the original response.

Body

application/json

callbackUrlstring

Optional. 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}.

targetenum<string>

What to draw. One of board, frame or item. Defaults to board.

itemIdstring

The frame or item to draw. Required unless target is board.

scaleenum<integer>

2 doubles the pixels, for retina screens and print. One of 1 or 2. Defaults to 1.

formatenum<string>

mp4 renders a video_maker item as a video. Needs target item; not on the Basic plan. One of png or mp4. Defaults to png.

qualityenum<integer>

mp4 only. The video's short side in pixels, fitted inside 3840 x 2160. One of 480, 720, 1080, 1440 or 2160. Defaults to 1080.

fpsenum<integer>

mp4 only. Frames per second. Defaults to the video's own setting, else 30. One of 24, 25, 30 or 60.

Response

202 · application/json

idstring

kindenum<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.

progressinteger

messagestring

Human readable progress, for example "Placing kanban".

resultobject | null

Child attributes

itemIdsstring[]

updatedstring[]

deletedstring[]

creditsUsedinteger

boardTitlestring | null

skillstring | null

convertedFromstring

sourceDeletedboolean

targetenum<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.

imageUrlstring

board.export. The PNG. Anyone with this URL can open it.

widthinteger

board.export. The image's width in pixels.

heightinteger

board.export. The image's height in pixels.

videoUrlstring

board.export with format mp4. The MP4. Anyone with this URL can open it.

fpsinteger

board.export with format mp4.

durationnumber

board.export with format mp4. Seconds.

bytesinteger

board.export with format mp4. The file's size.

errorerror

Child attributes

codeenum<string>required

One of unauthorized, forbidden, not_found, validation_failed, conflict, plan_limit, rate_limited or internal.

messagestringrequired

detailsobject[]

docsUrlstring

upgradeUrlstring

createdAtstring

finishedAtstring | null

callbackUrlstring | null

Where the job's result is POSTed

callbackobject | null

The newest delivery to callbackUrl, once the job has finished. Null until then, and when there is no callbackUrl.

Child attributes

urlstring

deliveryIdstring

statusenum<string>

One of pending, retrying, succeeded, failed or cancelled.

attemptsinteger

responseStatusinteger | null

errorstring | null

deliveredAtstring | null

nextRetryAtstring | null

Errors

429rate_limited

Too many requests.

Was this page helpful?