Board, card and file tools

For: developers connecting an HTTP or MCP client. Start with Agent API and AI clients.

AI is optional. You confirm invoice issuance in Pepper.

Boards and cards

The HTTP and MCP tools use the delegated person’s current Use boards permission and board membership. Private boards stay absent for installation admins until they explicitly recover access in the app. Linked record details require their own access. Read tools need boards:read; preparation needs boards:prepare.

MCP tool	HTTP path after `/api/v1/`	Result
`boards_list`	`GET boards`	Permitted boards, 25 per page by default; send `cursor` until `next_cursor` is null
`boards_get`	`GET boards/{id}`	Board, lists and the first 40 cards per list
`cards_list`	`GET board-lists/{id}/cards`	The cards of one list; send `cursor` until `next_cursor` is null
`cards_get`	`GET board-cards/{id}`	Card, current version, fields and permitted source details
`boards_prepare`	`POST boards/prepare`	Editable browser review link; writes no board or card

For boards_list, search filters titles and archived=true includes archived boards. boards_get returns later-page cursors in more, keyed by list ID.

boards_prepare requires operation, payload and idempotency_key:

create_board: payload title and template (ideas, project, kanban, weekly, announcements, retrospective or client).
create: board_id, and payload list_id with title or source: {type, id}. Optional description and due_at.
update: card_id, and payload version with any of title, description, starts_at or due_at.
move: card_id, destination board_id, and payload version and list_id.

Dates use YYYY-MM-DD; update dates can be null. Read the current version before preparing an update or move. Open review_url, review the editable values and save in the app. Observers cannot prepare edits. A stale version returns 409. There is no agent execution endpoint for these proposals.

Change boards, lists and cards

These tools make the changes a board member makes on the board, as that person. Board roles apply: an observer cannot change a card, and board settings need board admin. Each write needs an idempotency key and appears in the card or board activity as done by an AI connection for that person.

MCP tool	HTTP after `/api/v1/`	Scope	What it does
`cards_mine`	`GET cards/mine`	`boards:read`	Read the person's open cards across boards, as My work shows them: assigned (default), due today, overdue or watched.
`boards_backlinks`	`GET boards/backlinks`	`boards:read`	List the cards that link a record, such as a customer, deal or task, on boards the person can open.
`boards_source_url`	`GET boards/source`	`boards:read`	Read which record a Pepper address points to, as the card source field resolves it, if the person may open it.
`boards_directory`	`GET boards/directory`	`boards:read`	List every board of the business with its visibility, members and admins, for a person who manages boards. Titles only; no cards.
`boards_update`	`POST boards/{id}/settings`	`boards:prepare`	Change a board's title or colour, or archive and restore it, as a board admin. For changes to who can open the board, use the documented approval workflow.
`boards_label`	`POST boards/{id}/labels`	`boards:prepare`	Add a label to a board, or rename and recolour one.
`boards_create`	`POST boards`	`boards:prepare`	Create a private board from a template, with the template's lists and no sample cards, and optionally link it to a project.
`boards_copy`	`POST boards/{id}/copy`	`boards:prepare`	Copy a board's lists, labels and open cards into a new private board.
`boards_remove_examples`	`POST boards/{id}/examples/remove`	`boards:prepare`	Remove the sample cards a new board started with. Cards people added stay.
`cards_update`	`POST board-cards/{id}`	`boards:prepare`	Change a card at its current version: title, description, dates, members, labels, checklists and cover, mark it complete or reopen it, or archive and restore it. Send only the fields to change. A stale version returns 409. The answer carries undo_id for cards_undo.
`cards_participate`	`POST board-cards/{id}/participate`	`boards:prepare`	Join or leave a card, watch it, or add or remove a reaction, for the person themselves.
`cards_copy`	`POST board-cards/{id}/copy`	`boards:prepare`	Copy a card into a list of a board the person may change. Copying to a board with guests needs confirm_guests.
`cards_undo`	`POST board-undo/{id}`	`boards:prepare`	Undo a card change within 12 seconds, as the undo button does, while nobody changed the card since. cards_update returns the undo_id.
`lists_create`	`POST boards/{id}/lists`	`boards:prepare`	Add a list to a board, optionally as the done list or with a work-in-progress limit.
`lists_update`	`POST board-lists/{id}`	`boards:prepare`	Rename, reorder, limit, mark as done, or archive and restore a list at its current version.
`lists_copy`	`POST board-lists/{id}/copy`	`boards:prepare`	Copy a list with its open cards on the same board.
`lists_move_all`	`POST board-lists/{id}/move-all`	`boards:prepare`	Move every open card of a list to another list.
`tasks_from_card`	`POST cards/{id}/task`	`engagements:prepare`	Turn a board card into a task, optionally in a project, linked back to the card. The card stays on its board.
`boards_upload_prepare`	`POST boards/uploads`	`boards:prepare`	Start an upload for a card file, a board background image or a Trello export, up to 10 MB. Send content_base64, or size and PUT the bytes to upload_url with the same bearer token within 30 minutes.
`cards_attach_files`	`POST board-cards/{id}/files`	`boards:prepare`	Attach uploads to a card as private files.
`cards_drop_file`	`POST boards/{id}/drop`	`boards:prepare`	Add a card for an uploaded file to a list, as dropping a file on the board does.
`boards_background`	`POST boards/{id}/background`	`boards:prepare`	Set a board's background from a JPEG, PNG or WebP upload of at most 8192 by 8192 pixels.
`boards_import_preview`	`POST boards/import/preview`	`boards:prepare`	Check a Trello JSON export without writing: the title, counts, warnings and the people it names, with the token for boards_import. The upload stays usable for the import.
`boards_import`	`POST boards/import`	`boards:prepare`	Import the previewed Trello export as a new private board. The same file imports once.

