MCP tool reference

The Focal MCP server exposes 76 tools. They are grouped by what they may change, and every tool lists its parameters below. For setup, authentication and limits, see the MCP server guide.

Read-only

These tools only read data. Clients can run them without asking for confirmation.

Tool	Title	What it does	Scope
get_account	Get account	Get the organization, permission scopes and accessible spaces you are working with — a quick way to find space ids.	spaces:read
get_ad_accounts	Get ad accounts	Get connected ad accounts by id, with their currency and timezone — use list_ad_accounts to browse them.	metrics:read
get_ads	Get ads	Get ads by id, such as query_metrics ad keys, in list_ads’ shape — use list_ads to browse an account’s ads.	metrics:read
get_board_column	Get board column	Get specific columns’ configuration on a board by id — use list_board_columns for a board’s full schema.	boards:read
get_boards	Get boards	Get boards by id when you already hold their ids — use list_boards to browse a space’s boards.	boards:read
get_collection	Get collection	Get collections by id when you already hold their ids — use list_collections to browse a space’s collections.	collections:read
get_comments	Get comments	Get comments by id, each top-level one with its replies — use list_comments to browse a media’s or task’s threads.	comments:read
get_creatives	Get creatives	Get ad creatives by id, such as query_metrics creative keys, in list_creatives’ shape — use list_creatives to browse.	metrics:read
get_folders	Get folders	Get folders by id when you already hold their ids — use list_folders to browse a folder’s contents.	media:read
get_library_views	Get library views	Get saved library views by id when you already hold their ids — use list_library_views to browse a space’s views.	media:read
get_media	Get media	Get media by id with custom fields and lifetime ad metrics — use list_media to browse or search_media to find.	media:read
get_media_attribute	Get media attribute	Get media custom field definitions by id, including a tags field’s options — use list_media_attributes to browse.	media:read
get_media_download	Get media download	Get signed download URLs for media’s original full-quality files, not previews; they expire in about an hour.	media:read
get_media_ocr	Get media OCR	Get the text detected on screen in media images and videos, as structured blocks or plain text.	media:read
get_media_transcript	Get media transcript	Get speech transcripts of video or audio media, as timestamped segments or plain text.	media:read
get_media_upload	Get media upload	Get the status of media uploads and URL imports by id, with the media once finished.	media:read
get_spaces	Get spaces	Get spaces by id when you already hold their ids — use list_spaces to find a space by name.	spaces:read
get_users	Get users	Get a space’s members by id, returning their names — use list_users to browse a space’s members.	spaces:read
list_ad_accounts	List ad accounts	List the ad accounts connected to the organization, the starting point for every ad metrics lookup.	metrics:read
list_ad_campaigns	List ad campaigns	List ad campaigns in given ad accounts, to get campaign ids for query_metrics filters and the other ad lists.	metrics:read
list_ad_sets	List ad sets	List ad sets in given ad accounts with their campaigns, to get ad set ids for query_metrics and list_ads.	metrics:read
list_ads	List ads	List ads in given ad accounts with their campaign, ad set, creatives and library media — use get_ads for known ids.	metrics:read
list_board_columns	List board columns	List a board’s columns (its schema) with ids, types and options — read it before writing task values.	boards:read
list_board_tasks	List board tasks	List every task on a board, newest first, with chosen column values — use search_board_tasks to find specific tasks.	boards:read
list_board_views	List board views	List a board’s saved views with their filters, visible columns and layout.	boards:read
list_boards	List boards	List the boards in a space, newest first — use get_boards when you already hold board ids.	boards:read
list_collections	List collections	List a space’s collections, newest first, optionally matching by name — use list_folders for the library tree.	collections:read
list_comments	List comments	List the comment threads on one media or board task, newest first, with replies nested.	comments:read
list_creatives	List creatives	List ad creatives run in given ad accounts, with format, ad count and matching library media.	metrics:read
list_folders	List folders	Browse a space’s library folder tree, or find folders and media by name — use list_media for filtered media lists.	media:read
list_library_views	List library views	List a space’s saved library views: the shared saved searches the library sidebar shows.	media:read
list_media	List media	List a space’s media, newest first, filtered by folder, type, name or date — use search_media to find by meaning.	media:read
list_media_attributes	List media attributes	List the custom fields defined on a space’s media library, to find field ids before reading or writing values.	media:read
list_metrics	List metrics	List the metric keys query_metrics accepts for given ad accounts, including each account’s synced conversions.	metrics:read
list_spaces	List spaces	List the spaces (media libraries) you can access, or find one by name, to get the space ids other tools need.	spaces:read
list_users	List users	List the members of a space by name and id, to find who to mention or assign.	spaces:read
open_media_player	Open media player	Open an interactive media gallery in the chat to browse, view and play media — use get_media to read metadata.	media:read
query_metrics	Query metrics	Query ad performance for a date window, grouped by ad, ad set, creative, media, date or media field.	metrics:read
search_board_tasks	Search board tasks	Find tasks on a board by text or column conditions — use list_board_tasks only to read a whole board.	boards:read
search_media	Search media	Search a space’s media by meaning, content and fields, or rank it by ad metrics — use list_media to browse.	media:read

Creates and additions

These tools add new data, such as a board, a comment or an upload. They don’t overwrite or remove existing data.

Tool	Title	What it does	Scope
add_media_attribute_options	Add media attribute options	Append options to a media tags field while preserving every existing option.	media:write
complete_media_upload	Complete media upload	Finish direct uploads from create_media_upload after their bytes are sent, verifying each file and creating the media.	media:write
create_board	Create board	Create boards in a space, each starting with the app’s default columns and grid view and no tasks.	boards:write
create_board_column	Create board column	Add columns to a board, changing its structure — to write a value into an existing column use update_board_task.	boards:write
create_board_view	Create board view	Add saved views to a board: named filters, visible columns and layout, in search_board_tasks’ filter syntax.	boards:write
create_collection	Create collection	Create collections: curated, shareable sets of media with a guest link, separate from library folders.	collections:write
create_comment	Create comment	Post comments or replies on media or board tasks, with mentions and optional video timestamps or drawings.	comments:write
create_folder	Create folder	Create folders in a space’s media library, at the top level or inside an existing folder.	media:write
create_library_view	Create library view	Save media library searches as shared views, with their filter, sort, grouping and display mode.	media:write
create_media_from_url	Create media from URL	Import files from public HTTPS URLs as new media in a space; asynchronous, so poll get_media_upload for the result.	media:write
create_media_upload	Create media upload	Start uploading local files as new media via PUT URLs; needs your own HTTPS access, else use create_media_from_url.	media:write
react_to_comment	React to comment	Add or remove the current user’s emoji reactions on comments.	comments:write
report_feedback	Report feedback to Focal	Report a missing capability, confusing tool or wrong result in Focal’s tools to the Focal team.	spaces:read

Updates and archives

These tools may overwrite or remove existing data, such as editing a media item or archiving a board.

Tool	Title	What it does	Scope
archive_board	Archive board	Archive (soft-delete) whole boards with their tasks, columns and views — for single tasks use archive_board_task.	boards:delete
archive_board_column	Archive board column	Archive (soft-delete) board columns, removing that field from every task — to clear one value use update_board_task.	boards:delete
archive_board_task	Archive board task	Archive (soft-delete) tasks on a board so they drop out of its task lists — for the whole board use archive_board.	boards:delete
archive_board_view	Archive board view	Archive (soft-delete) saved views on a board — its tasks and columns are untouched; there is no unarchive tool.	boards:delete
archive_collection	Archive collection	Archive (soft-delete) collections and stop their share links — the media stay in the library; there is no restore.	collections:delete
archive_comment	Archive comment	Archive comments the current user wrote — a top-level comment takes its whole reply thread with it.	comments:delete
archive_folder	Archive folder	Archive (soft-delete) library folders along with every subfolder and media inside them.	media:delete
archive_library_view	Archive library view	Archive (soft-delete) saved library views for everyone in the space — the media they show are untouched.	media:delete
archive_media	Archive media	Archive (soft-delete) media so it drops out of the library, list_media and get_media.	media:delete
create_board_task	Create board task	Create tasks on a board, with their titles, column values and optional parent task.	boards:write
create_media_attribute	Create media attribute	Create a new custom field on a space’s media library — ask the user first; its type can’t be changed later.	spaces:write
delete_media_attribute_option	Delete media attribute option	Permanently delete one option from a media tags field, clearing it from every media tagged with it.	spaces:write
set_media_attribute_value	Set media attribute value	Set one custom field value on each of many media — use update_media to set several fields on one media.	media:write
update_board	Update board	Rename boards or change their descriptions — use update_board_task to change task values.	boards:write
update_board_column	Update board column	Rename board columns or change their options, value count or config — use update_board_task to change task values.	boards:write
update_board_task	Update board task	Update tasks on a board: titles, column values, position or parent task.	boards:write
update_board_view	Update board view	Change a board’s saved views: name, filters, visible columns, layout or position on the view bar.	boards:write
update_collection	Update collection	Rename collections, edit their descriptions, add or remove media, or change share link settings.	collections:write
update_comment	Update comment	Edit the text of comments the current user wrote, replacing the whole body without notifying anyone.	comments:write
update_folder	Update folder	Rename library folders or move them, with their contents, under another folder or to the space root.	media:write
update_library_view	Update library view	Change shared saved library views: name, saved search, sort, grouping, columns, display mode or position.	media:write
update_media	Update media	Rename assets or edit descriptions, folders, status and custom fields; set_media_attribute_value edits a field on many.	media:write
update_media_attribute	Update media attribute	Update a media field’s name, settings or tags options; its type cannot change.	spaces:write

