ActVox

Move a generated_artifact (an agent-made report, snapshot or skill result) to Trash. Recoverable with restore_artifact and idempotent; its file and saved versions are kept. Permanent deletion is a human action in the app. Page trash uses request_os_action_approval with action: delete_page. Read it first with get_artifact to be sure it is the one you mean.

archive_artifact

Soft-archive a FINISHED report: hidden from lists, tree, search, the public page and the refresh sweep; tombstone readable by id; idempotent.

archive_report

Deprecated alias of trash_upload, kept for one release: moves the file to Trash.

archive_upload

Assign a task row to an agent in the authorized workspace. Pass exactly one of owner (an agent id from find_people_to_mention) or route=most_budget. Routing prefers reported remaining percent, otherwise tokens, skips missing usage and reserve_agent_id, and never returns peer usage. The reviewer defaults to the sponsor; an agent reviewer may accept an intermediate stage, while a person accepts the final result. blocked_by identifies earlier stages whose acceptance unlocks this task. Returns the assignment and its requester or owner role. Returns agent_handoffs_off if workspace handoffs are disabled, and brief_required for a row with no title or body when no instructions or acceptance criteria are given. Reassigning, cancelling or changing blockers is not supported by this hosted tool. Changes to rows, task cells or tree placement can change what is visible through existing public database or page-tree shares.

create_assignment

Read connection diagnostics for the selected workspace: access status, API origin, capability counts, agent-surface versions, and existing standing-page IDs in standingPages (instructions for ACTVOX.md, design for DESIGN.md; null when absent). Does not create or update workspace pages. Use get_instructions or get_design to read an existing standing page.

doctor

Read this connection's mentions and assigned tasks, oldest first, across workspaces where the agent is assignable. Lists other workspaces as assignable: false without polling their tasks. Includes agent notices where the Training center is enabled. The first check-in records the agent's verifiedAt timestamp in each polled assignable workspace; later checks preserve it. Each task's target.status (available, no_access or archived) and brief.empty say whether it can be worked now, and its nextActions offer only what can be done. Does not acknowledge mentions or notices, claim tasks, or complete assignments. limit bounds each list; nextCursor resumes workspaces omitted by the response budget. workspace_id narrows the check to one authorized workspace. An empty result is a successful read: nothing names this agent yet (self names it), and the person Inbox is a different list. Only where the person who connected the agent turned it on, an assignable workspace also carries sponsorMentions: that person's own Needs you items there (each with its type: comment_mention, task_assigned, review_requested, changes_requested or approval_requested), read or unread: the person reading one in the app does not take it off this list. Without sponsor_since it is the newest ones; with it (the nextSince of the previous call, with that workspace_id) only newer ones, oldest first. Never pass the workspace cursor as sponsor_since. It is opt-in and read-only, is not the person Inbox, and is never counted in mentions; where the agent cannot read its page it shows only the location and type (bodyWithheld).

check_inbox

Start work on an acknowledged task, or one sent back with changes_requested (-> claimed). The result carries the fence every heartbeat_assignment, submit_assignment and release_assignment must send. 409 brief_required: nobody has said what the task is yet (ask in its comments); 409 target_unavailable: its row or board is in the Trash; 403 target_unreadable: it is described only by a row you cannot read. Changes to rows, task cells or tree placement can change what is visible through existing public database or page-tree shares.

claim_assignment

Complete a direct upload after POSTing bytes to uploadUrl (pass storage_id), or after sending every piece with upload_chunk (omit storage_id: the server joins the pieces).

complete_upload

Run the memory consolidation pass under one receipt: expire claims past valid_until (→ superseded with an Expired note), flag contradicting active claims on one subject+kind as disputed (they stay recallable), regenerate stale subject summaries; resummarize='all' rebuilds every subject. Result: {expired, disputed, summarized}. Changes to an existing page or generated standing page can be visible through existing public shares and queue link-preview rendering, including fetching referenced remote image URLs. Changed claims can queue embedding synchronization or removal and graph rebuilding; configured embedding/model providers may receive active claim text or remaining graph labels. Consolidation can also invoke an enabled dispute-judge model.

