Air

Start a discussion on an asset version. body is plain text, at most 500 characters, counted in Unicode code points. Most emoji count as one. Whitespace-only text is rejected. Mention someone with {{mention:N}} and a mentions entry at that index. At most 10 mentions. Each accountId is an active member. On create, mentions null is the same as omitting it. assetVersionId is required. There is no default version and no board. On a document or PDF, every annotation needs pageNumber. In a workspace that scopes comments to boards, a board guest gets 403 even when they can comment in their board. A timeout can create a duplicate: list before retrying. Creating a discussion spends action credits. A 403 whose body has extra.reason missing_scope means this connection needs comments.write. Reconnect Air; a grant saved before that scope was advertised does not widen on its own. Other 403s are unchanged. Returns the discussion. Box coordinates are the top-left, and the box must fit in the frame. A pencil has 1 to 10 lines of 2 to 1000 points. lineWidth is greater than 0 and at most 1000. Write color is #RRGGBB.

create_discussion

Add a comment to a discussion. body is plain text, at most 500 characters, counted in Unicode code points. Most emoji count as one. Whitespace-only text is rejected. Mention someone with {{mention:N}} and a mentions entry at that index. At most 10 mentions. Each accountId is an active member. On create, mentions null is the same as omitting it. Adding a comment spends action credits. A 403 whose body has extra.reason missing_scope means this connection needs comments.write. Reconnect Air; a grant saved before that scope was advertised does not widen on its own. Other 403s are unchanged. Returns the comment.

create_discussion_comment

Create a library. Title must be unique in the workspace. `accessibility` is who can join and defaults to `public`. `visibility` is who can see the library and defaults to `workspaceMembers`. The response includes a `url` field with the canonical Air webapp link.

create_library

Create a showcase and its share link in one step. The result includes the link. Create does not take items. After creating, add assets with add_assets_to_showcase and boards with add_boards_to_showcase. Sub-pages are not exposed. A showcase with sub-pages comes back with only its top-level items. allowDownload controls single-file download only; download-all is not exposed. Settings left out follow the workspace Share Link Defaults, so the returned link can include settings this request did not send. If the link cannot be created, the showcase is not created either. password is write only. null clears it. An empty password is rejected. Use the user's timezone when it is known, with a Z or an offset. For 11:59pm on December 31 in UTC-6, send `2026-12-31T23:59:00-06:00`. When the timezone is unknown, send a UTC instant with Z, such as `2026-12-31T23:59:00.000Z`. A value with no Z or offset is read in the server's timezone, not the person's, so an unqualified time can land hours early. null clears expiresAt. A past or unparseable expiresAt is a 400 and nothing in the request is saved. requireAccount requires the recipient to sign in. comments: allowed lets anyone with the link post comments. customFields: editable lets anyone with the link change custom field values. Turning password, expiresAt, requireAccount, comments, or customFields on needs the workspace shareLinks add-on. Raising comments from read_only to allowed, or customFields from read_only to editable, counts as turning it on. Otherwise the API returns 422 ADDON_DISABLED and applies nothing. This workspace's plan does not include that setting. Nothing in the request was saved. Ask the person whether to go ahead without those settings. Re-sending a value the link already has, changing an existing password or expiration, and turning a setting off are accepted. `url` is the public share link to give to people. It is not an Air webapp link and not a CDN link. A link is usable when `active` is true and `expiresAt` is null or in the future; an expired link can still be `active: true`. Disabled links are included (`active: false`). The password is never returned. `hasPassword` says whether one is set, and `requireAccount` says whether the recipient must sign in. Tell the recipient when a password or an Air account is required.

create_showcase

Create a new tag in the workspace

create_tag

Delete a comment. Only the author can delete. Deleting the last comment deletes the discussion. The response is empty. This spends action credits. A 403 whose body has extra.reason missing_scope means this connection needs comments.write. Reconnect Air; a grant saved before that scope was advertised does not widen on its own. Other 403s are unchanged.