Parameters

Parameters marked required must be sent; the rest are optional. Tools that act on several resources take a list, and each entry in the list carries the parameters shown under it.

add_media_attribute_options

• id (required, uuid string). The attribute definition id (UUID).
• options (required, array of object). Options to append, in order. Names that already exist on the field (case-insensitive) are skipped rather than duplicated, so the call is safe to repeat. At most 100 per request, and the field cannot exceed 499 options in total — a request that would go past that is rejected rather than partly applied.
  • name (required, string). The option’s label. Must be unique within the field (case-insensitive).
  • description (optional, string). Help text shown next to the option in Focal when picking tags. At most 500 characters; send an empty string to clear it.
• fields (required, array of string, one of id, name, type, multiple, space_id, organization_id, created_at, updated_at, options, autofill). REQUIRED. The properties of each media attribute to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice.

archive_board

• ids (required, array of uuid string). The board ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one board.

archive_board_column

• board_id (required, uuid string). The board id (UUID).
• column_ids (required, array of uuid string). The column ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one column. Every id must be a column of the same board_id.

archive_board_task

• board_id (required, uuid string). The board id (UUID).
• row_ids (required, array of uuid string). The row ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one row.

archive_board_view

• board_id (required, uuid string). The board id (UUID).
• view_ids (required, array of uuid string). The board view ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one board view. Every id must be a view of the same board_id.

archive_collection

• ids (required, array of uuid string). The collection ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one collection.

archive_comment

• ids (required, array of uuid string). The comment ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one comment.

archive_folder

• ids (required, array of uuid string). The folder ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one folder.

archive_library_view

• ids (required, array of uuid string). The library view ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one library view.

archive_media

• ids (required, array of uuid string). The media asset ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one media asset.

complete_media_upload

• ids (required, array of uuid string). The upload ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one upload. These are the ids create_media_upload returned.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice. Use a fresh key for this call — never the one you passed to create_media_upload. One key covers the whole batch.

create_board

• items (required, array of object). The boards to apply — 1 to 25 per call, each with its own values. Always a list, even for one board. Each entry carries its own space_id, name and optional description, so one call can create boards in several spaces.
  • space_id (required, uuid string). The space to create the board in.
  • name (required, string). Display name of the board. 1–255 characters.
  • description (optional, string, nullable). Free-form description of the board (≤2000 characters). Pass null to clear it.
• fields (required, array of string, one of id, name, description, organization_id, space_id, created_at, updated_at, html_url). REQUIRED. The properties of each board to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice. One key covers the WHOLE batch: retrying with it replays the original envelope instead of creating duplicates — failed entries included, which a replay never creates. Re-send those under a fresh key.

create_board_column

• board_id (required, uuid string). The board id (UUID).
• items (required, array of object). The columns to apply — 1 to 25 per call, each with its own values. Always a list, even for one column. Every entry is created on the same board_id.
  • name (required, string). The column’s label on the board. 1–255 characters, and unique on the board (case-insensitive) — a name another column already has is a 400, matching what the app refuses to save.
  • type (required, string, one of 13 values). The kind of column to create. Cannot be changed afterwards — cell values are encoded per type — so add a new column rather than retyping one. Two types need more than a name: - mediacolumn mirrors a media attribute onto the board. It requires media_attribute_id and at least one entry in config.media_column_ids; a value written into the cell lands on the media attached in those columns, and an edit made on the asset shows up here — which is what makes the value filterable in the media library, unlike a plain column. - creativeid auto-generates an ID for attached media. It requires config.naming_convention_id (a Creative ID pattern from the board’s space) and at least one entry in config.media_column_ids. A board holds at most one. The types a column read can report but this can’t create are the system columns backed by a field on the row itself (createdat, updatedat, and the name / created-by / updated-by sub-types) and relation, insights, metricsdata, externaldata, mediaattribute, checklist, list; add those in the app.
  • media_attribute_id (optional, uuid string). The media attribute a mediacolumn column mirrors — a MediaAttribute.id in the board’s own space, from GET /v1/media-attributes. Required for that type and rejected on every other one. Not patchable afterwards: the cell’s stored value is encoded for the attribute’s type, so repointing the column would strand it.
  • multiple (optional, boolean). Whether each row holds several values in this column. Only tags, user and media columns can (400 on any other type). Changing it on a populated column rewrites every row’s stored value in the background, and multiple → single keeps only each cell’s first value.
  • options (optional, array of object). Initial options, in display order. tags columns only (400 on any other type); each option’s id is generated and returned on the created column. At most 499 options.
    • name (required, string). The option’s label, as shown in the cell and its picker.
    • description (optional, string). Help text shown next to the option when picking a value. At most 500 characters; send an empty string to clear it.
  • config (optional, object). Type-specific configuration, mirroring the config object a column read returns. Only the keys belonging to this column’s type are accepted — any other key is a 400 naming it, rather than a setting that silently did nothing: - text → character_limit, uppercase, wrap_text, text_format - richtext → character_limit - number → unit, unit_position, decimal_places, number_format - date → date_format - media → default_to_library, folder_id, default_status - mediacolumn → media_column_ids - creativeid → naming_convention_id, media_column_ids, trigger_type, automation_id - tags, checkbox, user, link, rating, color → no configuration Keys you omit keep their stored value. folder_id must name a folder in the board’s own space, and every media_column_ids entry a media column on this same board.
    • character_limit (optional, integer, nullable).
    • uppercase (optional, boolean).
    • wrap_text (optional, boolean).
    • text_format (optional, string, one of capitalize, uppercase, lowercase, titlecase, nullable).
    • unit (optional, string, nullable).
    • unit_position (optional, string, one of prefix, suffix).
    • decimal_places (optional, integer, nullable).
    • number_format (optional, string, one of bytes, duration, aspectRatio, compact, percentage, nullable).
    • date_format (optional, object, nullable).
    • default_to_library (optional, boolean).
    • folder_id (optional, uuid string, nullable).
    • default_status (optional, string, nullable).
    • media_column_ids (optional, array of uuid string).
    • naming_convention_id (optional, uuid string).
    • trigger_type (optional, string, one of new-row, new-media, automation).
    • automation_id (optional, uuid string, nullable).
• fields (required, array of string, one of 15 values). REQUIRED. The properties of each column to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice. One key covers the WHOLE batch: retrying with it replays the original envelope instead of creating duplicate columns.

create_board_task

• board_id (required, uuid string). The board id (UUID).
• items (required, array of object). The rows to apply — 1 to 25 per call, each with its own values. Always a list, even for one row. Every entry is created on the same board_id.
  • title (optional, string, nullable). Row title. This IS the write path for the board’s display-name column (the one with sub_type: "name", usually labelled Name) — that column is rejected as a cell, whatever its type. null clears it.
  • position (optional, number, nullable). Sort position (lower renders first). May be fractional.
  • parent_id (optional, uuid string, nullable). Id of another row on the same board to nest this row under, making it a child row; null (the default on create) places the row at the board’s top level. On update, changing parent_id MOVES the row — its own child rows follow it. A row can’t be its own parent or move under one of its descendants (400). Siblings order by position.
  • cells (optional, array of object). Cell values to set — one entry per column. A column must clear two independent gates. Role: five columns hold their value on the row itself and are rejected whatever their type — the display-name column (sub_type: "name"), set via title instead, plus the created-by / updated-by sub_types and the createdat / updatedat types, which aren’t writable at all. Carrying a sub_type isn’t itself disqualifying: start-date / due-date are ordinary cells. Type: must be one of the writable types listed under value.
    • column_id (required, uuid string). Column to set — Column.id from GET /v1/boards/{id}/columns.
    • value (required, array of (string or number or boolean or object) or string or number or boolean or object, nullable). New value, in the column’s JSON type (an array for multi-value columns); null clears the cell. Writable types: text, number, tags, checkbox, date, link, richtext, media, user — plus a mediacolumn whose mirrored attribute (Column.media_attribute_type) is one of those except richtext/media. Any other type is rejected. Per type: tags takes option ids or names (for a tags-backed mediacolumn, resolved against the ATTRIBUTE’s Column.options). richtext takes Markdown — what reads return — or a Tiptap doc for full editor fidelity. media takes media id(s) that resolve in the board’s space; upload new files via POST /v1/media/uploads first. user takes user id(s) of the board’s space members (GET /v1/users?space_id=…). A mediacolumn cell follows the mirrored attribute’s shape and cardinality (Column.multiple) and also writes through to the media attached to the row’s media columns — if those columns are archived the row still stores the value, but no media are updated.
• fields (required, array of string, one of 12 values). REQUIRED. The properties of each row to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• columns (required, array of string). REQUIRED. Which of the board’s columns to return inside each row’s fields array — there is no ‘all columns’ default, because a wide board’s cells are the bulk of what a row costs your context window. Accepts column ids or column names (case-insensitive) from list_board_columns; an entry that matches no column fails the whole call before anything is written, and the error lists the valid columns. Each row’s fields come back in the order you list them here, so you know the shape before you parse it. Pass [] to return no cell values at all, when you only want the rows themselves.