memory_consolidate

Create a content draft ({type, title, body?, status?, schedule?, externalId?}); an existing externalId upserts and may overwrite the fenced item. status "published" is refused: only the publish route sets it. When workspace auto-adaptation is enabled, creating or first filling a draft body can queue AI text adaptation, send draft/business context to the configured text provider, and spend credits. This branch does not generate AI images, video or audio.

create_content

Insert one row ({title?, values?, content?, schemaHash?}); content creates the row's page BODY in the same call. Changes to rows, task cells or tree placement can change what is visible through existing public database or page-tree shares.

create_database_row

Materialize a persisted content or generated-artifact snapshot into an editable Page, replacing an existing Page target only with If-Match; generated HTML uses interactive_html and PDFs/binaries become file blocks. A replace_block over a block that holds a reference to an item hidden from you is refused with 409 content_has_hidden_links. Updating an existing publicly shared page changes its public content and can queue link-preview rendering, including fetching referenced remote image URLs.

materialize_page

Create a new page: payload {kind:'page', title, content?, placement?, externalId?, icon?, coverPreset?}. content is {format:'markdown', body} or {format:'actvox-page-v1', blocks}; there is no top-level markdown or body key. placement nests it: {type:'page', pageId} under a live page, {type:'folder', folderId} in a pages folder, or {type:'root'} (the default). Reusing an externalId is refused and this tool never replaces an existing page. Changes to rows, task cells or tree placement can change what is visible through existing public database or page-tree shares.

create_artifact

Create a typed-schema database ({name, columns?, externalId?, icon?, groupBy?, placement?}); groupBy names a status/select column to group the board by and is never set implicitly. A formula column takes formula: "<expression>" or {expression}. No upsert mode: an existing externalId is a 409, never a silent schema rewrite. Changes to rows, task cells or tree placement can change what is visible through existing public database or page-tree shares.

create_database

Create a folder under a root kind.

create_folder

Create 1-25 dependent Pages, Databases and seed rows atomically: request {steps, summary?}. Every step has a unique key and an op: page.create {title, content?, placement?}, database.create {name, columns?, placement?} or row.create {databaseRef | databaseId + schemaHash, title?, values?, content?}. placement is {type:'root'}, {type:'folder', folderId}, {type:'page', pageId} (a live page) or {type:'page', pageRef} (an earlier page.create key). Invalid cells fail the entire plan and failures roll back. The same operation_id replays the durable receipt of the same request; after a 400 validation_failed, resend the corrected request under the same operation_id. Changes to rows, task cells or tree placement can change what is visible through existing public database or page-tree shares.

create_workspace_subtree

Create a workspace skill from {name, description, body, files?, lane?, tools_required?, triggers?}; retries reuse operation_id.

put_skill

Create a whiteboard ({title?, externalId?, placement?}).

create_whiteboard

Partial-object content patch that may overwrite fields or clear the schedule (title, body, type, status, metadata, groupId, schedule|null); If-Match mandatory. A patch can neither enter nor leave status "published". When workspace auto-adaptation is enabled, creating or first filling a draft body can queue AI text adaptation, send draft/business context to the configured text provider, and spend credits. This branch does not generate AI images, video or audio.

patch_content

Patch a row's page BODY with page operations that may replace text or delete blocks — the page grammar, block ids and errors (a wrong blockId is 404 block_not_found). if_match is the BODY etag from get_database_row_content, NEVER the row etag. A reference to an item hidden from you reads as a "Restricted" placeholder with no id; delete_block of a whole block that holds one is allowed, but any other change that would remove one, or store a placeholder, is refused with 409 content_has_hidden_links. Changes to an existing page or generated standing page can be visible through existing public shares and queue link-preview rendering, including fetching referenced remote image URLs.

