Customization SDK

Use the FlashBoards SDK for behavior you want to reuse: a selected-note cleanup action, a selection layout, or a small reporting tool. A tool can run without showing a panel; an optional panel calls the same authored actions. For a single board edit, use an existing board action.

Start with an agentCopy Anchor Link

Connect over MCP or the Public API. Ask the agent to read get_skill with skillId: "flashboards-sdk", then discover the connected version's contracts. The SDK guide is also available as a public Markdown file. Live schemas and receipts govern which capabilities that version accepts. For SDK 2, discover tool-artifact, tool-context and tool-installations as shown below. The live contracts describe authored actions, bounded context and independent installed tools.

Where Settings → Plugins is available, Build with Assistant opens a customization request in the sidebar; Copy instructions for my agent supplies connection instructions; Read SDK guide opens the same guide. These controls do not install a package.

Discover before writingCopy Anchor Link

The public guide and describe_board_action envelope schema can be read without SDK pilot access. Live extension schemas and installed-tool discovery through extensionsRequest require an eligible pilot account and local-board tab, even for read-only requests; they do not require installation consent.

With that access, first call list_board_sessions and get_board_snapshot for the intended tab. Then send extensionsRequest through execute_board_action, with the snapshot's activeBoardId as the outer expectedBoardId and sessionId when needed:

{
  "operation": "execute_board_action",
  "input": {
    "action": "extensionsRequest",
    "args": { "operation": "describe", "section": "tool-artifact" },
    "expectedBoardId": "BOARD_ID_FROM_SNAPSHOT",
    "sessionId": "SESSION_ID_FROM_DISCOVERY"
  }
}

This is the Public API envelope. For MCP, send its input object as the arguments to execute_board_action. Replace the placeholder IDs with returned values. Request section: "tool-context" separately to inspect the bounded context schema, then section: "tool-installations" for version-4 installation requests.

Execution, including invocation without a visible panel, uses the authorized local-board tab. It does not run on the server against an arbitrary board. WebMCP's browser tools do not expose plugin execution.

Choose the package contractCopy Anchor Link

An SDK 2 action reads bounded context, requests item pages, then returns a result or one declared effect. Its program is stored as function-body strings in JSON. It cannot access arbitrary page DOM, network requests, files, shell commands or paid generation.

SDK 2 grants are explicit:

• Item reads. board.items.read returns up to 32 summaries per page, including IDs, kinds and available geometry. It excludes note bodies and media URLs. Continue with the returned offset and revision.
• Select and focus. These effects require matching capabilities and IDs from the captured selection or latest item page.
• Note editing. notes.read exposes one supported selected note. notes.write also needs that read grant and can update only that captured note's title, content, font size, text color and background color. The body limit is 2 KiB UTF-8 and the title limit is 256 bytes.
• Selection layout. board.layout also requires selection.geometry. One position-only layout must cover exactly the captured selection of 1–32 items. Paged or remembered IDs cannot expand that authority. Missing, extra, duplicate or stale targets refuse the whole effect. Bound arrows can follow moved targets; changedIds reports the directly positioned items.

The invocation has a two-second deadline and at most eight reads; eight reads are a ceiling, not a guaranteed throughput. Arguments and results are at most 2 KiB, state and each step at most 16 KiB. Agent installation accepts at most 8 KiB of serialized package JSON. Discover the exact schemas before authoring.

Install and invoke deliberatelyCopy Anchor Link

Before an agent installs, replaces or invokes a plugin, a human must enable Allow my connected agents to install panels, save toolbar drafts and run local plugins here under Settings → Plugins → Official Alignment. The agent must wait for that Settings action. A shared file or connected app does not supply consent.

Up to eight independent SDK 2 tools can be installed. Discover tool-installations, then use operation: "panel" with request.version: 4. Keep the installation ID and entry revision. Obtain fresh context with get before invokeAction, using the same ID, revision and token. Updates, enable/disable and removal require the entry revision. See the SDK guide and live schema for complete requests.

Metadata reads do not require agent consent; writes, context and execution do. Installation does not invoke an action. Hiding a panel leaves its tool installed. Obtain fresh context after board, selection or installation changes.

Version-2 SDK 1 panels and version-3 SDK 2 requests share the separate legacy single slot, alongside the alignment toolbar. Inspect its occupant before intentional replacement; these requests do not target version-4 installations.

Read the full receipt. Applied edits use normal Undo; pending persistence does not confirm durable saving. Version-4 committed: "runtime" acknowledges transient state; "registry" acknowledges an installation-registry write. Legacy receipts may use stateCommitted: true. Inspect withheld or uncertain results; never automatically replay them.

Share a definitionCopy Anchor Link

Exported packages transfer their JSON definition, code and optional CSS. They do not transfer private runtime state, live context tokens, account authority or consent. Check the editor text before export: export downloads the current editor text, including unsaved changes. Import the actual file when transferring a definition, then discover fresh context on the receiving board. Switching local boards alone does not normally require reimporting an installed tool.

An unsupported package or declared capability is refused and asks you to save your work and refresh. Refresh does not automatically replay an invocation.

RelatedCopy Anchor Link