create_board_view

• board_id (required, uuid string). The board id (UUID).
• items (required, array of object). The views to apply — 1 to 25 per call, each with its own values. Always a list, even for one view. Every entry is created on the same board_id.
  • name (required, string). The view’s label on the board’s view bar. 1–255 characters. Unlike column names, view names need not be unique — the app allows duplicates.
  • type (optional, string, one of grid, board, timeline, cards). How the view presents the board’s rows. Defaults to grid.
  • filters (optional, array of object). Conditions a row must satisfy to appear in the view, in the same vocabulary as POST /v1/boards/{id}/rows/search — so a search you just ran can be saved as a view verbatim. Every entry must hold; a value array on an equals entry is any-of. [] clears the view’s filters. Two limits differ from search: is_empty / is_not_empty can’t be stored on a view (400), and not_equals takes a single value, because “none of these” has no stored form.
    • column_id (required, uuid string). The column to filter on — a Column.id from GET /v1/boards/{id}/columns.
    • operator (required, string, one of equals, not_equals, contains, gt, gte, lt, lte, is_empty, is_not_empty). How the cell is compared to value: - equals / not_equals — the cell holds (or doesn’t hold) the value. A multi-value cell matches on any of its values, so not_equals reads as “has none of these”. Strings are case-insensitive; date compares by calendar day. - contains — case-insensitive substring of the cell’s text. Not on id-backed cells (tags, user, media, relation) — use equals (it accepts option names) or query. - gt / gte / lt / lte — against a single number or ISO date. - is_empty / is_not_empty — whether the cell holds anything. Takes no value, and the only operators available on structured cells (checklist, insights, metricsdata, externaldata, mediaattribute).
    • value (optional, array of (string or number or boolean or object) or string or number or boolean or object, nullable). What to compare against, in the column’s own JSON type (see RowField.value). An array is any-of, and is accepted by equals / not_equals only — contains and the ordered operators take one value, and is_empty / is_not_empty take none. tags values may be option ids or names; an option the column doesn’t have is rejected rather than silently matching nothing.
  • visible_column_ids (optional, array of uuid string). Column IDs the view shows, in display order — Column.id values from GET /v1/boards/{id}/columns. [] means the view declares no columns of its own and falls back to showing every column on the board, which is what a freshly created view does. A column the board doesn’t have is a 400, and so is naming the same column twice. Don’t send back a list you read from a view whose visible_columns_pinned is false: that set was synthesized from the board, and writing it pins it.
  • position (optional, integer). Sort position among the board’s views; lower renders first. Defaults to the end of the board’s views on create.
• fields (required, array of string, one of 14 values). REQUIRED. The properties of each view to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice. One key covers the WHOLE batch: retrying with it replays the original envelope instead of creating duplicate views.

create_collection

• items (required, array of object). The collections to apply — 1 to 25 per call, each with its own values. Always a list, even for one collection. Each entry carries its own space_id, name, optional description and optional media_ids, so one call can create collections in several spaces.
  • space_id (required, uuid string). The space to create the collection in.
  • name (required, string). Display name of the collection. 1–255 characters.
  • description (optional, string). Free-text description of the collection (≤2000 characters).
  • media_ids (optional, array of uuid string). Media to put in the collection, in display order. Every id must be live media in the same space; an id that isn’t rejects the whole entry rather than silently dropping it.
  • sharing (optional, object). Share-link settings. Only the keys you include change; the rest keep their current values. The link itself always exists and cannot be minted or revoked — archive the collection to stop it resolving.
    • password (optional, string, nullable). Password a guest must type to open the share link. Send null to remove the password and let anyone with the link in. Never returned by any read — sharing.password_protected tells you whether one is set.
    • expires_at (optional, date string, nullable). Calendar day (YYYY-MM-DD) after which the share link stops resolving. Send null to let it live forever.
    • allow_download (optional, boolean). Let guests download the collection’s media.
    • allow_comments (optional, boolean). Let guests comment on the collection’s media.
    • allow_status_change (optional, boolean). Let guests change the status of the collection’s media.
• fields (required, array of string, one of 12 values). REQUIRED. The properties of each collection to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice. One key covers the WHOLE batch: retrying with it replays the original envelope instead of creating duplicates — failed entries included, which a replay never creates. Re-send those under a fresh key.

create_comment

• items (required, array of object). The comments to apply — 1 to 25 per call, each with its own values. Always a list, even for one comment. Each entry carries its own target and body, so one call can comment in several places.
  • media_id (optional, uuid string). The media whose comments to read or write. Covers comments made on it anywhere — in the library and in the board media player.
  • row_id (optional, uuid string). The board row (task) whose comments to read or write.
  • reply_to_id (optional, uuid string). Reply to this comment instead of starting a new thread. The reply joins the thread’s media or row, so send it without media_id or row_id. Replying to a reply adds to the same thread.
  • body (required, string). The comment body as Markdown (≤10000 characters). Mentions are written <@user_id> — the user’s id in angle brackets after an @ — and render in the app as that person’s name. Every mentioned user must be a member of the comment’s space, and each one is notified by email and in the app when the comment is created.
  • annotation (optional, object). Anchor a top-level media comment to a spot on the media, as the app’s media player does: pin it to a moment of a video, to a page, and/or draw over it. Set at least one of timestamp, page or a non-empty drawings. Only with media_id. The anchor is fixed once the comment is created.
    • timestamp (optional, number). Seconds into the video the comment is pinned to. Only videos have one.
    • timestamp_end (optional, number). End, in seconds, of the stretch of video the comment covers. Leave it out to mark a single moment; when set it must be at least timestamp.
    • page (optional, integer). The page (counting from 1) of a multi-page media. Only for media with more than one page.
    • drawings (optional, array of object). Shapes to draw over the media (≤50), for images and videos. Every coordinate must lie within the media’s width × height.
• fields (required, array of string, one of 19 values). REQUIRED. The properties of each comment to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice. One key covers the WHOLE batch: retrying with it replays the original envelope instead of posting duplicates — failed entries included, which a replay never creates. Re-send those under a fresh key.

create_folder

• items (required, array of object). The folders to apply — 1 to 25 per call, each with its own values. Always a list, even for one folder. Each entry carries its own space_id, name and optional parent_id, so one call can create folders in several spaces.
  • space_id (required, uuid string). The space to create the folder in.
  • name (required, string). Display name of the folder. 1–255 characters.
  • parent_id (optional, uuid string, nullable). Id of an existing folder in the same space to create the folder inside; omit (or pass null) for a top-level folder.
• fields (required, array of string, one of kind, id, name, parent_id, space_id, total_media_count, organization_id, created_at, updated_at, html_url). REQUIRED. The properties of each folder to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice. One key covers the WHOLE batch: retrying with it replays the original envelope instead of creating duplicates — failed entries included, which a replay never creates. Re-send those under a fresh key.

create_library_view

• items (required, array of object). The library views to apply — 1 to 25 per call, each with its own values. Always a list, even for one library view. Each entry carries its own space_id and view settings, so one call can create views in several spaces.
  • space_id (required, uuid string). The space whose library this view belongs to.
  • name (optional, string, nullable). Display name of the view. 1–255 characters.
  • view_mode (optional, string, one of gallery, grid). Defaults to gallery.
  • filter (optional, object, nullable). The saved search this view runs, in the same vocabulary as POST /v1/media/search — every entry is ANDed. null means the view shows the whole library unfiltered. include_subfolders, sort and order are absent on purpose: a view doesn’t store folder recursion (the app settles that when the view runs), and result ordering lives in the view’s own sort.
    • query (optional, string). Free-text query, ranked by relevance (≤200 chars). Matches names, descriptions, folder names, tags and attribute values; in spaces with Focal AI enabled it also matches text detected in the asset (OCR), speech transcripts, and the visual content itself. A media id here matches that asset exactly.
    • type (optional, string, one of video, image, playable, file). Restrict to one file type.
    • folder_id (optional, uuid string). Restrict to a folder in the searched space. Subfolders are included unless include_subfolders is false. Unknown folders are rejected rather than ignored.
    • status (optional, string). Restrict to media with this status — an id or name from the space’s catalog (the Space resource’s media_statuses), the same id-or-name contract as a status write.
    • uploaded_by (optional, uuid string). Restrict to media uploaded by this user (a GET /v1/users id).
    • attributes (optional, array of object). Filter on media attribute (custom field) values. Media must satisfy every entry; within an entry, values is any-of. number and date attributes aren’t searchable yet and are rejected.
    • created_after (optional, date string or date-time string). Only media created on or after this date/timestamp.
    • created_before (optional, date string or date-time string). Only media created on or before this date/timestamp.
    • last_activity_after (optional, date string or date-time string). Only media the ad platforms last reported data for on or after this date/timestamp — i.e. that were still running then. Distinct from created_after, which is when the asset was added to Focal. Media that never ran as an ad never match.
    • last_activity_before (optional, date string or date-time string). Only media the ad platforms last reported data for on or before this date/timestamp. Pair with last_activity_after to ask for everything that was running inside a window.
    • metric_filters (optional, array of object). Narrow to media whose ad-platform metrics satisfy every one of these (ANDed, like the other filters). Compares against lifetime totals — { metric: "spend", operator: "greater_than", value: 1000 } means “has spent over 1000 in total”, not “spent over 1000 in some window”. Media with no data for the metric never match.
  • sort (optional, object, nullable).
    • field (required, string). The column to sort by — a built-in library column key (name, status, type, size, uploadedById, uploadedAt, …) or a media attribute id from GET /v1/media-attributes.
    • order (required, string, one of asc, desc).
  • group_by (optional, string, nullable). Column to group by. Same vocabulary as sort.field.
  • visible_fields (optional, array of string, nullable). Columns to show, in display order. Built-in library column keys or media attribute ids from GET /v1/media-attributes.
  • order (optional, integer). Position in the space’s view list. Omit on create to append to the end.
