Public API

Customize reusable local-board behavior

Read the shared flashboards-sdk guide at /skills/flashboards-sdk/SKILL.md. Use execute_board_action with action: "extensionsRequest", args equal to the discovered ExtensionOperation, and the current outer expectedBoardId. Format-2 panels are optional views; format-1 toolbars use a separate flow.

• Use live describe sections for schemas and availability. This requires an eligible open local-board browser owner and human Settings consent for writes. Inspect the full result and board after mutations; never automatically replay unknown or applied/pending outcomes.

Edit several text notes on one board

Call execute_board_action with action: "updateTextNotes" after reading the current active local board with "queryBoardItems". Supply that read's boardId and revision as expectedRevision, plus 1–100 unique explicit {id,changes} entries. Each changes object uses the same fields as updateTextNote; null clears optional title and style overrides.

• The full batch request is limited to 64 KiB UTF-8 JSON. Every target and patch is checked before one Undo step is made. The receipt returns exact changedItemIds and unchangedItemIds, beforeRevision, revision, and save:pending for changed content; pending does not confirm durable storage. An all-no-op batch returns save:unchanged. A refusal changes nothing and should be followed by a fresh query before retrying.

Search reference images by prompt

search_references searches the private reference catalog without an open board or browser session. API/MCP reference search and previews are available to all active authenticated accounts. The editor UI and its browser routes remain admin/tester-only. Results contain ranked display metadata and short-lived opaque handles, not source URLs or originals.

{"operation":"search_references","input":{"query":"brutalist concrete museum at dusk","limit":12}}

• Request envelope: query 1–1,024 characters and limit 1–100, default 20. The current catalog's advertised query/result ceilings can be lower and are enforced. A returned nextCursor may be sent back with the same query; no other pagination behavior is promised.
• Search and preview allowances are aggregate per account across Website, API and MCP. A transport switch does not create another catalog quota.

Search references using image bytes

search_references_by_image accepts the same prepared-image base64 format used by the Website. It does not accept paths or remote URLs.

{"operation":"search_references_by_image","input":{"imageBase64":"iVBORw0KGgo...","limit":12,"colorMatch":false}}

• JPEG, PNG or WebP only; canonical base64; at most 327,680 decoded bytes, 16,384 pixels per edge and 40 megapixels. MIME signature and dimensions are validated before search.
• Request envelope: limit 1–50, default 20. The current catalog's advertised byte/result ceilings can be lower and are enforced. colorMatch works only when that catalog advertises the capability. Continue image results only by resending the same bytes and returned cursor.

Download one reference preview

Pass a selected result's previewHandle to get_reference_preview. The API result adds authenticated base64 bytes to the preview metadata; decode result.base64 using result.mimeType. MCP returns the same metadata plus a native image content block. When HTTPS delivery is configured, metadata also includes a signed previewUrl and previewUrlExpiresAt (Unix milliseconds).

{"operation":"get_reference_preview","input":{"previewHandle":"OPAQUE_HANDLE_FROM_SEARCH"}}

• API previews are fetched on demand as JPEG, PNG or WebP. MCP also supports explicitly advertised alternate AVIF previews; the API answers alternatePreviewAvifHandle with REFERENCE_UNSUPPORTED. Search never eagerly downloads every result.
• Handles are short-lived and bound to the exact verified browser session, API key, or OAuth client consent that created them. A stale, altered, revoked or differently bound handle must be replaced by a fresh search.
• The preview URL is a separate 24-hour bearer sharing grant: anyone with it can read that preview without cookies, even after the source handle expires or the issuing connection is revoked. It cannot renew itself or grant originals. Delivery still requires the current catalog and shares the issuer's per-account preview quota.
• Embed previewUrl only where the chat supports image URLs; a link cannot force inline rendering. Native bytes remain available if the optional URL is omitted (previewUrlOmittedReason: unavailable). Never treat these links as permanent storage or publish private source URLs.
• Safe failures use REFERENCE_ACCESS_DENIED, REFERENCE_RATE_LIMITED, REFERENCE_STALE, REFERENCE_UNSUPPORTED or REFERENCE_UNAVAILABLE; private URLs and upstream error details are not returned.

Export a board image