delete_discussion_comment

Get detailed information about a specific asset including its cover version, custom fields, and metadata. The response includes a `url` field with the canonical Air webapp link — always use this instead of constructing URLs manually. If listing the asset's boards is forbidden, `url` is the All-assets link.

get_asset

Get a temporary download URL for a specific asset version. If versionId is not provided, uses the cover version.

get_asset_download_url

Get an inline image preview of an asset. Returns the image as base64-encoded image content that MCP clients can render directly.

get_asset_image

Get one version of an asset, including its file details, tags, smart tags, preview URLs, and metadata. The response includes a `url` field with the canonical Air webapp link for that version — always use this instead of constructing URLs manually. If listing the asset's boards is forbidden, `url` is the All-assets link for that version.

get_asset_version

Get detailed information about a specific board. The response includes a `url` field with the canonical Air webapp link.

get_board

Get detailed information about a specific custom field, including its type and possible values

get_custom_field

Get one discussion, including its first 10 comments. A discussion includes only its first 10 comments. Call list_discussion_comments for the rest, oldest first. discussion.comments.pagination.cursor is accepted as cursor. A missing boardId means the stored board is hidden or inactive, not that the thread has no board. author.id on a workspace_account author, and mentions[].id, are account ids. They match list_members id and the accountId sent on a write mention. Discussion reads do not spend action credits. A 403 whose body has extra.reason missing_scope means this connection needs comments.read. Reconnect Air; a grant saved before that scope was advertised does not widen on its own. Other 403s are unchanged. A discussion you cannot view is 404. Annotation color on a read is whatever was stored.

get_discussion

Check the status of an import task. Status will be one of: pending, inProgress, succeeded, failed. If failed, an error object with type and message is included.

get_import_status

Get a library by id, including its title, description, accessibility, and visibility. The response includes a `url` field with the canonical Air webapp link.

get_library

Get a showcase and its share link. shareLink is null when the showcase has none. list_showcases omits those. Sub-pages are not exposed. A showcase with sub-pages comes back with only its top-level items. `url` is the public share link to give to people. It is not an Air webapp link and not a CDN link. A link is usable when `active` is true and `expiresAt` is null or in the future; an expired link can still be `active: true`. Disabled links are included (`active: false`). The password is never returned. `hasPassword` says whether one is set, and `requireAccount` says whether the recipient must sign in. Tell the recipient when a password or an Air account is required. An unknown, trashed, or other-workspace id is 404. A showcase the caller cannot view is 403.

get_showcase

Import an asset into Air from a source URL. Air fetches the URL itself, so it must point directly at the file and be reachable from the internet; a share page such as a Google Drive or Dropbox link returns a web page, not the file. Returns an import task ID, asset ID, version ID, and a canonical `url` for the asset in the Air webapp. Use get_import_status to poll for completion. Always use the returned `url` field — never construct Air URLs manually. This connection cannot read files on the user's computer, so create_import is the only way to add new assets here. Local files are uploaded in the Air web app.

create_import

List CDN links for an asset. Each link includes its public url, whether it follows the asset's current default version, and whether it is active. The response is `{ data }` for the newest 100 links. Use create_cdn_link to add one and update_cdn_link to turn one on or off.

list_cdn_links

List public share links for an asset. `url` is the public share link to give to people. It is not an Air webapp link and not a CDN link. A link is usable when `active` is true and `expiresAt` is null or in the future; an expired link can still be `active: true`. Disabled links are included (`active: false`). The password is never returned. `hasPassword` says whether one is set, and `requireAccount` says whether the recipient must sign in. Tell the recipient when a password or an Air account is required. An asset can have several links: one that follows the current version (`followsDefaultVersion: true`) and one per pinned version (`followsDefaultVersion: false` with `versionId`). A pinned link follows the file, not the version number. The response is `{ data, pagination, total }`. The API defaults limit to 12 and caps it at 200. Use create_asset_share_link to add one and update_asset_share_link to change it.