• fields (required, array of string, one of 14 values). REQUIRED. The properties of each library view to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice. One key covers the WHOLE batch: retrying with it replays the original envelope instead of creating duplicate views — failed entries included, which a replay never creates. Re-send those under a fresh key.

create_media_attribute

• space_id (required, uuid string). The space whose media library gets the new field.
• name (required, string). Display name of the field. 1–255 characters.
• type (required, string, one of text, number, tags, checkbox, date, link, user). The kind of field to create. Cannot be changed afterwards — stored values are encoded per type — so create a new field instead of retyping one.
• multiple (optional, boolean). Whether the field holds multiple values per media. Only tags and user fields can (400 on any other type). Switching a populated field from multiple to single is destructive — every cell keeps only its first value, across the whole space.
• hide_from_guests (optional, boolean). Hide this field from Guest users in the media player.
• options (optional, array of object). Initial options, in display order. tags fields only (400 on any other type); each option’s id is generated and returned. At most 499 options per field.
  • name (required, string). The option’s label. Must be unique within the field (case-insensitive).
  • description (optional, string). Help text shown next to the option in Focal when picking tags. At most 500 characters; send an empty string to clear it.
• allow_create (optional, boolean). Whether new options may be added to this field ad hoc — both while tagging in the app and via POST /v1/media-attributes/{id}/options on the media:write scope alone. When this is false, that call needs spaces:write (plus admin/owner for a connector) instead of being rejected outright. Defaults to false on create, matching the app. tags fields only.
• show_in_library (optional, boolean). Surface this field’s options as clickable suggestions in media library search. tags fields only.
• autofill (optional, object, nullable). AI autofill for this field — an object to configure it, null to turn it off. text and tags fields only (400 on any other type). Enabling it requires a prompt, either in this call or already stored. Turning it on makes the AI write values across the space’s media, so treat it as a change with reach.
  • prompt (optional, string). The instruction the AI follows when filling this field — e.g. “the primary call to action in this ad”. Required: autofill enabled with no instruction never runs, so this API won’t create that state (the app allows it mid-edit). Rich prompts written in the app may @mention other fields; those read back flattened to @Label text, and writing a plain string replaces the rich content. At most 4000 chars.
  • allowed_media_types (optional, array of string, one of statics, videos, nullable). Restrict autofill to these media kinds. null (the default) runs it on everything. Use this rather than wording the prompt to opt out — a column restricted here is never queued for the wrong kind of media in the first place.
  • name_only (optional, boolean). When true the AI sees only the media’s filename — no visual analysis, transcript, or metadata. Much cheaper and faster, and the right choice when the answer is encoded in a naming convention.
• fields (required, array of string, one of id, name, type, multiple, space_id, organization_id, created_at, updated_at, options, autofill). REQUIRED. The properties of each media attribute to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice.

create_media_from_url

• items (required, array of object). The URL imports to apply — 1 to 25 per call, each with its own values. Always a list, even for one URL import. Each entry carries its own space_id, url and optional name / folder_id / library, so one call can import into several spaces or folders.
  • space_id (required, uuid string). Space to create the media in.
  • url (required, string). URL import: HTTPS URL of the file to fetch and store as media. Must resolve to a public host — private, loopback, and link-local addresses are rejected. Supports images, videos, playables, and other files, up to the same size limits as a direct upload. Exactly one of url and size is required.
  • name (optional, string). Display name. Required for direct uploads (absent mime_type, its extension determines the media type); defaults to a name derived from url for URL imports.
  • folder_id (optional, uuid string). Folder to place the media in, once ready. Must belong to space_id. Defaults to the space root.
  • library (optional, boolean). Whether the media appears in the space’s media library (default true). Pass false when the file isn’t meant for the space’s media library — e.g. an asset destined for a board row’s media column — so it doesn’t clutter the library. Non-library media stay fully addressable by id (get, download, transcript/OCR, update, archive) and referenceable from board rows; they’re only excluded from the GET /v1/media library listing.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice. One key covers the WHOLE batch: retrying with it replays the original envelope instead of re-importing anything — failed entries included, which a replay never creates. Re-send those under a fresh key.

create_media_upload

• items (required, array of object). The file uploads to apply — 1 to 25 per call, each with its own values. Always a list, even for one file upload. Each entry carries its own space_id, size and name.
  • space_id (required, uuid string). Space to create the media in.
  • size (required, integer). Exact size of the file in bytes (0 for an empty file), as reported by the filesystem (e.g. stat / wc -c) — never an estimate. Verified against the stored object by complete_media_upload; a mismatch fails the upload permanently.
  • name (required, string). Display name, including the file extension — absent mime_type, the extension determines the media type (image / video / playable / file).
  • mime_type (optional, string). Direct upload only: the file’s MIME type. When given, it determines the media type (image / video / playable / file) and is pinned as the stored object’s Content-Type; when omitted, the type is derived from name’s extension.
  • folder_id (optional, uuid string). Folder to place the media in, once ready. Must belong to space_id. Defaults to the space root.
  • library (optional, boolean). Whether the media appears in the space’s media library (default true). Pass false when the file isn’t meant for the space’s media library — e.g. an asset destined for a board row’s media column — so it doesn’t clutter the library. Non-library media stay fully addressable by id (get, download, transcript/OCR, update, archive) and referenceable from board rows; they’re only excluded from the GET /v1/media library listing.
• idempotency_key (required, string). Client-generated key for safe retries (a UUID is recommended). Generate a fresh key for every tool call and reuse it only when retrying that exact call: a retry with the same key returns the original result instead of running twice. One key covers the WHOLE batch: retrying with it replays the original envelope — including every upload_url — instead of opening new sessions. A replay never opens sessions for the entries that failed, so re-send those under a fresh key. Never reuse it for complete_media_upload.

delete_media_attribute_option

• id (required, uuid string). The attribute definition id (UUID).
• option_id (required, uuid string). Id of the option to delete, from the definition’s options[].id.
• fields (required, array of string, one of id, name, type, multiple, space_id, organization_id, created_at, updated_at, options, autofill). REQUIRED. The properties of each media attribute to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_account

No parameters.

get_ad_accounts

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• ids (required, array of uuid string). The ad account ids (UUIDs) to act on — 1 to 100 per call. Always a list, even for one ad account.
• fields (required, array of string, one of id, external_id, name, service, currency, timezone_name, external_created_at, cutoff_date, created_at, updated_at). REQUIRED. The properties of each ad account to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_ads

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• ids (required, array of uuid string). The ad ids (UUIDs) to act on — 1 to 100 per call. Always a list, even for one ad.
• fields (required, array of string, one of 15 values). REQUIRED. The properties of each ad to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_board_column

• board_id (required, uuid string). The board id (UUID).
• column_ids (required, array of uuid string). The column ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one column.
• fields (required, array of string, one of 15 values). REQUIRED. The properties of each column to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_boards

• ids (required, array of uuid string). The board ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one board.
• fields (required, array of string, one of id, name, description, organization_id, space_id, created_at, updated_at, html_url). REQUIRED. The properties of each board to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_collection

• ids (required, array of uuid string). The collection ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one collection.
• fields (required, array of string, one of 12 values). REQUIRED. The properties of each collection to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_comments

• ids (required, array of uuid string). The comment ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one comment.
• fields (required, array of string, one of 19 values). REQUIRED. The properties of each comment to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_creatives

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• ids (required, array of string). The creative ids to look up — 1 to 100 per call, always a list. A creative id is a content fingerprint, not a UUID: take it from list_creatives, an ad’s creative_ids, or the key of a query_metrics row under group_by: "creative".
• fields (required, array of string, one of 12 values). REQUIRED. The properties of each creative to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_folders

• ids (required, array of uuid string). The folder ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one folder.
• fields (required, array of string, one of kind, id, name, parent_id, space_id, total_media_count, organization_id, created_at, updated_at, html_url). REQUIRED. The properties of each folder to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_library_views

• ids (required, array of uuid string). The library view ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one library view.
• fields (required, array of string, one of 14 values). REQUIRED. The properties of each library view to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_media

• ids (required, array of uuid string). The media asset ids (UUIDs) to act on — 1 to 100 per call. Always a list, even for one media asset.
• fields (required, array of string, one of 26 values). REQUIRED. The properties of each media asset to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• metrics (optional, array of string). Performance metrics to include in each media’s metrics.insights. Default: the core set (spend, impressions, clicks, reach, installs, watch_min_3_seconds). all returns every metric with data — ad platforms report hundreds of conversion events, so expect a large response — or name keys like meta.omni_purchase. Only metrics with stored data come back, so an unknown key is silently absent rather than an error. Needs metrics to survive the fields selection.