Use export_board_image with a live updated FlashBoards tab. First read get_board_snapshot, then pass expectedBoardId and sessionId. scope defaults to selection; pass itemIds for an explicit selection or scope: board for all items. The board is not modified.

{"operation":"export_board_image","input":{"expectedBoardId":"BOARD_ID","sessionId":"SESSION_ID","itemIds":["IMAGE_ID","TEXT_ID","ARROW_ID"],"scale":2,"background":"#ffffff","region":{"x":0,"y":0,"width":1200,"height":800}}}

• scale: 0.1–4 pixels per board unit; padding: 0–1024 board units; background: transparent or #RRGGBB.
• region: {x, y, width, height} uses board coordinates. Use the same region, scale and background for Figma comparison.
• Supports static PNG/JPEG/WebP images, text, drawings and arrows. Missing assets, unavailable custom fonts and unsupported media fail explicitly.
• Limits: 256 items, 8192 pixels per edge, 16 megapixels, 8 MiB PNG. The REST result contains bounds, itemIds, scale, pixel dimensions, mimeType and base64. Decode result.base64 to save a PNG. MCP returns the same metadata plus a native image content block.

Use a local reference image

generate_image can accept one explicitly approved local image in referenceImages. This is part of the same generation call: it does not require a board, an open tab, or a separate upload operation.

{
  "operation": "generate_image",
  "input": {
    "prompt": "Describe the requested edit",
    "model": "nano-banana-2",
    "resolution": "1k",
    "generationAttemptId": "attempt-local-reference-1",
    "referenceImages": [
      {
        "filename": "reference.png",
        "dataUrl": "data:image/png;base64,..."
      }
    ]
  }
}

• The attachment must be a supported image MIME type encoded as a bounded base64 data URL. Send the image bytes only after the user has approved that attachment; do not send a local filesystem path.
• MCP host note: on ChatGPT MCP hosts that support file inputs, pass the host-provided imageFile to generate_image, or imageFile/videoFile/referenceVideos to compatible Seedance generate_video models. When forwarding is unavailable in an MCP App host, the MCP-only show_media_upload_picker lets the user select and explicitly upload a bounded file; use its opaque receipt in referenceVideoReceipts or referenceImageReceipts for generate_video, or pass one image receipt in referenceImageReceipts to a compatible generate_image model. describe_media accepts one host file instead of mediaDataUrl. These direct paths need no open board; validate_chat_media checks a file without uploading or starting a paid action.
• FlashBoards stores the input temporarily and passes its short-lived signed URL into the generation. The upload handle is not a separate public resource and is not returned in the generation result.
• imageUrls remains supported. For generate_video, Seedance accepts one referenceImages attachment or one referencePreviewHandle, alongside model-supported imageUrls. The caller must be able to provide the actual image bytes; a local path alone is insufficient. MiniMax H3 Max Reference to Video takes your own image results as referenceGenerationIds and catalog previews as referencePreviewHandles (read on the server; signed result links do not work in referenceImageUrls), and estimate_generation_cost prices them the same way. H3 Max takes one of your image results as firstFrameUrl. Other MiniMax attached images use the board path: add_media_to_board(dataUrl or referencePreviewHandle), then prepare_board_generation with the returned itemId and discovered model slot, then generate_on_board after normal consent.
• For multi-reference edit models (GPT Image 2.5, Seedream, Grok Imagine Image 2), generate_image takes your own completed images as referenceGenerationIds and search previews as referencePreviewHandles; the server reads them, so signed links are not needed. Other models: add the preview to a board and use the model's native board slot. add_media_to_board accepts an encoded MP4 data URL up to 10 MiB; the client must have its bytes. Preview handles grant the preview rendition only, never the catalog original.

Recover a generation after losing its ID

Call list_recoverable_generations to find your recent recoverable generations and receive a fresh generationId for each. Then call get_generation with that ID for one status/result check.

• The list covers the last 48 hours and never starts, refreshes, or charges a generation.
• Only generations supported by the current Public API model catalog are returned. The response never exposes provider task IDs or internal database IDs.

Working with a board

The board operations act on a FlashBoards tab that is open and signed in. With no live tab they return an error saying so; list_board_sessions reports an empty list.