list_asset_share_links

List every version of an asset. The response is `{ data, total }` for the full version stack. IMPORTANT: Never construct Air webapp URLs from version IDs. To get a link to a specific version, use the get_asset_version tool which returns a canonical `url` field.

list_asset_versions

List assets in the workspace, optionally filtered by board, showcase, tags, custom fields, or search query. customField filters select options, plain text (text, textPrefix, textNot), and dates (dateGte, dateLte). Set semantic=true with a search query to rank results by natural-language meaning instead of keyword matching. showcaseId lists assets added to a showcase. It cannot be combined with parentBoardId or semantic search. With includeNestedAssets it also returns assets inside the boards added to that showcase. Sub-pages are not exposed. A showcase with sub-pages comes back with only its top-level items. IMPORTANT: Never construct Air webapp URLs from asset IDs. To get a link to an asset, use the get_asset tool which returns a canonical `url` field.

list_assets

List the public share link for a board. A board has zero or one link, so `data` is empty or holds that single link. `url` is the public share link to give to people. It is not an Air webapp link and not a CDN link. A link is usable when `active` is true and `expiresAt` is null or in the future; an expired link can still be `active: true`. Disabled links are included (`active: false`). The password is never returned. `hasPassword` says whether one is set, and `requireAccount` says whether the recipient must sign in. Tell the recipient when a password or an Air account is required. A parent board can pass a password down, so `hasPassword` can be true on a link created without one. The response is `{ data, pagination, total }`. Use create_board_share_link to add one and update_board_share_link to change it.

list_board_share_links

List boards in the workspace, optionally filtered by name, parent board, library, or showcase. `libraryId` and `inGeneralLibrary` cannot be used together. showcaseId lists boards added to a showcase. It cannot be combined with parentBoardId, libraryId, or inGeneralLibrary set to true. Sub-pages are not exposed. A showcase with sub-pages comes back with only its top-level items. IMPORTANT: Never construct Air webapp URLs from board IDs. To get a link to a board, use the get_board tool which returns a canonical `url` field.

list_boards

List all boards that contain a specific asset

get_asset_boards

List custom fields defined in the workspace

list_custom_fields

List every comment on a discussion, oldest first. A discussion includes only its first 10 comments. Call list_discussion_comments for the rest, oldest first. discussion.comments.pagination.cursor is accepted as cursor. author.id on a workspace_account author, and mentions[].id, are account ids. They match list_members id and the accountId sent on a write mention. Discussion reads do not spend action credits. A 403 whose body has extra.reason missing_scope means this connection needs comments.read. Reconnect Air; a grant saved before that scope was advertised does not widen on its own. Other 403s are unchanged. The response is `{ data, pagination, total }`. A discussion you cannot view is 404.

list_discussion_comments

List discussions on an asset, or on the assets placed directly on a board. Pass assetId or boardId, not both. assetVersionId is only valid with assetId. boardId covers only assets placed directly on that board, not assets in its sub-boards. To cover a board and its sub-boards, list them with list_boards parentBoardId and call this for each board. Pages do not overlap. The cursor is the first discussion of the next page. The default lastCommentedAt sort can repeat or skip a discussion if a reply lands between pages. For a stable walk, pass sortBy createdAt and sortDirection asc. A discussion includes only its first 10 comments. Call list_discussion_comments for the rest, oldest first. discussion.comments.pagination.cursor is accepted as cursor. A missing boardId means the stored board is hidden or inactive, not that the thread has no board. author.id on a workspace_account author, and mentions[].id, are account ids. They match list_members id and the accountId sent on a write mention. Discussion reads do not spend action credits. A 403 whose body has extra.reason missing_scope means this connection needs comments.read. Reconnect Air; a grant saved before that scope was advertised does not widen on its own. Other 403s are unchanged. The response is `{ data, pagination, total }`.

list_discussions

List libraries in the workspace. `search` is a text search over library title and description.