get_media_attribute

• ids (required, array of uuid string). The attribute definition ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one attribute definition.
• fields (required, array of string, one of id, name, type, multiple, space_id, organization_id, created_at, updated_at, options, autofill). REQUIRED. The properties of each media attribute to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_media_download

• ids (required, array of uuid string). The media asset ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one media asset.

get_media_ocr

• ids (required, array of uuid string). The media asset ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one media asset.
• format (optional, string, one of blocks, text). Response form, applied to every id: blocks (default) returns the structured block array; text returns all detected text as one newline-joined string instead.

get_media_transcript

• ids (required, array of uuid string). The media asset ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one media asset.
• format (optional, string, one of segments, text). Response form, applied to every id: segments (default) returns timestamped segments in playback order; text returns each whole transcript as one newline-joined string instead.

get_media_upload

• ids (required, array of uuid string). The upload ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one upload. These are the ids an upload or URL import returned.

get_spaces

• ids (required, array of uuid string). The space ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one space.
• fields (required, array of string, one of id, name, description, organization_id, media_statuses, created_at, updated_at, html_url). REQUIRED. The properties of each space to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

get_users

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• ids (required, array of uuid string). The user ids (UUIDs) to act on — 1 to 25 per call. Always a list, even for one user.
• fields (required, array of string, one of id, name). REQUIRED. The properties of each user to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_ad_accounts

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• service (optional, string, one of meta, tiktok, demo). Only return accounts on this ad platform.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of id, external_id, name, service, currency, timezone_name, external_created_at, cutoff_date, created_at, updated_at). REQUIRED. The properties of each ad account to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_ad_campaigns

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• ad_account_ids (required, array of uuid string). Ad accounts to read from, from list_ad_accounts. Each must be visible in the space.
• query (optional, string). Only return rows whose name contains this (case-insensitive).
• status (optional, string, one of not_launched_yet, live, paused). Only return rows with this delivery status.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of id, external_id, ad_account_id, name, status, first_active_at, last_active_at, created_at, updated_at). REQUIRED. The properties of each ad campaign to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_ad_sets

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• ad_account_ids (required, array of uuid string). Ad accounts to read from, from list_ad_accounts. Each must be visible in the space.
• ad_campaign_ids (optional, array of uuid string). Only ad sets under these campaigns, from list_ad_campaigns.
• query (optional, string). Only return rows whose name contains this (case-insensitive).
• status (optional, string, one of not_launched_yet, live, paused). Only return rows with this delivery status.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of id, external_id, ad_account_id, name, status, first_active_at, last_active_at, created_at, updated_at, ad_campaign_id). REQUIRED. The properties of each ad set to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_ads

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• ad_account_ids (required, array of uuid string). Ad accounts to read from, from list_ad_accounts. Each must be visible in the space.
• ad_campaign_ids (optional, array of uuid string). Only ads under these campaigns, from list_ad_campaigns.
• ad_set_ids (optional, array of uuid string). Only ads in these ad sets, from list_ad_sets.
• creative_ids (optional, array of string). Only ads running these creatives — ids from list_creatives or the key of a query_metrics group_by: "creative" row.
• media_ids (optional, array of uuid string). Only ads linked to these media assets in space_id.
• query (optional, string). Only return rows whose name contains this (case-insensitive).
• status (optional, string, one of not_launched_yet, live, paused). Only return rows with this delivery status.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of 15 values). REQUIRED. The properties of each ad to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_board_columns

• board_id (required, uuid string). The board id (UUID).
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of 15 values). REQUIRED. The properties of each column to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_board_tasks

• board_id (required, uuid string). The board id (UUID).
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of 12 values). REQUIRED. The properties of each row to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• columns (required, array of string). REQUIRED. Which of the board’s columns to return inside each row’s fields array — there is no ‘all columns’ default, because a wide board’s cells are the bulk of what a row costs your context window. Accepts column ids or column names (case-insensitive) from list_board_columns; an entry that matches no column fails the whole call before anything is written, and the error lists the valid columns. Each row’s fields come back in the order you list them here, so you know the shape before you parse it. Pass [] to return no cell values at all, when you only want the rows themselves.

list_board_views

• board_id (required, uuid string). The board id (UUID).
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of 14 values). REQUIRED. The properties of each view to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_boards

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of id, name, description, organization_id, space_id, created_at, updated_at, html_url). REQUIRED. The properties of each board to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_collections

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• search (optional, string). Case-insensitive substring match (≤200 chars) against the collection name.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of 12 values). REQUIRED. The properties of each collection to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_comments

• media_id (optional, uuid string). The media whose comments to read or write. Covers comments made on it anywhere — in the library and in the board media player.
• row_id (optional, uuid string). The board row (task) whose comments to read or write.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of 19 values). REQUIRED. The properties of each comment to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_creatives

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• ad_account_ids (required, array of uuid string). Ad accounts to read from, from list_ad_accounts. Each must be visible in the space.
• ad_ids (optional, array of uuid string). Only creatives run by these ads.
• ad_campaign_ids (optional, array of uuid string). Only creatives run by ads under these campaigns, from list_ad_campaigns.
• media_ids (optional, array of uuid string). Only creatives linked to these media assets in space_id.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of 12 values). REQUIRED. The properties of each creative to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_folders

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• folder_id (optional, uuid string). Browse this folder’s contents instead of the root.
• search (optional, string). Search the whole space by name instead of browsing: case-insensitive substring match (≤200 chars) against folders anywhere in the space’s tree and the space’s library media. Cannot be combined with folder_id.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of 14 values). REQUIRED. The properties of each entry to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_library_views

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of 14 values). REQUIRED. The properties of each library view to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_media

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• folder_id (optional, uuid string). Restrict to a single folder.
• type (optional, string, one of video, image, playable, file). Filter by file type.
• search (optional, string). Case-insensitive substring match on name (≤200 chars).
• created_after (optional, date string or date-time string). Return only assets created on or after this date/timestamp.
• created_before (optional, date string or date-time string). Return only assets created on or before this date/timestamp.
• fields (required, array of string, one of 26 values). REQUIRED. The properties of each media asset to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• metrics (optional, array of string). Performance metrics to include in each media’s metrics.insights. Default: the core set (spend, impressions, clicks, reach, installs, watch_min_3_seconds). all returns every metric with data — ad platforms report hundreds of conversion events, so expect a large response — or name keys like meta.omni_purchase. Only metrics with stored data come back, so an unknown key is silently absent rather than an error. Needs metrics to survive the fields selection.

list_media_attributes

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• fields (required, array of string, one of id, name, type, multiple, space_id, organization_id, created_at, updated_at). REQUIRED. The properties of each media attribute to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_metrics

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• ad_account_ids (required, array of uuid string). The ad account ids (UUIDs) to act on — 1 to 100 per call. Always a list, even for one ad account.

list_spaces

• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• search (optional, string). Case-insensitive substring match on the space name (≤200 chars). Use this to jump straight to a named space instead of listing every page.
• fields (required, array of string, one of id, name, description, organization_id, media_statuses, created_at, updated_at, html_url). REQUIRED. The properties of each space to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

list_users

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.

open_media_player

Takes one of 2 argument shapes.

Shape 1

• ids (required, array of uuid string). Up to 100 media ids (UUIDs) to show in the player.

Shape 2

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.
• folder_id (optional, uuid string). Restrict to a single folder.
• type (optional, string, one of video, image, playable, file). Filter by file type.
• search (optional, string). Case-insensitive substring match on name (≤200 chars).
• created_after (optional, date string or date-time string). Return only assets created on or after this date/timestamp.
• created_before (optional, date string or date-time string). Return only assets created on or before this date/timestamp.

query_metrics

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• ad_account_ids (required, array of uuid string). Ad accounts to query, from list_ad_accounts. Figures are summed across them without currency conversion.
• start_date (required, string). First day of the window, inclusive (YYYY-MM-DD).
• end_date (required, string). Last day of the window, inclusive (YYYY-MM-DD).
• metrics (required, array of string). Metric keys to return, from list_metrics.
• group_by (required, string, one of date, ad, ad_set, creative, media, media_column). What each row represents.
• granularity (optional, string, one of day, week, month, quarter). Bucket size for group_by: "date". Default day.
• media_column_id (optional, uuid string). Required for group_by: "media_column" — the attribute to group by, from list_media_attributes.
• filters (optional, object). Narrow the query. All id filters combine as one OR set across kinds: a row counts when it sits under any id named in any of ad_campaign_ids, ad_set_ids, ad_ids or media_ids. To intersect them, run one filter kind per call.
  • ad_campaign_ids (optional, array of uuid string).
  • ad_set_ids (optional, array of uuid string).
  • ad_ids (optional, array of uuid string).
  • media_ids (optional, array of uuid string).
• sort (optional, object). Order rows by one of the requested metrics, or by name. Defaults to the first metric, descending. group_by: "date" is always chronological.
  • by (required, string).
  • desc (optional, boolean).
• limit (optional, integer). Max rows per page (1–500). Default 50.
• cursor (optional, string). Pagination cursor returned as next_cursor from a previous call.

react_to_comment