A change to a board, list or card needs its current version; a stale version returns 409 with the current record. Archiving or moving cards returns an undo_id. Send it to cards_undo within 12 seconds to reverse that change, as the Undo button does. Card files, a board background and a Trello export arrive through an upload: see Upload and download files.

See Boards and cards.

Files

The tools use the delegated person's current file permissions and record access. A file attached only to records outside that access is absent. Read tools need files:read and See files; preparation needs files:prepare and Upload and change files.

MCP tool	HTTP path after `/api/v1/`	Result
`files_list`	`GET files`	A folder's subfolders, then its files, 25 files per page by default. Pass `folder_id` for a folder, `search` for names in every folder, and `cursor` until `next_cursor` is null
`files_get`	`GET files/{id}`	The file's folder, current version, version list and the records it is attached to within access. Returns no bytes
`files_read_text`	`GET files/{id}/text`	The text of a plain text, CSV, Markdown, HTML, CSS, JavaScript, JSON, XML or YAML file up to 1 MB, and its version ID. Pass `version_id` for an earlier version. Reading counts as a download
`files_prepare_text_version`	`POST files/{id}/text/prepare`	A review link for new text; writes no version

files_prepare_text_version requires base_version_id (from files_read_text), the complete new content (UTF-8, up to 1 MB) and idempotency_key. The same checks as a save in the editor apply, including valid JSON and XML. If a newer version exists, the call returns 409 with who saved it. Open review_url: the person sees the proposed text in the editor, compares it and saves it as a new version, or closes it without saving. There is no agent execution endpoint for these proposals.

See Edit text files.

Upload, change and download files

These tools make the changes a person makes in Files: upload, add a version, rename, move, delete and restore, attach to and detach from records, and folders. Uploads and downloads use single-use transfers: see Upload and download files. Each write needs an idempotency key and appears in the file's activity as done by an AI connection for that person.

MCP tool	HTTP after `/api/v1/`	Scope	What it does
`files_download`	`GET files/{id}/download`	`files:read`	Get a single-use download link for a file the person may open, valid for 5 minutes. Fetch download_url without a token, or read resource_uri through MCP. The bytes are checked against their hash; a changed file is refused. The download is recorded.
`files_thumbnail`	`GET files/{id}/thumbnail`	`files:read`	Get a single-use link to a small preview image of a JPEG, PNG, WebP or GIF file the person may open. Other types return 404.
`files_share_preview`	`GET files/shares/preview`	`files:read`	Read what a share link shows: the file name, type and size, and whether the link needs a password or expires. Only links the person may open. The view is recorded like a visitor opening the page.
`files_proposal`	`GET files/{id}/proposal`	`files:read`	Read a text proposal this person prepared through files_prepare_text_version and has not saved: the base version and the proposed text.
`files_selection`	`POST files/selection`	`files:prepare`	Move, delete or restore up to 500 files and folders at once. Each item is checked on its own; the answer counts what was done and skipped and names each refusal.
`files_upload_prepare`	`POST files/uploads`	`files:prepare`	Start an upload for Files. Send the bytes inline as content_base64 (up to 8 MB), or send size and then PUT the raw bytes to the returned upload_url with the same bearer token (once, within 30 minutes). Then pass upload_id to files_upload or files_add_version. Type, size and the storage quota are checked when the file is created; SVG and scripts are stored as text and never shown inline.
`files_upload`	`POST files`	`files:prepare`	Create a file from an upload, optionally in a folder and attached to a record the person may change. Returns the file as files_get does.
`files_add_version`	`POST files/{id}/versions`	`files:prepare`	Add a new current version to a file from an upload. Earlier versions stay.
`files_rename`	`POST files/{id}/name`	`files:prepare`	Rename a file. The extension stays with the stored type.
`files_move`	`POST files/{id}/folder`	`files:prepare`	Move a file to another folder.
`files_delete`	`POST files/{id}/delete`	`files:prepare`	Move a file to the deleted files. Its versions and attachments stay, and files_restore brings it back.
`files_restore`	`POST files/{id}/restore`	`files:prepare`	Restore a deleted file to its folder, or to the top level when that folder is deleted.
`files_restore_version`	`POST files/{id}/versions/restore`	`files:prepare`	Make an earlier version current again, as a new version. Nothing is removed.
`files_attach`	`POST files/{id}/attachments`	`files:prepare`	Attach a file to a record the person may change, such as a customer, deal, task or card.
`files_detach`	`POST files/{id}/attachments/remove`	`files:prepare`	Remove one attachment of a file from a record. The file stays in Files.
`files_revoke_share`	`POST files/{id}/shares/revoke`	`files:prepare`	Turn off one share link of a file. The link stops working at once.
`folders_create`	`POST folders`	`files:prepare`	Create a folder.
`folders_rename`	`POST folders/{id}/name`	`files:prepare`	Rename a folder.
`folders_move`	`POST folders/{id}/parent`	`files:prepare`	Move a folder into another folder, or to the top level with null. A folder cannot move into itself.
`folders_delete`	`POST folders/{id}/delete`	`files:prepare`	Delete a folder with everything in it. folders_restore brings it back.
`folders_restore`	`POST folders/{id}/restore`	`files:prepare`	Restore a deleted folder and what was deleted with it.

Deleted files and folders go to the bin, where files_restore and folders_restore bring them back. An AI client can preview and revoke a share link. It can create one with files_share only after the delegated person approves it; a password is set in Pepper only. See Approve sensitive steps. A download link opens once, within five minutes, and Pepper checks the person's file access again when it opens.