list_libraries

List all assets within a board and all of its nested sub-boards. IMPORTANT: Never construct Air webapp URLs from asset IDs. To get a link to an asset, use the get_asset tool which returns a canonical `url` field.

list_nested_assets

List the showcases the caller can see, not every showcase in the workspace. An editor sees their own. A role that can view every showcase sees all of them. Showcases without a share link are omitted; use get_showcase for those. Sub-pages are not exposed. A showcase with sub-pages comes back with only its top-level items. `url` is the public share link to give to people. It is not an Air webapp link and not a CDN link. A link is usable when `active` is true and `expiresAt` is null or in the future; an expired link can still be `active: true`. Disabled links are included (`active: false`). The password is never returned. `hasPassword` says whether one is set, and `requireAccount` says whether the recipient must sign in. Tell the recipient when a password or an Air account is required. The response is `{ data, pagination, total }`. The API defaults limit to 12 and caps it at 200. Filter with search (showcase name) or status (`active`, `inactive`, or `expired`).

list_showcases

List tags in the workspace, optionally filtered by name

list_tags

List people in the workspace directory. Use email for a specific person and search for a name. Do not page the whole directory. type defaults to member. Pass guest or libraryMember to list those. email with no type searches every type. An unknown email is an empty list. id is the account id for discussion authors and mentions. search is a case-insensitive substring on first name, last name, full name, or email, 1 to 100 characters. email is an exact, case-insensitive match. search and email cannot be combined. Sorted by firstJoinedAt ascending, then id. firstJoinedAt is Postgres timestamp text, not ISO 8601, for example `2024-03-01 12:00:00.123456+00`. It has up to 6 fraction digits with trailing zeros dropped, and a UTC offset. avatar is omitted when unset. The response is `{ data, pagination, total }`. The API defaults limit to 50 and caps it at 100. To get the next page, pass cursor with the same filters. Changing a filter with a cursor is rejected. Listing members does not spend action credits. Board guests and library-only members cannot list the directory. A 403 whose body has extra.reason missing_scope means this connection needs members.read. Reconnect Air; a grant saved before that scope was advertised does not widen on its own. Other 403s are unchanged.

list_members

List the workspaces the authenticated caller can access. Use this to discover a workspaceId to pass to other tools when no default workspace is configured (e.g. multi-tenant HTTP mode). Requires OAuth bearer auth; not available on the single-workspace API-key path.

list_workspaces

Remove an asset from a board. The asset stays in the workspace.

remove_asset_from_board

Remove an asset from a showcase. The asset stays in the workspace. Removing an asset that is not in the showcase succeeds. Sub-pages are not exposed. A showcase with sub-pages comes back with only its top-level items.

remove_asset_from_showcase

Remove a board from a showcase. The board stays in the workspace. Removing a board that is not in the showcase succeeds. Sub-pages are not exposed. A showcase with sub-pages comes back with only its top-level items.

remove_board_from_showcase

Remove a tag from an asset version. If versionId is not provided, uses the cover version.

remove_tag_from_asset

Rename an asset by updating its display title only. To update description as well, use update_asset instead. Optionally provide a versionId to target a specific version.

rename_asset

Set a custom field value on an asset. Provide exactly one of `value` or `values`; pass `null` to clear. For plain-text and date fields use `value`. For single-select and multi-select fields use `values` (array of option ID objects) — or pass the option ID via `value` and the field type will be auto-detected and converted. If the select option does not exist yet, call add_custom_field_option first and use the returned option id.

update_asset_custom_field

Set a custom field value on a board. Provide exactly one of `value` or `values`; pass `null` to clear. For plain-text and date fields use `value`. For single-select and multi-select fields use `values` (array of option ID objects) — or pass the option ID via `value` and the field type will be auto-detected and converted. If the select option does not exist yet, call add_custom_field_option first and use the returned option id. Passing a single option id on a multi-select replaces the whole selection.

set_board_custom_field