• items (required, array of object). The reactions to apply — 1 to 25 per call, each with its own values. Always a list, even for one reaction.
  • id (required, uuid string). The comment id (UUID).
  • emoji (required, string, one of thumbs-up, face-grin, face-grin-wink, face-surprise, heart, check, eye, rocket). The reaction, as the app’s icon name.
  • remove (optional, boolean). true to take the reaction back instead of adding it. Default false.
• fields (required, array of string, one of 19 values). REQUIRED. The properties of each comment to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

report_feedback

• category (required, string, one of missing_feature, missing_data, confusing_tool, wrong_result, other). missing_feature: an action no tool offers. missing_data: a field/resource the tools don’t expose. confusing_tool: a tool whose arguments or results were hard to use correctly. wrong_result: a tool returned something that looks incorrect.
• message (required, string). What the user was trying to do and what was missing or wrong (≤2000 chars). Written for the Focal product team.
• related_tool (optional, string). The tool this concerns, if any — an existing tool name, or the name of a tool you expected to exist.

search_board_tasks

• board_id (required, uuid string). The board id (UUID).
• query (optional, string). Free-text query — a case-insensitive substring match (≤200 chars) over the row’s title and its human-readable cell text: text, link and richtext values, plus the option / user names behind tags and user cells (and mediacolumn cells mirroring either). Ids, numbers, checkboxes and dates aren’t matched by text — use filters for those.
• filters (optional, array of object). Per-column conditions. A row must satisfy every entry (AND); within an entry a value array is any-of. A filter naming an unknown column, or one its column’s type can’t honour, is a 400 — never silently dropped, which would widen the result set.
  • column_id (required, uuid string). The column to filter on — a Column.id from GET /v1/boards/{id}/columns.
  • operator (required, string, one of equals, not_equals, contains, gt, gte, lt, lte, is_empty, is_not_empty). How the cell is compared to value: - equals / not_equals — the cell holds (or doesn’t hold) the value. A multi-value cell matches on any of its values, so not_equals reads as “has none of these”. Strings are case-insensitive; date compares by calendar day. - contains — case-insensitive substring of the cell’s text. Not on id-backed cells (tags, user, media, relation) — use equals (it accepts option names) or query. - gt / gte / lt / lte — against a single number or ISO date. - is_empty / is_not_empty — whether the cell holds anything. Takes no value, and the only operators available on structured cells (checklist, insights, metricsdata, externaldata, mediaattribute).
  • value (optional, array of (string or number or boolean or object) or string or number or boolean or object, nullable). What to compare against, in the column’s own JSON type (see RowField.value). An array is any-of, and is accepted by equals / not_equals only — contains and the ordered operators take one value, and is_empty / is_not_empty take none. tags values may be option ids or names; an option the column doesn’t have is rejected rather than silently matching nothing.
• sort (optional, string, one of position, title, created_at, updated_at). Result ordering. position (default) is the board’s own row order, so results read like the board itself; rows with no position sort last in either direction.
• order (optional, string, one of asc, desc). Sort direction. Defaults to asc for position and title, desc for created_at and updated_at.
• limit (optional, integer). Max rows per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from the previous page.
• fields (required, array of string, one of 12 values). REQUIRED. The properties of each row to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• columns (required, array of string). REQUIRED. Which of the board’s columns to return inside each row’s fields array — there is no ‘all columns’ default, because a wide board’s cells are the bulk of what a row costs your context window. Accepts column ids or column names (case-insensitive) from list_board_columns; an entry that matches no column fails the whole call before anything is written, and the error lists the valid columns. Each row’s fields come back in the order you list them here, so you know the shape before you parse it. Pass [] to return no cell values at all, when you only want the rows themselves.

search_media

• space_id (required, uuid string). Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.
• query (optional, string). Free-text query, ranked by relevance (≤200 chars). Matches names, descriptions, folder names, tags and attribute values; in spaces with Focal AI enabled it also matches text detected in the asset (OCR), speech transcripts, and the visual content itself. A media id here matches that asset exactly.
• type (optional, string, one of video, image, playable, file). Restrict to one file type.
• folder_id (optional, uuid string). Restrict to a folder in the searched space. Subfolders are included unless include_subfolders is false. Unknown folders are rejected rather than ignored.
• include_subfolders (optional, boolean). Whether to descend into subfolders. Default true. With folder_id, false restricts to that folder’s immediate contents; without it, false restricts to the space root.
• status (optional, string). Restrict to media with this status — an id or name from the space’s catalog (the Space resource’s media_statuses), the same id-or-name contract as a status write.
• uploaded_by (optional, uuid string). Restrict to media uploaded by this user (a GET /v1/users id).
• attributes (optional, array of object). Filter on media attribute (custom field) values. Media must satisfy every entry; within an entry, values is any-of. number and date attributes aren’t searchable yet and are rejected.
  • attribute_id (required, uuid string). The media attribute (custom field) to filter on — an id from GET /v1/media-attributes.
  • values (required, array of string). Values to match, interpreted per the attribute’s type: option ids or names for a tags field, user ids for a user field, "true" / "false" for a checkbox field (exactly one), and the stored text for text / link. Several values match any of them. An option value matching none of the attribute’s options — and a user value that isn’t a user id — is rejected rather than ignored, so a filter never silently widens the result set.
  • match (optional, string, one of any, none). any (default) keeps media matching at least one value; none excludes media matching any of them.
• created_after (optional, date string or date-time string). Only media created on or after this date/timestamp.
• created_before (optional, date string or date-time string). Only media created on or before this date/timestamp.
• sort (optional, string, one of 13 values). Result ordering. relevance (default) ranks by match quality — meaningful only with a query; a filter-only search falls back to newest first. Any other key sorts by that column and ignores relevance entirely.
• order (optional, string, one of asc, desc). Sort direction. Defaults to asc for name and desc for the other columns. Ignored when sort is relevance (best matches always come first).
• limit (optional, integer). Max results per page (1–100). Default 25.
• cursor (optional, string). Pagination cursor returned as next_cursor from the previous page.
• last_activity_after (optional, date string or date-time string). Only media the ad platforms last reported data for on or after this date/timestamp — i.e. that were still running then. Distinct from created_after, which is when the asset was added to Focal. Media that never ran as an ad never match.
• last_activity_before (optional, date string or date-time string). Only media the ad platforms last reported data for on or before this date/timestamp. Pair with last_activity_after to ask for everything that was running inside a window.
• metric_filters (optional, array of object). Narrow to media whose ad-platform metrics satisfy every one of these (ANDed, like the other filters). Compares against lifetime totals — { metric: "spend", operator: "greater_than", value: 1000 } means “has spent over 1000 in total”, not “spent over 1000 in some window”. Media with no data for the metric never match.
  • metric (required, string, one of spend, impressions, clicks, reach, installs, watch_min_3_seconds, watch_hook_rate_min_3_seconds). Which metric to compare — one of the keys that appear in a media’s metrics.insights.
  • operator (required, string, one of greater_than, less_than, equals). How to compare — greater_than, less_than, or equals.
  • value (required, number). The bound to compare the metric’s lifetime total against.
• fields (required, array of string, one of 26 values). REQUIRED. The properties of each media asset to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• metrics (optional, array of string). Performance metrics to include in each media’s metrics.insights. Default: the core set (spend, impressions, clicks, reach, installs, watch_min_3_seconds). all returns every metric with data — ad platforms report hundreds of conversion events, so expect a large response — or name keys like meta.omni_purchase. Only metrics with stored data come back, so an unknown key is silently absent rather than an error. Needs metrics to survive the fields selection.

set_media_attribute_value

• items (required, array of object). The attribute writes to apply — 1 to 25 per call, each with its own values. Always a list, even for one attribute write. Entries are independent: they may name different assets, different attributes, or the same attribute across many assets.
  • id (required, uuid string). The media id (UUID).
  • attribute_id (required, uuid string). The media attribute definition id (see list_media_attributes).
  • value (required, array of (string or number or boolean) or string or number or boolean, nullable). The new value, in the attribute’s JSON-native type — number → JSON number, checkbox → true/false, date → ISO 8601 string, tags → option id or name (stored as the id; reads return ids in value with names in display_value), user → user id (see GET /v1/users; names come back under display_value), text/link → string. An array for a multi-value attribute, a scalar otherwise. null clears the attribute.
• fields (required, array of string, one of 26 values). REQUIRED. The properties of each media asset to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

update_board

• items (required, array of object). The board updates to apply — 1 to 25 per call, each with its own values. Always a list, even for one board update. Each entry names the board by id and carries only the fields to change on it.
  • id (required, uuid string). The board id (UUID).
  • name (optional, string). Display name of the board. 1–255 characters.
  • description (optional, string, nullable). Free-form description of the board (≤2000 characters). Pass null to clear it.
• fields (required, array of string, one of id, name, description, organization_id, space_id, created_at, updated_at, html_url). REQUIRED. The properties of each board to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

update_board_column