patch_database_row_content

Typed schema ops on a database, including destructive remove_column (rename, add_column, update_column, remove_column, reorder_columns, set_view — set_view also carries fullWidth, the Full width toggle — and set_cover {cover: {type: preset|image, value, position?}|null}, the page cover op on a database; null clears it); If-Match mandatory (the database etag or its schemaEtag). dry_run previews retype migrations / orphaned cells without writing. Changing the type of a relation column that links rows hidden from you is refused with 409 column_has_hidden_links. Changes to rows, task cells or tree placement can change what is visible through existing public database or page-tree shares.

patch_database_schema

Rename a saved character and/or replace its whole look ({name?, look?}) with If-Match (its etag). Blocks already made keep the look they were made with.

patch_character

Typed page patch fenced by If-Match; operations may replace the whole body or delete blocks. To rename a page, send {"op":"replace_title","value":"<title>"} (title is also accepted). Block ops address attrs.blockId at any depth (inside columns, toggles, list items, quotes and table cells too); append_blocks takes parentBlockId to append inside a container, and blocks may be markdown, one block, or actvox-page-v1 blocks (markdown, interactive_html, model_3d, image, motion). replace_motion edits a motion block (value.motion merges onto its grammar; read motionBlocks[] first). A wrong blockId is 404 block_not_found listing the page's ids; only 409 artifact_diverged means re-read and retry. replace_text takes targetSpan {blockId, quotedText, charRange?} and value: send charRange {from,to}, or leave it out when quotedText occurs exactly once in that block. A malformed item reports every problem at once with a valid example. set_block_layout sets one block's width/align/height (an interactive HTML block's height is set with replace_interactive_html value.height); set_page_layout {fullWidth} toggles the page's Full width. A reference to an item hidden from you reads as a "Restricted" placeholder with no id; delete_block of a whole block that holds one is allowed, but any other change that would remove one, or store a placeholder, is refused with 409 content_has_hidden_links. Updating an existing publicly shared page changes its public content and can queue link-preview rendering, including fetching referenced remote image URLs.

patch_artifact

Single-op whiteboard patch (patch is a one-item array) that can mark elements deleted or retire prior diagram elements; If-Match requiredness is per-op (rename needs it, upsert_elements refuses it).

patch_whiteboard

Typed row ops that may overwrite or remove values (rename, set_property, unset_property); If-Match on the ROW etag is mandatory. Changes to an existing page or generated standing page can be visible through existing public shares and queue link-preview rendering, including fetching referenced remote image URLs. Adding a person to a task can queue notifications and a Clerk organization-membership lookup when local name resolution misses.

patch_database_row

Rename a file and set its alt text (up to 250 characters), caption (up to 500) and tags (up to 20): an upload handle, or (operator write) a workspace file from the tree or search. A field left out is unchanged; "" or [] clears it. A rename is the file's one name everywhere and keeps its type; alt text is what a page image placed from the file reads when it has none. A file in Trash answers 409 upload_in_trash.

patch_upload

Patch brand DNA and optionally clear or replace brand fields; If-Match protects concurrent edits. Changes to an existing page or generated standing page can be visible through existing public shares and queue link-preview rendering, including fetching referenced remote image URLs.

patch_brand_dna

Patch workspace instructions and optionally replace the full markdown or clear fields; If-Match protects concurrent edits. A change that would remove a reference to an item hidden from you, or store a "Restricted" placeholder, is refused with 409 content_has_hidden_links. Changes to an existing page or generated standing page can be visible through existing public shares and queue link-preview rendering, including fetching referenced remote image URLs.

patch_instructions

Partial-object settings patch ({profile?, agent?}) that can clear fields and replace nested objects; If-Match mandatory.

patch_settings

Partial-object strategy patch that can clear or replace strategy and persona data; If-Match mandatory.

patch_strategy

Whole-table export: format json (row views + schema, formulas and rollups evaluated) ONE PAGE per call — limit 1-500 (default 100) and cursor (the previous page's nextCursor); the envelope carries rowCount (this page), total, nextCursor while more rows follow and truncated (#2289) — or csv (text/csv) or xlsx (a typed workbook; returned as bytes), both whole-table in one call (limit/cursor are a 400 there); view='default' applies the saved view (filters on computed columns included) and keeps its order. Capped at 2000 rows. Too large for one response is 413 export_too_large naming the next call, never a generic 500.

export_database_rows

The people and agents a comment on a page or database row may mention: {people: [{id, name, handle}], agents: [{id, name, handle, runtimeKind, self}], truncated}. agents are the agents you may name — yourself (self: true), agents shared with the workspace and your sponsor's private agents. Filter with query (part of a name or handle). Mention them by writing @handle (or their exact @Display Name) in the body of create_comment or reply_to_comment, or pass people's ids as mentions and agents' ids as agent_mentions; a person whose handle is null is mentioned by id or name only.

find_people_to_mention

Fetch a PUBLIC https file into a workspace upload handle. Choose purpose=file for general supported files, model_3d/model_poster/model_ar for 3D assets, or interactive_html / interactive_data / interactive_asset for an interactive block's .html (htmlUploadId), .json data (dataUploadId) or a file it reads (assetUploadIds). Answers a PENDING handle; poll get_upload until ready. The file is streamed into storage up to its purpose's cap — a general file up to 500 MiB — within the upload's 2 minutes (about 4.5 MB/s for 500 MiB). Hostnames only, never ActVox/Convex origins.

upload_from_url

Bulk insert up to 1000 rows in one call ({rows:[{title?, values, content?}]} or {csv}, mode strict|lenient); typed validation per row, per-row report on the receipt. Changes to rows, task cells or tree placement can change what is visible through existing public database or page-tree shares.

import_database_rows

Submit an invite for a person to join the ORGANIZATION as org:member (not a page share, not a page invite). Needs workspace:operator:members. This only SUBMITS: a person sees the email domain and the role and approves in the app; nothing is sent until then, and a rejection sends nothing. owner, admin and org:admin are refused. Answers {approvalId, status: pending}; retries reuse operation_id. A workspace that belongs to no organization answers org_required.

invite_organization_member

Analysis report summaries, newest first (archived=true lists tombstones).

list_reports

List comment threads on a page (page_id) or a database row (database_id + row_id), oldest first, with replies, resolution status, inline anchors and person or agent authors. mine identifies comments written by this connection's agent. status is open, resolved or all (default all). Returns at most limit threads (default 20); while nextCursor is present, pass it as cursor to read the next threads. counts are the totals of every thread, not of the page. reply_limit (1-100, default 1) pages replies oldest first; replyTotal is the total replies. Pass a thread's repliesNextCursor as reply_cursor with the same thread cursor to continue only that thread. REST without reply_limit returns every reply.

list_comments

Content items (posts, articles) workspace-wide with calendar placement.

list_content

Rows of one database (formulas and rollups evaluated), with server-side filters/sorts/aggregate (JSON text in the set_view shapes) or view='default'. Hosted MCP defaults to 20 rows when limit is omitted; an explicit limit is honored. Filters are JSON [{propertyId, op, value?}]; use ~title for the row title, and contains is a case-insensitive substring. Filters, sorts and aggregates run over evaluated cells: a rollup or formula is filtered, sorted and summed by its real value; a column that cannot be evaluated is a 400 naming it. aggregate.groupBy returns aggregate.groups (a pivot in one call). Newest-created cursor paging (a row edited mid-scan is never skipped), or offset paging when sorts are given.

list_database_rows

Knowledge sources with status and counts.

list_knowledge_sources