• board_id (required, uuid string). The board id (UUID).
• items (required, array of object). The column updates to apply — 1 to 25 per call, each with its own values. Always a list, even for one column update. Each entry names the column by column_id and carries only the fields to change on it.
  • column_id (required, uuid string). The board column id (UUID).
  • name (optional, string). The column’s label on the board. 1–255 characters, and unique on the board (case-insensitive) — a name another column already has is a 400, matching what the app refuses to save.
  • multiple (optional, boolean). Whether each row holds several values in this column. Only tags, user and media columns can (400 on any other type). Changing it on a populated column rewrites every row’s stored value in the background, and multiple → single keeps only each cell’s first value.
  • options (optional, array of object). Rewrites the column’s option set, in display order. tags columns only. An entry with an id keeps that option (renaming it, and replacing its description if you send one); an entry without one adopts the existing option of the same name, or is added as new — so re-sending a name you already have keeps its id, and retrying is safe. Must list every option the column currently has: omitting one is a 400, not a removal, since removing an option clears that value from every row holding it. Listing the same id twice is rejected. At most 499 options.
    • id (optional, uuid string). Id of an existing option on this column to keep. Omit to add a new option. An id that isn’t an option of this column → 400.
    • name (required, string). The option’s label, as shown in the cell and its picker.
    • description (optional, string). Replaces the option’s help text. Omit to leave whatever it already has — unlike name, an absent description is not a request to clear it; send "" for that.
  • config (optional, object). Type-specific configuration, mirroring the config object a column read returns. Only the keys belonging to this column’s type are accepted — any other key is a 400 naming it, rather than a setting that silently did nothing: - text → character_limit, uppercase, wrap_text, text_format - richtext → character_limit - number → unit, unit_position, decimal_places, number_format - date → date_format - media → default_to_library, folder_id, default_status - mediacolumn → media_column_ids - creativeid → naming_convention_id, media_column_ids, trigger_type, automation_id - tags, checkbox, user, link, rating, color → no configuration Keys you omit keep their stored value. folder_id must name a folder in the board’s own space, and every media_column_ids entry a media column on this same board.
    • character_limit (optional, integer, nullable).
    • uppercase (optional, boolean).
    • wrap_text (optional, boolean).
    • text_format (optional, string, one of capitalize, uppercase, lowercase, titlecase, nullable).
    • unit (optional, string, nullable).
    • unit_position (optional, string, one of prefix, suffix).
    • decimal_places (optional, integer, nullable).
    • number_format (optional, string, one of bytes, duration, aspectRatio, compact, percentage, nullable).
    • date_format (optional, object, nullable).
    • default_to_library (optional, boolean).
    • folder_id (optional, uuid string, nullable).
    • default_status (optional, string, nullable).
    • media_column_ids (optional, array of uuid string).
    • naming_convention_id (optional, uuid string).
    • trigger_type (optional, string, one of new-row, new-media, automation).
    • automation_id (optional, uuid string, nullable).
• fields (required, array of string, one of 15 values). REQUIRED. The properties of each column to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

update_board_task

• board_id (required, uuid string). The board id (UUID).
• items (required, array of object). The row updates to apply — 1 to 25 per call, each with its own values. Always a list, even for one row update. Every entry updates a row on the same board_id and carries only the values to change on it.
  • row_id (required, uuid string). The row id (UUID).
  • title (optional, string, nullable). Row title. This IS the write path for the board’s display-name column (the one with sub_type: "name", usually labelled Name) — that column is rejected as a cell, whatever its type. null clears it.
  • position (optional, number, nullable). Sort position (lower renders first). May be fractional.
  • parent_id (optional, uuid string, nullable). Id of another row on the same board to nest this row under, making it a child row; null (the default on create) places the row at the board’s top level. On update, changing parent_id MOVES the row — its own child rows follow it. A row can’t be its own parent or move under one of its descendants (400). Siblings order by position.
  • cells (optional, array of object). Cell values to set — one entry per column. A column must clear two independent gates. Role: five columns hold their value on the row itself and are rejected whatever their type — the display-name column (sub_type: "name"), set via title instead, plus the created-by / updated-by sub_types and the createdat / updatedat types, which aren’t writable at all. Carrying a sub_type isn’t itself disqualifying: start-date / due-date are ordinary cells. Type: must be one of the writable types listed under value.
    • column_id (required, uuid string). Column to set — Column.id from GET /v1/boards/{id}/columns.
    • value (required, array of (string or number or boolean or object) or string or number or boolean or object, nullable). New value, in the column’s JSON type (an array for multi-value columns); null clears the cell. Writable types: text, number, tags, checkbox, date, link, richtext, media, user — plus a mediacolumn whose mirrored attribute (Column.media_attribute_type) is one of those except richtext/media. Any other type is rejected. Per type: tags takes option ids or names (for a tags-backed mediacolumn, resolved against the ATTRIBUTE’s Column.options). richtext takes Markdown — what reads return — or a Tiptap doc for full editor fidelity. media takes media id(s) that resolve in the board’s space; upload new files via POST /v1/media/uploads first. user takes user id(s) of the board’s space members (GET /v1/users?space_id=…). A mediacolumn cell follows the mirrored attribute’s shape and cardinality (Column.multiple) and also writes through to the media attached to the row’s media columns — if those columns are archived the row still stores the value, but no media are updated.
• fields (required, array of string, one of 12 values). REQUIRED. The properties of each row to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.
• columns (required, array of string). REQUIRED. Which of the board’s columns to return inside each row’s fields array — there is no ‘all columns’ default, because a wide board’s cells are the bulk of what a row costs your context window. Accepts column ids or column names (case-insensitive) from list_board_columns; an entry that matches no column fails the whole call before anything is written, and the error lists the valid columns. Each row’s fields come back in the order you list them here, so you know the shape before you parse it. Pass [] to return no cell values at all, when you only want the rows themselves.

update_board_view

• board_id (required, uuid string). The board id (UUID).
• items (required, array of object). The view updates to apply — 1 to 25 per call, each with its own values. Always a list, even for one view update. Each entry names the view by id and carries only the properties to change on it.
  • id (required, uuid string). The board view id (UUID).
  • name (optional, string). The view’s label on the board’s view bar. 1–255 characters. Unlike column names, view names need not be unique — the app allows duplicates.
  • type (optional, string, one of grid, board, timeline, cards). How the view presents the board’s rows.
  • filters (optional, array of object). Conditions a row must satisfy to appear in the view, in the same vocabulary as POST /v1/boards/{id}/rows/search — so a search you just ran can be saved as a view verbatim. Every entry must hold; a value array on an equals entry is any-of. [] clears the view’s filters. Two limits differ from search: is_empty / is_not_empty can’t be stored on a view (400), and not_equals takes a single value, because “none of these” has no stored form.
    • column_id (required, uuid string). The column to filter on — a Column.id from GET /v1/boards/{id}/columns.
    • operator (required, string, one of equals, not_equals, contains, gt, gte, lt, lte, is_empty, is_not_empty). How the cell is compared to value: - equals / not_equals — the cell holds (or doesn’t hold) the value. A multi-value cell matches on any of its values, so not_equals reads as “has none of these”. Strings are case-insensitive; date compares by calendar day. - contains — case-insensitive substring of the cell’s text. Not on id-backed cells (tags, user, media, relation) — use equals (it accepts option names) or query. - gt / gte / lt / lte — against a single number or ISO date. - is_empty / is_not_empty — whether the cell holds anything. Takes no value, and the only operators available on structured cells (checklist, insights, metricsdata, externaldata, mediaattribute).
    • value (optional, array of (string or number or boolean or object) or string or number or boolean or object, nullable). What to compare against, in the column’s own JSON type (see RowField.value). An array is any-of, and is accepted by equals / not_equals only — contains and the ordered operators take one value, and is_empty / is_not_empty take none. tags values may be option ids or names; an option the column doesn’t have is rejected rather than silently matching nothing.
  • visible_column_ids (optional, array of uuid string). Column IDs the view shows, in display order — Column.id values from GET /v1/boards/{id}/columns. [] means the view declares no columns of its own and falls back to showing every column on the board, which is what a freshly created view does. A column the board doesn’t have is a 400, and so is naming the same column twice. Don’t send back a list you read from a view whose visible_columns_pinned is false: that set was synthesized from the board, and writing it pins it.
  • position (optional, integer). Sort position among the board’s views; lower renders first. Defaults to the end of the board’s views on create.
• fields (required, array of string, one of 14 values). REQUIRED. The properties of each view to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

update_collection

• items (required, array of object). The collection updates to apply — 1 to 25 per call, each with its own values. Always a list, even for one collection update. Each entry names the collection by id and carries only the fields to change on it.
  • id (required, uuid string). The collection id (UUID).
  • name (optional, string). Display name of the collection. 1–255 characters.
  • description (optional, string, nullable). Free-text description of the collection (≤2000 characters).
  • media_ids (optional, array of uuid string). REPLACES the collection’s membership with exactly this list, in this order — media not named here are removed. To add or remove a few without restating the rest, use add_media_ids / remove_media_ids instead. Cannot be combined with either.
  • add_media_ids (optional, array of uuid string). Append these media to the end of the collection, keeping what is already there. Ids already in the collection are ignored rather than duplicated. Cannot be combined with media_ids.
  • remove_media_ids (optional, array of uuid string). Remove these media from the collection, leaving the rest in order. Ids that aren’t in the collection are ignored. The media themselves are untouched — only the membership changes. Cannot be combined with media_ids.
  • sharing (optional, object). Share-link settings. Only the keys you include change; the rest keep their current values. The link itself always exists and cannot be minted or revoked — archive the collection to stop it resolving.
    • password (optional, string, nullable). Password a guest must type to open the share link. Send null to remove the password and let anyone with the link in. Never returned by any read — sharing.password_protected tells you whether one is set.
    • expires_at (optional, date string, nullable). Calendar day (YYYY-MM-DD) after which the share link stops resolving. Send null to let it live forever.
    • allow_download (optional, boolean). Let guests download the collection’s media.
    • allow_comments (optional, boolean). Let guests comment on the collection’s media.
    • allow_status_change (optional, boolean). Let guests change the status of the collection’s media.
• fields (required, array of string, one of 12 values). REQUIRED. The properties of each collection to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

update_comment

• items (required, array of object). The comment edits to apply — 1 to 25 per call, each with its own values. Always a list, even for one comment edit. Each entry names the comment by id and carries its new body.
  • id (required, uuid string). The comment id (UUID).
  • body (required, string). The comment body as Markdown (≤10000 characters). Mentions are written <@user_id> — the user’s id in angle brackets after an @ — and render in the app as that person’s name. Every mentioned user must be a member of the comment’s space, and each one is notified by email and in the app when the comment is created.
• fields (required, array of string, one of 19 values). REQUIRED. The properties of each comment to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

update_folder

• items (required, array of object). The folder updates to apply — 1 to 25 per call, each with its own values. Always a list, even for one folder update. Each entry names the folder by id and carries only the fields to change on it.
  • id (required, uuid string). The folder id (UUID).
  • name (optional, string). Display name of the folder. 1–255 characters.
  • parent_id (optional, uuid string, nullable). Move the folder under this folder (which must be in the same space); null moves it to the space root. The folder’s own subtree moves with it. Moving a folder into itself or one of its descendants is rejected (400).
• fields (required, array of string, one of kind, id, name, parent_id, space_id, total_media_count, organization_id, created_at, updated_at, html_url). REQUIRED. The properties of each folder to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

update_library_view

• items (required, array of object). The library view updates to apply — 1 to 25 per call, each with its own values. Always a list, even for one library view update. Each entry names the view by id and carries only the fields to change on it.
  • id (required, uuid string). The library view id (UUID).
  • name (optional, string, nullable). Display name of the view. 1–255 characters.
  • view_mode (optional, string, one of gallery, grid).
  • filter (optional, object, nullable). The saved search this view runs, in the same vocabulary as POST /v1/media/search — every entry is ANDed. null means the view shows the whole library unfiltered. include_subfolders, sort and order are absent on purpose: a view doesn’t store folder recursion (the app settles that when the view runs), and result ordering lives in the view’s own sort.
    • query (optional, string). Free-text query, ranked by relevance (≤200 chars). Matches names, descriptions, folder names, tags and attribute values; in spaces with Focal AI enabled it also matches text detected in the asset (OCR), speech transcripts, and the visual content itself. A media id here matches that asset exactly.
    • type (optional, string, one of video, image, playable, file). Restrict to one file type.
    • folder_id (optional, uuid string). Restrict to a folder in the searched space. Subfolders are included unless include_subfolders is false. Unknown folders are rejected rather than ignored.
    • status (optional, string). Restrict to media with this status — an id or name from the space’s catalog (the Space resource’s media_statuses), the same id-or-name contract as a status write.
    • uploaded_by (optional, uuid string). Restrict to media uploaded by this user (a GET /v1/users id).
    • attributes (optional, array of object). Filter on media attribute (custom field) values. Media must satisfy every entry; within an entry, values is any-of. number and date attributes aren’t searchable yet and are rejected.
    • created_after (optional, date string or date-time string). Only media created on or after this date/timestamp.
    • created_before (optional, date string or date-time string). Only media created on or before this date/timestamp.
    • last_activity_after (optional, date string or date-time string). Only media the ad platforms last reported data for on or after this date/timestamp — i.e. that were still running then. Distinct from created_after, which is when the asset was added to Focal. Media that never ran as an ad never match.
    • last_activity_before (optional, date string or date-time string). Only media the ad platforms last reported data for on or before this date/timestamp. Pair with last_activity_after to ask for everything that was running inside a window.
    • metric_filters (optional, array of object). Narrow to media whose ad-platform metrics satisfy every one of these (ANDed, like the other filters). Compares against lifetime totals — { metric: "spend", operator: "greater_than", value: 1000 } means “has spent over 1000 in total”, not “spent over 1000 in some window”. Media with no data for the metric never match.
  • sort (optional, object, nullable).
    • field (required, string). The column to sort by — a built-in library column key (name, status, type, size, uploadedById, uploadedAt, …) or a media attribute id from GET /v1/media-attributes.
    • order (required, string, one of asc, desc).
  • group_by (optional, string, nullable). Column to group by. Same vocabulary as sort.field.
  • visible_fields (optional, array of string, nullable). Columns to show, in display order. Built-in library column keys or media attribute ids from GET /v1/media-attributes.
  • order (optional, integer). Position in the space’s view list. Omit on create to append to the end.
• fields (required, array of string, one of 14 values). REQUIRED. The properties of each library view to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

update_media

• items (required, array of object). The media updates to apply — 1 to 25 per call, each with its own values. Always a list, even for one media update. Each entry names the asset by id and carries only the fields to change on it; different entries can change different fields.
  • id (required, uuid string). The media id (UUID).
  • name (optional, string). Display name of the media. 1–255 characters.
  • folder_id (optional, uuid string, nullable). Move the media into this folder, or null to move it to the space root. The folder must belong to the same space as the media.
  • description (optional, string, nullable). Free-text description as Markdown, or null to clear it. Up to 10,000 characters.
  • status (optional, string, nullable). Set the media’s status — a status id or name from the space’s catalog (the Space resource’s media_statuses), or null to clear it. Reads return the status name.
  • attributes (optional, array of object). Media-attribute values to set — one entry per attribute definition (duplicate attribute_ids are rejected). Each write replaces the attribute’s whole value; attributes not listed are untouched.
    • attribute_id (required, uuid string). The media attribute definition id (see GET /v1/media-attributes).
    • value (required, array of (string or number or boolean) or string or number or boolean, nullable). The new value, in the attribute’s JSON-native type — number → JSON number, checkbox → true/false, date → ISO 8601 string, tags → option id or name (stored as the id; reads return ids in value with names in display_value), user → user id (see GET /v1/users; names come back under display_value), text/link → string. An array for a multi-value attribute, a scalar otherwise. null clears the attribute.
• fields (required, array of string, one of 26 values). REQUIRED. The properties of each media asset to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.

update_media_attribute

• id (required, uuid string). The attribute definition id (UUID).
• name (optional, string). Display name of the field. 1–255 characters.
• multiple (optional, boolean). Whether the field holds multiple values per media. Only tags and user fields can (400 on any other type). Switching a populated field from multiple to single is destructive — every cell keeps only its first value, across the whole space.
• hide_from_guests (optional, boolean). Hide this field from Guest users in the media player.
• options (optional, array of object). Rewrites the field’s option set, in display order. tags fields only. An entry with an id keeps that option (renaming it, and replacing its description if you send one); an entry without one adopts the existing option of the same name, or is added as new — so re-sending a name you already have keeps its id, and retrying is safe. Must list every option the field currently has: omitting one is a 400, not a removal, since removing it would clear it from every media holding it. Delete with DELETE /v1/media-attributes/{id}/options/{option_id}, add with POST /v1/media-attributes/{id}/options. Listing the same id twice is rejected. At most 499 options per field.
  • id (optional, uuid string). Id of an existing option on this field to keep. Omit to add a new option. An id that isn’t an option of this field → 400.
  • name (required, string). The option’s label. Must be unique within the field (case-insensitive).
  • description (optional, string). Replaces the option’s help text. Omit to leave whatever it already has — unlike name, an absent description is not a request to clear it; send "" for that. At most 500 characters.
• allow_create (optional, boolean). Whether new options may be added to this field ad hoc — both while tagging in the app and via POST /v1/media-attributes/{id}/options on the media:write scope alone. When this is false, that call needs spaces:write (plus admin/owner for a connector) instead of being rejected outright. Defaults to false on create, matching the app. tags fields only.
• show_in_library (optional, boolean). Surface this field’s options as clickable suggestions in media library search. tags fields only.
• autofill (optional, object, nullable). AI autofill for this field — an object to configure it, null to turn it off. text and tags fields only (400 on any other type). Enabling it requires a prompt, either in this call or already stored. Turning it on makes the AI write values across the space’s media, so treat it as a change with reach.
  • prompt (optional, string). The instruction the AI follows when filling this field — e.g. “the primary call to action in this ad”. Required: autofill enabled with no instruction never runs, so this API won’t create that state (the app allows it mid-edit). Rich prompts written in the app may @mention other fields; those read back flattened to @Label text, and writing a plain string replaces the rich content. At most 4000 chars.
  • allowed_media_types (optional, array of string, one of statics, videos, nullable). Restrict autofill to these media kinds. null (the default) runs it on everything. Use this rather than wording the prompt to opt out — a column restricted here is never queued for the wrong kind of media in the first place.
  • name_only (optional, boolean). When true the AI sees only the media’s filename — no visual analysis, transcript, or metadata. Much cheaper and faster, and the right choice when the answer is encoded in a naming convention.
• fields (required, array of string, one of id, name, type, multiple, space_id, organization_id, created_at, updated_at, options, autofill). REQUIRED. The properties of each media attribute to return — name only the ones you actually need, since the full objects are wide and every property you ask for is spent out of your context window. id is always included.