Let an agent run Archestra for you: ask it to create an agent, install an MCP server, or build an app, and it calls these tools. The Archestra MCP Server is built into every deployment and acts as the person using the agent, with their permissions. Every tool name starts with archestra__. This page lists tools by their short name.
Give an Agent These Tools
Pick these tools like any other MCP server's tools, on an agent's Tools, Skills & Knowledge tab or a gateway's Tools & Knowledge settings:
Manual: assign the tools you want.
All: the agent gets every tool the person can use, but built-in tools start out excluded. Remove a tool from the exclusions to allow it.
Each tool needs the permission in the last column of its table. A person sees only the tools their permissions allow: without knowledgeSource:create, for example, create_knowledge_base is hidden. A tool marked † has an extra condition, described in its entry. Guardrails policies apply on top of these permissions.
Tools Reference
Identity
Tool
Description
Permission
whoami
Returns the name and ID of the current agent.
None
whoami
Required RBAC permission: None
This tool takes no arguments.
Output
Field
Type
Required
Description
agentId
string
Yes
The ID of the current agent.
agentName
string
Yes
The display name of the current agent.
Chat
Tool
Description
Permission
todo_write
Write todos to the current conversation.
None
ask_user
Ask the user to pick from a short list of options.
None
todo_write
Required RBAC permission: None
Input
Parameter
Type
Required
Description
todos
object[]
Yes
Array of todo items to write to the conversation.
todos[].id
integer
Yes
Unique identifier for the todo item.
todos[].content
string
Yes
The content or description of the todo item.
todos[].status
"pending" | "in_progress" | "completed"
Yes
The current status of the todo item.
Output
Field
Type
Required
Description
success
true
Yes
Whether the write succeeded.
todoCount
integer
Yes
How many todo items were written.
ask_user
Required RBAC permission: None
Input
Parameter
Type
Required
Description
question
string
Yes
The question shown above the options, as plain text. Put links and commands in your reply text.
header
string
No
A very short label shown as the question's tab, e.g. 'Visibility'.
options
object[]
Yes
The options the user can pick. Labels must be unique.
options[].label
string
Yes
The option shown to the user.
options[].description
string
No
Optional extra detail shown next to the option.
allowMultiple
boolean
No
When true, the user may select more than one option. Defaults to false (exactly one).
remedy_offer_ids
string[]
No
Exact offer IDs from the blocked ruling that this question asks the user to decide: a review execute_remedy_plan requires, or a plan that would prevent what the user asked for. Say in the question what it would prevent. Omit for ordinary questions.
Output
Field
Type
Required
Description
action
"accept" | "decline" | "cancel"
Yes
Whether the choice form was submitted, declined, or canceled.
selected
string[]
Yes
The labels the user selected. Empty when declined or canceled.
text
string
No
What the user typed instead of picking an option.
timedOut
boolean
No
True when the question expired without an answer.
Tool Discovery
Tool
Description
Permission
search_tools
Search the tools available to this agent and to you on demand.
None
run_tool
Dispatch to any tool available to this agent, including built-in platform tools, agent delegation tools ('agent-'), or third-party MCP tools exposed through the MCP Gateway (e.g.
None
search_tools
Required RBAC permission: None
Input
Parameter
Type
Required
Description
query
string
Yes
Keywords for the capability you need — combine the action (verb + object) with the server/product name when you know it, e.g. 'github search repositories' or 'slack send message'. Avoid querying with a bare product/server name on its own. Results are keyword-ranked across tool names, descriptions, and argument names/descriptions. If nothing fits, reformulate with different keywords and search again rather than settling for a poor match.
limit
integer
No
Maximum number of matching tools to return, at most 20. A larger value returns 20.
mode
"keyword" | "regex"
No
Search mode. 'keyword' (default) keyword-ranks the query across tool fields. 'regex' treats query as a case-insensitive regular expression matched against tool names, titles, and descriptions — use it when you know a naming pattern, e.g. '^github__' or 'search|find'.
Output
Field
Type
Required
Description
total
integer
Yes
Number of returned tools.
matchCount
integer
Yes
Total tools matching the query before the limit was applied (>= total).
truncated
boolean
Yes
True when matchCount exceeds the returned tools (results cut by limit).
hint
string | null
Yes
Actionable guidance when results were truncated or empty (an empty result also names which query terms matched no tool text).
tools
object[]
Yes
tools[].toolName
string
Yes
Exact tool name to pass to run_tool.
tools[].description
string | null
Yes
Short tool description, if available.
tools[].source
"archestra" | "mcp" | "agent_delegation"
Yes
Where the tool comes from.
tools[].server
string | null
Yes
MCP server prefix for third-party MCP tools when available.
tools[].available
boolean
Yes
False when the tool's MCP connection is not installed; it stays discoverable but cannot run until reconnected.
tools[].unavailableReason
string | null
Yes
Compact reason and recovery action when available is false; null otherwise.
tools[].params
string
Yes
Compact one-line input signature — a summary, not the full schema. Parameters are joined by '; ', each rendered as name<!|?>:<type> where ! marks required and ? optional. Object parameters are expanded up to two levels as {child<!|?>:type{grandchild<!|?>:type}, …}, enums as enum(<json-values>), and a trailing — description is added when available. A trailing … on a type marks an object whose content is not fully shown (freeform or more deeply nested) — consult the task instructions or the full schema for its shape. Empty string when the tool takes no input. Pass matching values inside tool_args when calling run_tool; if a call is rejected as invalid, the error describes the expected input (for third-party tools, the full input schema).
run_tool
Required RBAC permission: None
Input
Parameter
Type
Required
Description
tool_name
string
Yes
Name of the tool to invoke. Use the exact name as it appears in the tools list, e.g. 'archestra__whoami', 'context7__resolve-library-id', or an agent delegation name 'agent-'.
tool_args
object
No
Arguments object for the target tool; must match its input schema.
Skills
Tool
Description
Permission
list_skills
List the Agent Skills available in this organization — one line per skill (name and description).
Optional. Omit (or pass an empty string) to load the skill's instructions and bundled-file list. Pass a resource path from that list (e.g. references/REFERENCE.md) to read one bundled file instead.
A complete SKILL.md manifest: a YAML frontmatter block with name and description (and optional license, compatibility, allowed-tools, agent, templated, metadata), followed by the Markdown instruction body. Set templated: true to render the body through Handlebars (e.g. {{user.name}}) at activation. allowed-tools is a space-separated list of tools the skill is pre-approved to use. agent names an agent the skill runs in — when set, activating the skill delegates it to that agent instead of loading the instructions into the caller's context.
files
object[]
No
Optional bundled resource files. Each is { path, content } with text content; the path prefix classifies the file — references/ for docs, scripts/ for code, assets/ for other files.
files[].path
string
Yes
Resource path, e.g. references/API.md or scripts/run.py
files[].content
string
Yes
Text content of the file
files[].encoding
"utf8" | "base64"
No
update_skill
Required RBAC permission: update on the skill (granted per item)
Input
Parameter
Type
Required
Description
name
string
Yes
The current name of the skill to update, as named by list_skills.
content
string
Yes
A complete SKILL.md manifest: a YAML frontmatter block with name and description (and optional license, compatibility, allowed-tools, agent, templated, metadata), followed by the Markdown instruction body. Set templated: true to render the body through Handlebars (e.g. {{user.name}}) at activation. allowed-tools is a space-separated list of tools the skill is pre-approved to use. agent names an agent the skill runs in — when set, activating the skill delegates it to that agent instead of loading the instructions into the caller's context.
files
object[]
No
Optional. WHEN PROVIDED, REPLACES THE SKILL'S ENTIRE bundled file set. Omit it to leave the existing resource files untouched. There is no per-file patch: to change one file you must resend all of them — read the current files back first with load_skill (with and without a path).
files[].path
string
Yes
Resource path, e.g. references/API.md or scripts/run.py
files[].content
string
Yes
Text content of the file
files[].encoding
"utf8" | "base64"
No
edit_skill
Required RBAC permission: update on the skill (granted per item)
Input
Parameter
Type
Required
Description
name
string
Yes
The current name of the skill to edit, as named by list_skills.
baseVersion
integer
Yes
The version the edit is based on — the version shown on the <skill_content>/<skill_file> frame you loaded with load_skill. The edit is rejected if the skill's head has moved past it.
path
string
No
Omit (or pass an empty string) to edit the SKILL.md body; pass a bundled file path (from the <skill_resources> list) to edit that file instead. Only text (utf8) files are editable — binary assets are not.
edits
object[]
No
str_replace edits applied in order to the target; the whole edit is atomic (any failure leaves the skill unchanged). This is the way to change a large SKILL.md without resending it all. Pass either edits or replacementContent, never both.
edits[].old_str
string
Yes
Exact text to replace; must occur exactly once in the target (add surrounding context to disambiguate).
edits[].new_str
string
Yes
Replacement text (may be empty to delete).
replacementContent
string
No
The complete new content of the target, replacing it outright with no old_str matching — use it for a small file or a full rewrite. Prefer edits for the SKILL.md body so you don't resend the whole thing. Pass either edits or replacementContent, never both.
Files
Tool
Description
Permission
search_files
List or search the conversation's persistent files.
Exchange a file between this chat and the app the user has open: copy a chat/project file or a chat attachment INTO the open app's file store (so the app can load it), or copy a file OUT of the app...
Case-insensitive substring matched against filenames only. Omit it (or pass empty) to list the files (the first 200).
scope
"chat" | "app"
No
"chat" (default) = this chat's files; "app" = the files of the app the user has open, which is how you find what the app has produced before copying one out with copy_file.
project_id
string
No
Use this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app".
Output
Field
Type
Required
Description
files
object[]
Yes
files[].id
string | null
Yes
Row id (UUID), or null for a hand-placed file with no row.
files[].ref
string
Yes
Stable handle for this file — pass it to read_file / upload_file / edit_file / delete_file. Works for hand-placed files too (where id is null).
Id or ref of the file to read — the id or ref from search_files, or a fileId from save_file.
filename
string
No
Filename to read instead of id; rejected as ambiguous if more than one file shares the name.
offset
integer
No
1-based line number to start reading from. Defaults to 1.
limit
integer
No
Maximum number of lines to read. Defaults to 2000.
project_id
string
No
Use this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app".
Output
Field
Type
Required
Description
kind
"text" | "image"
Yes
text = numbered lines in the text content; image = the file is returned as an inline image block.
fileId
string | null
Yes
The file's id, or null for a hand-placed file with no row.
filename
string
Yes
mimeType
string
Yes
sizeBytes
number
Yes
totalLines
number
No
startLine
number
No
returnedLines
number
No
truncated
boolean
No
True when more lines follow the returned window (raise offset to continue).
content
string
No
The returned window's text, WITHOUT the line numbers — the file's own bytes. Present for text reads so a structured consumer (an app via archestra.tools.call, which unwraps to structuredContent and never sees the text block) gets usable content instead of only metadata. The numbered rendering stays in the text output, where line numbers are what makes edit_file addressable.
Plain filename including extension (e.g. "joke.md"). No paths.
content
string
No
UTF-8 text content of the file.
contentBase64
string
No
Base64-encoded binary content.
mimeType
string
No
Optional MIME type. Sniffed from the bytes when omitted.
overwrite
boolean
No
Replace an existing file of the same name in place, keeping its id. Default false errors if the name is already taken.
project_id
string
No
Use this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app".
Output
Field
Type
Required
Description
fileId
string
Yes
filename
string
Yes
projectName
string | null
Yes
Owning project when saved into a project; null otherwise.
mimeType
string
Yes
sizeBytes
number
Yes
overwritten
boolean
Yes
True when an existing same-named file was replaced in place.
Id of the file to edit — the id or ref from search_files, or a fileId from save_file.
filename
string
No
Filename to edit instead of id; rejected as ambiguous if more than one file shares the name.
old_string
string
Yes
The exact text to replace; must match the file's current content (read it first with read_file). Include enough surrounding context to be unique unless replace_all is set.
new_string
string
Yes
The text to insert in place of old_string.
replace_all
boolean
No
Replace every occurrence of old_string. Default false replaces a single occurrence and errors if old_string is not unique.
project_id
string
No
Use this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app".
Id of the file to delete — the id or ref from search_files, or a fileId from save_file.
filename
string
No
Filename to delete instead of id; rejected as ambiguous if more than one file shares the name.
project_id
string
No
Use this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app".
Output
Field
Type
Required
Description
fileId
string
Yes
The deleted file's id, or its ref for a rowless file.
Where the bytes come from: {"type":"chat_file","id"|"filename"} | {"type":"chat_attachment","attachmentId"|"filename"} | {"type":"app_file","id"|"filename"}.
from.type
"chat_file" | "chat_attachment" | "app_file"
Yes
from.id
string
No
When type="chat_file": File id from search_files. When type="app_file": File id in the app's store.
from.filename
string
No
When type="chat_file": Filename instead of id; ambiguous names rejected. When type="chat_attachment": Original filename of an attachment in this conversation (when you have no id). If the same name was attached more than once, the newest one wins. When type="app_file": Filename instead of id.
from.attachmentId
string
No
Id of an attachment uploaded to THIS conversation.
to
object
Yes
Where the copy lands.
to.scope
"chat" | "app"
Yes
"app" = the open app's per-viewer store; "chat" = this chat's files (the project's files when this chat belongs to a project).
to.filename
string
No
Destination filename; defaults to the source's name. Plain filename, no paths.
to.overwrite
boolean
No
Replace an existing same-named destination file in place. Default false: a duplicate name is an error.
Shell command to execute (bash). Runs in the sandbox's working directory (or cwd when provided). Returns text output only — use download_file for generated files.
cwd
string
No
Optional absolute path inside the container. Defaults to the sandbox's working directory (/home/sandbox).
timeoutSeconds
integer
No
Optional wall-clock limit in seconds, capped at the deployment maximum.
target
object
No
Which sandbox to use. Omit (or leave empty) for the conversation's default sandbox (created on first use). Pass { "fresh": true } for a new isolated sandbox, or { "id": "<uuid>" } to target a specific one.
target.fresh
boolean
No
Set true for a brand-new isolated sandbox; its id is returned.
target.id
string
No
An existing sandbox id (UUID) returned by an earlier call.
Output
Field
Type
Required
Description
commandId
string
Yes
sandboxId
string
Yes
command
string
Yes
cwd
string | null
Yes
stdout
string
Yes
stderr
string
Yes
exitCode
number
Yes
durationMs
number
Yes
timedOut
boolean
Yes
truncated
boolean
Yes
binaryStripped
boolean
Yes
True when NUL bytes were stripped from stdout/stderr before storage.
stagingNotices
string[]
Yes
Notices about chat attachments that could not be auto-staged (e.g. too large). Empty when all attachments are available in the sandbox.
Path to the file inside the container — absolute, or relative to the sandbox's working directory.
mimeType
string
No
Optional MIME type recorded with the file. Sniffed from the bytes when omitted.
overwrite
boolean
No
Replace an existing same-named persistent file in place, keeping its id. Default false errors if the name is already taken.
target
object
No
Which sandbox to use. Omit (or leave empty) for the conversation's default sandbox (created on first use). Pass { "fresh": true } for a new isolated sandbox, or { "id": "<uuid>" } to target a specific one.
target.fresh
boolean
No
Set true for a brand-new isolated sandbox; its id is returned.
target.id
string
No
An existing sandbox id (UUID) returned by an earlier call.
Output
Field
Type
Required
Description
fileId
string
Yes
sandboxId
string
Yes
path
string
Yes
mimeType
string
Yes
sizeBytes
number
Yes
stagingNotices
string[]
Yes
Notices about chat attachments that could not be auto-staged (e.g. too large). Empty when all attachments are available in the sandbox.
overwritten
boolean
Yes
True when an existing same-named file was replaced in place.
Destination path inside the container — absolute under /skills or /home/sandbox, or relative to the sandbox's working directory.
source
object
Yes
Where the file bytes come from. One of four shapes, each tagged by a type: a chat attachment ({"type":"chat_attachment","attachmentId"|"filename":...}), inline base64 ({"type":"base64","dataBase64":...}), inline text ({"type":"text","text":"print(1)"}), or a file from the user's persistent files ({"type":"my_file","filename":...}, found via search_files). Use this to place input bytes; to create a file the sandbox will then run or read, write it with run_command instead.
source.type
"chat_attachment" | "base64" | "text" | "my_file"
Yes
source.attachmentId
string
No
Id of an attachment in the current conversation. The bytes are copied directly and never enter your context.
source.filename
string
No
When type="chat_attachment": Original filename of an attachment in this conversation (when you have no id). If the same name was attached more than once, the newest one wins. When type="my_file": Exact filename of a persistent file (when you have no id).
source.dataBase64
string
When type="base64"
Base64-encoded file bytes.
source.mimeType
string
No
source.originalName
string
No
source.text
string
When type="text"
UTF-8 text content of the file.
source.id
string
No
Id or ref of a persistent file, as returned by search_files (id for stored files, ref for hand-placed ones).
target
object
No
Which sandbox to use. Omit (or leave empty) for the conversation's default sandbox (created on first use). Pass { "fresh": true } for a new isolated sandbox, or { "id": "<uuid>" } to target a specific one.
target.fresh
boolean
No
Set true for a brand-new isolated sandbox; its id is returned.
target.id
string
No
An existing sandbox id (UUID) returned by an earlier call.
Output
Field
Type
Required
Description
uploadId
string
Yes
sandboxId
string
Yes
path
string
Yes
mimeType
string
Yes
sizeBytes
number
Yes
Apps
Tool
Description
Permission
scaffold_app
Create a new interactive app (dashboard, form, tracker, game, or any custom UI) seeded from the default starter template.
Return an app's stored HTML (pre-injection — exactly what was saved, without the platform SDK or base stylesheet) plus its version, byte size, name, and scope.
Restore a historical app version directly on the server as a new head version.
update on the app (granted per item)
edit_app
The single path for any change to an app's HTML: pass edits for targeted str_replace changes, imageReplacements to replace embedded images from chat attachments without sending base64 through the m...
update on the app (granted per item)
set_app_tools
Replace an existing app's assigned upstream tools with exactly the set you pass (the full desired list; [] clears all).
update on the app (granted per item)
set_app_labels
Replace an app's labels with exactly the set you pass ([] clears them).
update on the app (granted per item)
set_app_lock
Lock or unlock an app.
update on the app (granted per item)
validate_app
The pre-publish gate for an app's head version: static structural checks (findings, each carrying its own specific message) plus the most recent live-render diagnostics (live), with ok true w...
Share an app by granting read and use access to specific teams (scope: team, teams: names or IDs) or the whole organization (scope: org).
manage-permissions on the app (granted per item)
preview_app_tool
Run one of an app's assigned MCP tools server-side, exactly as the rendered app would (as you, the viewing user, with your MCP credentials), and return its real output.
update on the app (granted per item)
get_app_diagnostics
Check how the app's current version rendered for you.
Optional display icon for the app, as a single emoji character (e.g. "📊") chosen to suit what the app does. Omitted leaves the app with the generic app glyph.
labels
object[]
No
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
tools
string[]
No
Upstream MCP tool names to assign to the new app (e.g. from search_tools), callable from its HTML via archestra.tools.call with the viewing user's credentials. Omitted leaves the app with no assigned tools.
project_id
string
No
Link the new app into this project (from list_projects) so it is listed with the project's files. You need access to the project. Omitted creates a standalone app.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
description
string | null
Yes
scope
"personal" | "team" | "org"
Yes
latestVersion
number
Yes
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
tools
string[]
No
The app's assigned tool names after this call (present when the tools param was given).
status
"ok" | "partial"
No
Absent or "ok" on full success. "partial" means the app was created (see id) but assigning its tools failed — the app exists; assign them with set_app_tools rather than re-scaffolding.
refine_app
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id to refine.
questions
object[]
No
Up to 3 clarifying questions to ask the user before consolidating the spec.
questions[].id
string
Yes
Stable key the answer is returned under.
questions[].prompt
string
Yes
The question shown to the user.
questions[].options
string[]
No
When present, the question is single-select over these plain-string option labels, e.g. ["Light", "Dark"] — never {label, value} objects; otherwise it is free-text.
spec
object
No
The consolidated product requirements to persist on the app (features/data/ui/tools — no implementation stack).
spec.summary
string
Yes
One-line summary of what the app is for.
spec.features
string[]
Yes
Concrete capabilities the app should provide.
spec.data
string | null
No
What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.
spec.ui
string | null
No
UI / style direction as a free-form prose string, not a structured object.
spec.tools
string[]
Yes
Full names of the MCP tools the app calls through window.archestra.
Output
Field
Type
Required
Description
id
string
Yes
spec
object
Yes
The persisted spec when one was given, else the base spec seeded for the model.
spec.summary
string
Yes
One-line summary of what the app is for.
spec.features
string[]
Yes
Concrete capabilities the app should provide.
spec.data
string | null
No
What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.
spec.ui
string | null
No
UI / style direction as a free-form prose string, not a structured object.
spec.tools
string[]
Yes
Full names of the MCP tools the app calls through window.archestra.
capability
object
Yes
capability.tools
object[]
Yes
capability.tools[].name
string
Yes
capability.tools[].description
string
Yes
capability.sdkSummary
string
Yes
answers
object
No
The user's answers to the clarifying questions, if any.
persisted
boolean
Yes
Whether a spec was persisted on the app head by this call.
Filter by name. Each whitespace-separated word must appear in the name or description, in any order — so a remembered name matches even when its word order or punctuation differs from how the app was saved.
labels
object[]
No
Filter by labels. AND across keys, OR within the values given for the same key.
labels[].key
string
Yes
labels[].value
string
Yes
limit
integer
No
access
string[]
No
Only return items the caller reaches in one of these ways: mine (created by the caller), shared (shared with the caller or one of their teams), org (shared with the whole organization), others (not shared with the caller; visible only through admin access). Omit for everything the caller can read. Use ["mine"] for "my apps".
shared_with
string[]
No
Only return items whose own permissions grant read to one of these subjects: org (the whole organization), role:, team:, user:, serviceAccount:. Omit for no filtering.
owner_ids
string[]
No
Only return items created by one of these user IDs. Omit for no filtering.
Output
Field
Type
Required
Description
apps
object[]
Yes
apps[].id
string
Yes
apps[].name
string
Yes
apps[].description
string | null
Yes
apps[].scope
"personal" | "team" | "org"
Yes
apps[].latestVersion
number
Yes
apps[].labels
object[]
Yes
Key-value labels for organization/categorization.
apps[].labels[].key
string
Yes
The label key.
apps[].labels[].value
string
Yes
The label value.
apps[].warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
Specific version to read; defaults to the current head.
offset
integer
No
Start of the read window as a 0-based character offset (a JavaScript string index / UTF-16 code unit) into the stored HTML — character-based, not line-based, since minified HTML can be one enormous line. Defaults to 0. An offset past the end returns an empty window, not an error. A window never splits a character in half: its edges shift by one unit when they would.
limit
integer
No
Maximum number of characters to return, starting at offset. Omitted reads to the end of the document; 0 returns no content, just the size metadata.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
scope
"personal" | "team" | "org"
Yes
version
number
Yes
byteSize
number
Yes
UTF-8 byte size of the full stored HTML (never the window's).
totalChars
number
Yes
Total character length of the full stored HTML.
offset
number
Yes
Effective 0-based character offset of the returned window (0 for a full read; clamped to the end when past it).
hasMore
boolean
Yes
True when the document continues past the returned window.
html
string
Yes
The stored HTML, pre-injection (no SDK/base CSS) — the requested character window when offset/limit was passed.
restore_app_version
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
version
integer
Yes
The historical version to restore.
baseVersion
integer
Yes
The current head version. This prevents overwriting a newer edit that landed after the rollback was requested.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
description
string | null
Yes
scope
"personal" | "team" | "org"
Yes
latestVersion
number
Yes
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
edit_app
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
baseVersion
integer
Yes
The version this edit is based on — the one named by read_app or the latest scaffold_app/edit_app result. Always report the version you actually built the edit from. When the head has moved past it (another conversation edited the app), your edit is treated as a delta from that base and merged with the newer changes; if the regions overlap, the call fails with the head's conflicting content to incorporate.
edits
object[]
No
str_replace edits applied in order to the current HTML; the whole edit is atomic (any failure leaves the app unchanged). Pass exactly one edit mode.
edits[].old_str
string
Yes
Exact text to replace; must occur exactly once in the current HTML (add surrounding context to disambiguate).
edits[].new_str
string
Yes
Replacement text (may be empty to delete).
replacementHtml
string
No
The complete new document, replacing the current HTML outright with no old_str matching — use this for a full rewrite instead of reproducing the whole document as an edit. Pass exactly one edit mode.
replacementHtmlSource
object
No
Like replacementHtml, but the document is read server-side from a file you already saved instead of being written out here — use this when the HTML already exists as a file (assembled in the sandbox, or attached to the chat) so its bytes never have to be reproduced as tool arguments. The file must be UTF-8 text and is subject to the same size limit as any other document. Reads whatever the file holds at call time. Pass exactly one edit mode.
replacementHtmlSource.fileId
string
Yes
Id of a saved file whose bytes become the document, as returned by download_file, save_file, or search_files.
imageReplacements
object[]
No
Replace one or more image URLs with the most recently attached image. Pass short surrounding anchors only: the server reads the newest attachment bytes, builds the data URL, and replaces everything between the anchors. Never put attachment ids, filenames, paths, or old/new base64 in edits/tool arguments. The batch is atomic. Pass exactly one edit mode.
imageReplacements[].before_str
string
Yes
Exact short HTML ending with the opening quote immediately before the existing image URL or data URL (for example <img src="). It must occur exactly once; include nearby id/class context when needed to disambiguate.
imageReplacements[].after_str
string
Yes
Exact short HTML starting with the matching closing quote immediately after the existing image URL or data URL (for example " alt="Issue tracker"). The text between before_str and after_str is replaced server-side.
imageReplacements[].source
object
Yes
The most recently attached image in this conversation. Its bytes are read and encoded server-side; never read or base64-encode the attachment yourself.
imageReplacements[].source.type
"chat_attachment"
Yes
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
description
string | null
Yes
scope
"personal" | "team" | "org"
Yes
latestVersion
number
Yes
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
set_app_tools
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id whose tools to set.
tools
string[]
Yes
Upstream MCP tool names (e.g. from search_tools) to assign to the app, replacing its current set exactly — pass the full desired list, or [] to clear all.
Output
Field
Type
Required
Description
id
string
Yes
tools
string[]
Yes
The app's assigned tool names after this call.
set_app_labels
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id whose labels to set.
labels
object[]
Yes
Key-value labels to assign to the app, replacing its current set exactly — pass the full desired list, or [] to clear all. One value per key; a repeated key keeps the last one.
labels[].key
string
Yes
labels[].value
string
Yes
Output
Field
Type
Required
Description
id
string
Yes
labels
object[]
Yes
The app's labels after this call.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
set_app_lock
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
locked
boolean
Yes
true locks the app against all modification; false unlocks it (only on the user's direct request).
Diagnostics from the most recent live render of the head version (untrusted iframe output). status no_render_observed means no render of this version has happened yet — live diagnostics are captured only when the app renders for a viewer, so this is the normal state right after authoring and a clean static pass (ok: true) is enough to proceed.
live.status
"no_render_observed" | "clean" | "errors"
Yes
live.version
number
Yes
live.entries
object[]
Yes
live.entries[].type
string
Yes
live.entries[].message
string
Yes
live.renderedAt
string | null
Yes
publish_app
Required RBAC permission: manage-permissions on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id to publish.
scope
"team" | "org"
Yes
Publish to specific teams or to the whole organization. Promotes the app out of personal scope.
teams
string[]
No
Target teams, each a team name or team id — required when scope is team. Pass the team name the user gave (e.g. ["Platform"]); no need to look up ids first.
Output
Field
Type
Required
Description
id
string
Yes
scope
"personal" | "team" | "org"
Yes
runUrl
string
Yes
Standalone page for the published app.
preview_app_tool
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id whose assigned tool to run.
toolName
string
Yes
Name of an MCP tool assigned to the app (exactly as archestra.tools.call would receive it).
args
object
No
Arguments to pass to the tool (defaults to {}).
Output
Field
Type
Required
Description
toolName
string
Yes
isError
boolean
Yes
truncated
boolean
Yes
output
string
Yes
The JSON-serialized value archestra.tools.call resolves with for this result, framed as untrusted data (media dataUrls are elided).
Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app.
Output
Field
Type
Required
Description
value
any
Yes
revision
integer | null
Yes
owner
string | null
Yes
User id owning a shared key, or null if collaborative.
app_data_set
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
key
string
Yes
The data store key.
value
any
Yes
Any JSON-serializable value except null (use app_data_delete to clear a key). Pass objects/arrays directly — get returns exactly what was stored, no JSON.stringify needed.
scope
"user" | "app"
No
Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app.
expectedRevision
integer
No
Optimistic concurrency guard. Omit for last-writer-wins. 0 = create only if the key is absent. A positive value = overwrite only if the key is still at that revision (from a prior get/set); otherwise the write is rejected as a conflict.
claimOwner
boolean
No
Shared-scope only: when creating a NEW key, claim it so only you (or an app admin/author) may later overwrite or delete it. Has no effect on the "user" scope or on an existing key.
Output
Field
Type
Required
Description
key
string
Yes
revision
integer
Yes
owner
string | null
Yes
User id owning a shared key, or null if collaborative.
Read one project's context in a single call: its metadata, its instructions (the instructions.md that steers every chat in the project), the files it owns, and the apps linked into it that you ca...
List the scheduled agent triggers the caller can see: which agent each one runs, its cron expression and timezone, whether it is enabled, and when it last fired.
List a scheduled task's run history, newest first: whether each run was due or manual, how it ended, when it started and completed, its failure text, and the chat conversation holding its transcript.
Read what one scheduled task run did: its messages and every tool call with arguments, result and error, including guardrails rulings, remedy offers and review outcomes returned to the agent.
Additional access requirement: Returns only projects the caller owns or that are shared with them. Oversight of every project (a * grant) does not extend to this tool.
Input
Parameter
Type
Required
Description
query
string
No
Case-insensitive substring matched against the project name and description. Omit to list everything the caller can reach.
access
string[]
No
Only return items the caller reaches in one of these ways: mine (created by the caller), shared (shared with the caller or one of their teams), org (shared with the whole organization), others (not shared with the caller; visible only through admin access). Omit for everything the caller can read. Use ["mine"] for "my projects".
shared_with
string[]
No
Only return items whose own permissions grant read to one of these subjects: org (the whole organization), role:, team:, user:, serviceAccount:. Omit for no filtering.
owner_ids
string[]
No
Only return items created by one of these user IDs. Omit for no filtering.
Output
Field
Type
Required
Description
projects
object[]
Yes
Projects the caller can reach.
projects[].id
string
Yes
The project's id — pass it to get_project.
projects[].name
string
Yes
The project's name.
projects[].description
string | null
Yes
The project's description.
projects[].visibility
"organization" | "team" | "user" | null
Yes
Who the project is shared with; null = owner-only.
Additional access requirement: Readable only for projects the caller owns or that are shared with them. Oversight of every project (a * grant) does not extend to this tool.
Input
Parameter
Type
Required
Description
project_id
string
Yes
Id of the project to read (from list_projects).
Output
Field
Type
Required
Description
id
string
Yes
The project's id — pass it to get_project.
name
string
Yes
The project's name.
description
string | null
Yes
The project's description.
visibility
"organization" | "team" | "user" | null
Yes
Who the project is shared with; null = owner-only.
viewer_role
"owner" | "shared" | "admin"
Yes
The caller's relationship to the project.
owner_name
string | null
Yes
Display name of the owner.
labels
object[]
Yes
Key/value labels assigned to the project.
labels[].key
string
Yes
labels[].value
string
Yes
labels[].keyId
string
No
labels[].valueId
string
No
conversation_count
integer
Yes
How many chats live in the project.
created_at
string
Yes
ISO 8601 creation timestamp.
instructions
string
Yes
The project's instructions markdown; empty when never saved. Truncated when instructions_truncated is true.
instructions_truncated
boolean
Yes
Whether instructions was cut short at the inline limit.
files
object[]
Yes
Files the project owns. Read one with read_file, passing the same project_id and this ref.
files[].id
string
Yes
The file's id.
files[].ref
string
Yes
Stable reference to pass to read_file.
files[].filename
string
Yes
The file's name.
files[].mime_type
string
Yes
The file's MIME type.
files[].size_bytes
integer
Yes
Size in bytes.
apps
object[]
Yes
Apps linked into the project that you can open. Read or edit one with the app tools, passing this id.
Additional access requirement: Requires an acting user. Omitting project_id creates a private project with the task prompt as its instructions. Repeating the same new-project task returns the existing schedule. An existing project must be accessible to the caller.
Input
Parameter
Type
Required
Description
name
string
Yes
Name of the scheduled task.
project_id
string
No
Existing project to schedule in. Omit to create a private project using name and message_template as its instructions.
agent_id
string
No
Agent to run. For a new project, defaults to the current agent; for an existing project, its agent then the organization default.
cron_expression
string
Yes
Cron expression, for example 0 9 * * 1-5.
timezone
string
Yes
IANA timezone, for example America/Toronto.
message_template
string
Yes
Prompt sent to the agent on each run.
enabled
boolean
No
Whether the schedule is enabled. Defaults to true on creation.
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
actor_user_id
string
Yes
The user the scheduled run executes as.
actor_name
string | null
Yes
Display name of that user.
created_at
string
Yes
ISO 8601 creation timestamp.
message_template
string
Yes
The prompt sent to the agent on every run.
created
boolean
Yes
False when an identical new-project request reused an existing schedule.
Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can update access can perform this action. Project membership alone permits reading. See Granular Access Control.
Input
Parameter
Type
Required
Description
name
string
No
Name of the scheduled task.
project_id
string
No
Project containing the scheduled task.
agent_id
string
No
Agent to run. Defaults to the project's agent, then the organization default.
cron_expression
string
No
Cron expression, for example 0 9 * * 1-5.
timezone
string
No
IANA timezone, for example America/Toronto.
message_template
string
No
Prompt sent to the agent on each run.
enabled
boolean
No
Whether the schedule is enabled. Defaults to true on creation.
schedule_trigger_id
string
Yes
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Full access access can perform this action. Project membership alone permits reading. See Granular Access Control.
Additional access requirement: Requires a user token. The caller must be the schedule actor, a project member, or someone with organization-wide Projects Can read access.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule to read.
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
Additional access requirement: Requires a user token. The caller must be the schedule actor, a project member, or someone with organization-wide Projects Can read access.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule whose runs to list.
status
"running" | "success" | "failed" | "cancelled"
No
Only runs in this state.
limit
integer
No
How many rows to return, newest first (1-100, default 25).
cursor
string
No
Pass pagination.nextCursor from the previous response to read the next page. Keep the same filters; omit for the newest page.
Output
Field
Type
Required
Description
pagination
object
Yes
pagination.limit
integer
Yes
pagination.nextCursor
string | null
Yes
pagination.hasNext
boolean
Yes
runs
object[]
Yes
Matching runs, newest first.
runs[].blocked_by
object | null
Yes
Why this tick was skipped, including the blocking run and its frozen deadline.
runs[].blocked_by.phase
"starting" | "running" | "stopping"
Yes
runs[].blocked_by.runId
string | null
Yes
runs[].blocked_by.runtimeTaskId
string | null
Yes
runs[].blocked_by.startedAt
string
Yes
runs[].blocked_by.elapsedSeconds
integer
Yes
runs[].blocked_by.deadline
string | null
Yes
runs[].blocked_by.maximumDurationSeconds
integer | null
Yes
runs[].id
string
Yes
The run's id — pass it to get_schedule_trigger_run.
runs[].trigger_id
string
Yes
Id of the schedule this run belongs to.
runs[].run_kind
"due" | "manual"
Yes
due = fired by the schedule; manual = started by a person.
runs[].status
"running" | "success" | "failed" | "cancelled"
Yes
Current state of the run.
runs[].started_at
string | null
Yes
ISO 8601 timestamp the run started.
runs[].completed_at
string | null
Yes
ISO 8601 timestamp the run settled; null while still running.
runs[].error
string | null
Yes
Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress.
runs[].chat_conversation_id
string | null
Yes
Chat conversation holding the run's transcript, when linked.
runs[].runtime_task_id
string | null
Yes
Agent Runtime task id, when the run executed on the runtime.
Additional access requirement: Requires a user token. The caller must be the schedule actor, a project member, or someone with organization-wide Projects Can read access.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule the run belongs to.
run_id
string
Yes
Id of the run to read.
Output
Field
Type
Required
Description
blocked_by
object | null
Yes
Why this tick was skipped, including the blocking run and its frozen deadline.
blocked_by.phase
"starting" | "running" | "stopping"
Yes
blocked_by.runId
string | null
Yes
blocked_by.runtimeTaskId
string | null
Yes
blocked_by.startedAt
string
Yes
blocked_by.elapsedSeconds
integer
Yes
blocked_by.deadline
string | null
Yes
blocked_by.maximumDurationSeconds
integer | null
Yes
id
string
Yes
The run's id — pass it to get_schedule_trigger_run.
trigger_id
string
Yes
Id of the schedule this run belongs to.
run_kind
"due" | "manual"
Yes
due = fired by the schedule; manual = started by a person.
status
"running" | "success" | "failed" | "cancelled"
Yes
Current state of the run.
started_at
string | null
Yes
ISO 8601 timestamp the run started.
completed_at
string | null
Yes
ISO 8601 timestamp the run settled; null while still running.
error
string | null
Yes
Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress.
chat_conversation_id
string | null
Yes
Chat conversation holding the run's transcript, when linked.
runtime_task_id
string | null
Yes
Agent Runtime task id, when the run executed on the runtime.
Additional access requirement: Requires a user token. The caller must be the schedule actor, or hold both organization-wide Projects Can read access and log:admin. Project membership or Projects read alone shows run status but not the transcript.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule the run belongs to.
run_id
string
Yes
Id of the run to read.
Output
Field
Type
Required
Description
run
object
Yes
run.blocked_by
object | null
Yes
Why this tick was skipped, including the blocking run and its frozen deadline.
run.blocked_by.phase
"starting" | "running" | "stopping"
Yes
run.blocked_by.runId
string | null
Yes
run.blocked_by.runtimeTaskId
string | null
Yes
run.blocked_by.startedAt
string
Yes
run.blocked_by.elapsedSeconds
integer
Yes
run.blocked_by.deadline
string | null
Yes
run.blocked_by.maximumDurationSeconds
integer | null
Yes
run.id
string
Yes
The run's id — pass it to get_schedule_trigger_run.
run.trigger_id
string
Yes
Id of the schedule this run belongs to.
run.run_kind
"due" | "manual"
Yes
due = fired by the schedule; manual = started by a person.
run.status
"running" | "success" | "failed" | "cancelled"
Yes
Current state of the run.
run.started_at
string | null
Yes
ISO 8601 timestamp the run started.
run.completed_at
string | null
Yes
ISO 8601 timestamp the run settled; null while still running.
run.error
string | null
Yes
Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress.
run.chat_conversation_id
string | null
Yes
Chat conversation holding the run's transcript, when linked.
run.runtime_task_id
string | null
Yes
Agent Runtime task id, when the run executed on the runtime.
run.created_at
string
Yes
ISO 8601 creation timestamp.
session_id
string
Yes
The run's session id. Pass it to list_openappa_consults or list_openappa_yells.
conversation = the run's chat; interactions = rebuilt from its LLM calls; encrypted = the chat is encrypted and cannot be read here; runtime = it ran on the Agent Runtime, whose output is read on its run page; pending = it finished under a minute ago with nothing recorded yet; its record may still be written, so read it again shortly; none = nothing was recorded.
messages
object[]
Yes
The run's messages in order, with long values shortened.
messages[].role
string
Yes
messages[].parts
object[]
Yes
messages[].parts[].type
string
Yes
text, tool, or the UI part type when it is something else.
messages[].parts[].text
string
No
Message text, for a text part.
messages[].parts[].tool_name
string
No
Tool called, for a tool part.
messages[].parts[].tool_call_id
string
No
The tool call's id.
messages[].parts[].parent_tool_call_id
string
No
For a delegated agent's call, the delegation call that started that agent.
messages[].parts[].state
string
No
The tool call's final state.
messages[].parts[].input
string
No
The tool call's arguments as JSON.
messages[].parts[].output
string
No
The tool result as JSON, including any guardrails ruling.
messages[].parts[].error_text
string
No
The tool call's error text.
truncated
boolean
Yes
True when parts were left out to keep the result small.
Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can update access can perform this action. Project membership alone permits reading. See Granular Access Control.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule to enable.
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can update access can perform this action. Project membership alone permits reading. See Granular Access Control.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule to disable.
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can use access can perform this action. Project membership alone permits reading. See Granular Access Control.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule to run.
Output
Field
Type
Required
Description
blocked_by
object | null
Yes
Why this tick was skipped, including the blocking run and its frozen deadline.
blocked_by.phase
"starting" | "running" | "stopping"
Yes
blocked_by.runId
string | null
Yes
blocked_by.runtimeTaskId
string | null
Yes
blocked_by.startedAt
string
Yes
blocked_by.elapsedSeconds
integer
Yes
blocked_by.deadline
string | null
Yes
blocked_by.maximumDurationSeconds
integer | null
Yes
id
string
Yes
The run's id — pass it to get_schedule_trigger_run.
trigger_id
string
Yes
Id of the schedule this run belongs to.
run_kind
"due" | "manual"
Yes
due = fired by the schedule; manual = started by a person.
status
"running" | "success" | "failed" | "cancelled"
Yes
Current state of the run.
started_at
string | null
Yes
ISO 8601 timestamp the run started.
completed_at
string | null
Yes
ISO 8601 timestamp the run settled; null while still running.
error
string | null
Yes
Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress.
chat_conversation_id
string | null
Yes
Chat conversation holding the run's transcript, when linked.
runtime_task_id
string | null
Yes
Agent Runtime task id, when the run executed on the runtime.
created_at
string
Yes
ISO 8601 creation timestamp.
Agent Runtime
Tool
Description
Permission
delete_workspace
Permanently delete a retained runtime workspace and all of its files.
Upload a file into the messaging-channel thread a run reports to — a demo recording, for example — so it renders natively there (Slack plays video uploads inline).
What the agent should do, including handoff context and acceptance criteria.
attachments
object[]
No
Input files staged before the first turn. For repository work, include a patch for uncommitted changes and identify the base commit in message. Never include credentials.
Only runs originating in the current messaging thread. Requires messaging context; never falls back to an unfiltered list.
limit
integer
No
Output
Field
Type
Required
Description
runs
object[]
Yes
runs[].task_id
string
Yes
runs[].llm_session_id
string | null
Yes
Verified LLM telemetry session key for /llm/logs/:id (the run's workload name); URL-encode it as one path segment. Null when no readable logged session is available. It is not a task_id: never pass it to the run tools.
runs[].title
string
Yes
runs[].prompt
string
Yes
runs[].state
string
Yes
runs[].status_reason
string | null
Yes
runs[].started_at
string
Yes
runs[].ended_at
string | null
Yes
runs[].state_changed_at
string | null
Yes
runs[].hard_deadline_at
string
Yes
When the runtime will be forcefully stopped.
runs[].last_model_activity_at
string | null
Yes
Most recent model request attributed to this run.
runs[].attention_state
"input_required" | "auth_required" | null
Yes
Native runtime signal that the live process needs user attention.
Exactly one credential to transfer. Never include more than the task needs.
environment[].key
string
Yes
Environment variable name, e.g. AWS_SECRET_ACCESS_KEY.
environment[].type
"secret"
Yes
Always 'secret'. Marks the value for redaction in logs.
environment[].value
string
No
The credential value to transfer. OMIT IT to declare the credential without a value and get back a link the person opens to paste it themselves — the value then never enters your context. Send a value only when the person asked you to move one you already hold.
label
string
No
Human-readable name shown in the Agent's credential list. Defaults to the key.
Output
Field
Type
Required
Description
key
string
Yes
The environment variable the value is stored under.
scope
"personal"
Yes
Who the value applies to. Always personal to the calling user.
declarationCreated
boolean
Yes
Whether this call declared the credential on the Agent.
valueStored
boolean
Yes
Whether a value is now stored. False means the credential is declared and still empty.
url
string | null
Yes
Where the person pastes the value. Null when this call already stored one.
availability
string
Yes
When a run can read the value, in plain words.
next_step
string
No
What to do with url: hand it over in the reply text, never inside a question form. Only set while a value is still missing.
Agents
Tool
Description
Permission
create_agent
Create a new agent with the specified name, optional description, labels, prompts, icon emoji, model, explicit tool assignments, and sub-agent delegations.
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models. Use 'search_and_run_only' to keep the initial tool list small while letting search_tools find assigned tools and run_tool execute them. MCP gateways defer skill, file, sandbox, run lifecycle and policy-management capabilities in this mode; questions and guardrails session/peer-message controls remain directly available. search_tools summarizes the caller's available built-in capability groups as well as connected MCP servers. Manual gateways also keep explicitly assigned MCP App UI tools available for client rendering. Internal chat keeps assigned skill discovery/loading, file, sandbox and run lifecycle tools directly available for its skill activation and file guidance. App tools (scaffold_app, edit_app, read_app, render_app, list_apps, and the rest of the app surface) are reached through search_tools/run_tool in 'search_and_run_only' mode.
accessAllTools
boolean
No
Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access (MCP catalog tools and knowledge sources) without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only', since dynamic access only works through the search/run dispatch surface. Defaults to false. Also gated by the organization's security settings.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions). Defaults to false.
description
string | null
No
Optional human-readable description of the agent.
icon
string | null
No
Optional emoji icon for the agent.
knowledgeBaseIds
string[]
No
Knowledge base IDs to assign to the agent. Use get_knowledge_bases first when you need to look up IDs by name.
connectorIds
string[]
No
Knowledge connector IDs to assign directly to the agent. Use get_knowledge_connectors first when you need to look up IDs by name.
subAgentIds
string[]
No
Agent IDs to delegate to from this newly created agent.
suggestedPrompts
object[]
No
Optional suggested prompts that appear in the chat UI.
suggestedPrompts[].summaryTitle
string
Yes
Short title shown to users for this suggested prompt.
suggestedPrompts[].prompt
string
Yes
Suggested prompt text users can click to start a conversation.
systemPrompt
string | null
No
The system prompt that defines the agent's behavior.
toolAssignments
object[]
No
Explicit tool assignments to create immediately after the agent is created.
toolAssignments[].toolId
string
Yes
The ID of the tool to assign to the agent.
toolAssignments[].resolveAtCallTime
boolean
No
When true, resolve credentials and execution target at tool call time. Prefer this for builder flows.
toolAssignments[].credentialResolutionMode
"static" | "dynamic" | "enterprise_managed"
No
toolAssignments[].mcpServerId
string | null
No
Optional MCP server installation to pin the tool to when using static credential resolution.
runtime
object
No
Run this agent in its own container (Agent Runtime) instead of the built-in chat harness. Pass { template } for a maintained CLI, or { image } for a custom image. Other fields override the defaults: claudeCode.authentication is 'subscription' (each user signs in with their own Claude account, the default) or 'provider' (bill through llmApiKeyId/modelId); credentials declares environment variables a run needs (users supply values later, or use transfer_credential); ttlHours, idleTimeoutMinutes, and maxCostUsd bound each run; privileged requires an agent administrator.
Maintained CLI to run: 'claude-code' (Claude Code), 'codex' (Codex), 'opencode' (OpenCode), 'hermes' (Hermes), 'openclaw' (OpenClaw). The image, launch command, and model protocol come from the template.
runtime.image
string
No
runtime.command
string[] | null
No
runtime.inferenceProtocol
"openai_responses" | "openai_chat" | "anthropic"
No
llmApiKeyId
string
No
Provider API key the agent uses. Set together with modelId. Use list_llm_models to find both.
modelId
string
No
Model the agent uses: the model's id from list_llm_models, not its provider name. Set together with llmApiKeyId.
Filter by a configured provider key, or organization-default for agents with no pinned key or model.
limit
integer
No
Maximum number of agents to return.
name
string
No
Optional agent name filter. Use this when the user names an agent but you still need to look up the ID.
access
string[]
No
Only return items the caller reaches in one of these ways: mine (created by the caller), shared (shared with the caller or one of their teams), org (shared with the whole organization), others (not shared with the caller; visible only through admin access). Omit for everything the caller can read. Use ["mine"] for "my agents".
shared_with
string[]
No
Only return items whose own permissions grant read to one of these subjects: org (the whole organization), role:, team:, user:, serviceAccount:. Omit for no filtering.
owner_ids
string[]
No
Only return items created by one of these user IDs. Omit for no filtering.
Output
Field
Type
Required
Description
total
number
Yes
The total number of matching agents.
agents
object[]
Yes
agents[].id
string
Yes
The agent ID.
agents[].name
string
Yes
The agent name.
agents[].scope
"personal" | "team" | "org"
Yes
The agent scope.
agents[].executionMode
"runtime" | "foreground"
Yes
Runtime agents retain a workspace and support steering; foreground agents do not.
agents[].description
string | null
Yes
The agent description, if any.
agents[].resolvedLlmProviderKeyName
string | null
Yes
The configured provider-key name, or null when unconfigured.
agents[].resolvedLlmModelName
string | null
Yes
The configured model name, or null when unconfigured.
agents[].teams
object[]
Yes
Teams attached to it.
agents[].teams[].id
string
Yes
The team ID.
agents[].teams[].name
string
Yes
The team name.
agents[].labels
object[]
Yes
Assigned labels.
agents[].labels[].key
string
Yes
The label key.
agents[].labels[].value
string
Yes
The label value.
agents[].tools
object[]
Yes
agents[].tools[].name
string
Yes
The tool name.
agents[].tools[].description
string | null
Yes
The tool description, if any.
agents[].knowledgeSources
object[]
Yes
Assigned knowledge bases and connectors.
agents[].knowledgeSources[].name
string
Yes
The knowledge source name.
agents[].knowledgeSources[].description
string | null
Yes
The knowledge source description, if any.
agents[].knowledgeSources[].type
"knowledge_base" | "knowledge_connector"
Yes
Whether this source is a knowledge base or connector.
edit_agent
Required RBAC permission: update on the agent (granted per item)
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the agent to edit. Use get_agent or list_agents to look it up by name.
subAgentIds
string[]
No
Agent IDs to add as delegation targets.
toolAssignments
object[]
No
Explicit tool assignments to add or update on the agent.
toolAssignments[].toolId
string
Yes
The ID of the tool to assign to the agent.
toolAssignments[].resolveAtCallTime
boolean
No
When true, resolve credentials and execution target at tool call time. Prefer this for builder flows.
toolAssignments[].credentialResolutionMode
"static" | "dynamic" | "enterprise_managed"
No
toolAssignments[].mcpServerId
string | null
No
Optional MCP server installation to pin the tool to when using static credential resolution.
description
string | null
No
New description for the agent.
icon
string | null
No
New emoji icon for the agent.
knowledgeBaseIds
string[]
No
Replace the agent's assigned knowledge bases with this set.
labels
object[]
No
Replace the agent's labels with this set.
labels[].key
string
Yes
labels[].value
string
Yes
name
string
No
New name for the agent.
connectorIds
string[]
No
Replace the agent's directly assigned knowledge connectors with this set.
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models.
accessAllTools
boolean
No
Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only'.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions).
suggestedPrompts
object[]
No
Replace the agent's suggested prompts.
suggestedPrompts[].summaryTitle
string
Yes
Short title shown to users for this suggested prompt.
suggestedPrompts[].prompt
string
Yes
Suggested prompt text users can click to start a conversation.
systemPrompt
string | null
No
New system prompt for the agent.
runtime
object | null
No
Run this agent in its own container (Agent Runtime) instead of the built-in chat harness. Pass { template } for a maintained CLI, or { image } for a custom image. Other fields override the defaults: claudeCode.authentication is 'subscription' (each user signs in with their own Claude account, the default) or 'provider' (bill through llmApiKeyId/modelId); credentials declares environment variables a run needs (users supply values later, or use transfer_credential); ttlHours, idleTimeoutMinutes, and maxCostUsd bound each run; privileged requires an agent administrator. Replaces the whole runtime: pass every field to keep. Pass null to return the agent to the built-in chat harness.
llmApiKeyId
string | null
No
Provider API key the agent uses. Set together with modelId. Use list_llm_models to find both. Pass null for both to use the default model.
modelId
string | null
No
Model the agent uses: the model's id from list_llm_models, not its provider name. Set together with llmApiKeyId. Pass null for both to use the default model.
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
The script file name (.py or .sh); also the execution-order key within an event.
hooks[].content
string
Yes
The script content.
hooks[].requirements
string[]
Yes
Python dependencies installed before a .py hook runs.
hooks[].enabled
boolean
Yes
Whether the hook currently fires.
hooks[].createdAt
string
Yes
ISO timestamp when the hook was created.
hooks[].updatedAt
string
Yes
ISO timestamp when the hook was last updated.
create_hook
Required RBAC permission: update on the agent (granted per item)
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
The script file name (.py or .sh); also the execution-order key within an event.
hook.content
string
Yes
The script content.
hook.requirements
string[]
Yes
Python dependencies installed before a .py hook runs.
hook.enabled
boolean
Yes
Whether the hook currently fires.
hook.createdAt
string
Yes
ISO timestamp when the hook was created.
hook.updatedAt
string
Yes
ISO timestamp when the hook was last updated.
update_hook
Required RBAC permission: update on the agent (granted per item)
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
The script file name (.py or .sh); also the execution-order key within an event.
hook.content
string
Yes
The script content.
hook.requirements
string[]
Yes
Python dependencies installed before a .py hook runs.
hook.enabled
boolean
Yes
Whether the hook currently fires.
hook.createdAt
string
Yes
ISO timestamp when the hook was created.
hook.updatedAt
string
Yes
ISO timestamp when the hook was last updated.
delete_hook
Required RBAC permission: update on the agent (granted per item)
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the hook to delete.
Output
Field
Type
Required
Description
success
true
Yes
id
string
Yes
Knowledge Management
Tool
Description
Permission
query_knowledge_sources
Search the organization's indexed knowledge — documents, files, images, photos, and records synced from its connected sources.
The user's original query, passed verbatim without rephrasing or expansion.
documentFilter
object
No
Optional. Narrows the search to a subset of the indexed documents by their source metadata — for example {"spaceKey": "DEV"} or {"labels": ["release-2.0"]}. Keys are ANDed; a list of values for one key is ORed. Matches both single values and list-valued metadata. Only use this when the user's request explicitly names a subset to search; do NOT infer one from the topic of the question, and do NOT guess key or value names. If a filter matches nothing, the response lists the values that actually exist so the call can be retried with a real one.
Output
Field
Type
Required
Description
results
any[]
Yes
Retrieved knowledge results.
totalChunks
number
Yes
The number of result chunks returned.
citationInstruction
string
No
How to cite these results: back each claim with a verbatim quote tagged with the source chunk's ref.
filterDiagnostic
string
No
Present only when documentFilter matched no documents. Names the values that do exist for the keys that were filtered on, so the search can be retried.
Only return items the caller reaches in one of these ways: mine (created by the caller), shared (shared with the caller or one of their teams), org (shared with the whole organization), others (not shared with the caller; visible only through admin access). Omit for everything the caller can read. Use ["mine"] for "my knowledge bases".
shared_with
string[]
No
Only return items whose own permissions grant read to one of these subjects: org (the whole organization), role:, team:, user:, serviceAccount:. Omit for no filtering.
owner_ids
string[]
No
Only return items created by one of these user IDs. Omit for no filtering.
Type of the knowledge connector (for example jira, confluence, or google_drive).
config
object
Yes
Provider-specific configuration object.
description
string | null
No
Description of the knowledge connector.
sync_permissions_from_source
boolean
No
Mirror each document's access control from the source, so a query only returns what the caller could open there. Requires an enterprise license and a connector type that supports it.
Re-discover a deployed MCP server's tools from the live server and refresh Archestra's tool catalog for it — picks up added, removed, and changed tools (names, descriptions, and input schemas) with...
Optional search query to filter MCP servers by name or description.
access
string[]
No
Only return items the caller reaches in one of these ways: mine (created by the caller), shared (shared with the caller or one of their teams), org (shared with the whole organization), others (not shared with the caller; visible only through admin access). Omit for everything the caller can read. Use ["mine"] for "my MCP servers".
shared_with
string[]
No
Only return items whose own permissions grant read to one of these subjects: org (the whole organization), role:, team:, user:, serviceAccount:. Omit for no filtering.
owner_ids
string[]
No
Only return items created by one of these user IDs. Omit for no filtering.
Output
Field
Type
Required
Description
items
object[]
Yes
Catalog items matching the search.
items[].id
string
Yes
The catalog item ID.
items[].name
string
Yes
The MCP server name.
items[].version
string | null
Yes
The version, if provided.
items[].description
string | null
Yes
The server description, if any.
items[].serverType
"local" | "remote" | "builtin" | "app"
Yes
Server type: local, remote, builtin, or app (user-generated App).
Only return items the caller reaches in one of these ways: mine (created by the caller), shared (shared with the caller or one of their teams), org (shared with the whole organization), others (not shared with the caller; visible only through admin access). Omit for everything the caller can read. Use ["mine"] for "my MCP servers".
shared_with
string[]
No
Only return items whose own permissions grant read to one of these subjects: org (the whole organization), role:, team:, user:, serviceAccount:. Omit for no filtering.
owner_ids
string[]
No
Only return items created by one of these user IDs. Omit for no filtering.
ID of the environment this server belongs to. Pass null for the default environment. Omit it to use your own environment, or the organization's landing environment for new MCP servers when you have none.
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models.
accessAllTools
boolean
No
Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access (MCP catalog tools and knowledge sources) without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only', since dynamic access only works through the search/run dispatch surface. Defaults to false. Also gated by the organization's security settings.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions). Defaults to false.
knowledgeBaseIds
string[]
No
Knowledge base IDs to assign to the agent. Use get_knowledge_bases first when you need to look up IDs by name.
connectorIds
string[]
No
Knowledge connector IDs to assign directly to the agent. Use get_knowledge_connectors first when you need to look up IDs by name.
subAgentIds
string[]
No
Optional list of agent IDs that this MCP gateway can delegate to as subagents.
The ID of the MCP gateway to fetch. Prefer the ID when you already have it.
name
string
No
The exact name of the MCP gateway to fetch when you do not already have the ID.
Output
Field
Type
Required
Description
id
string
Yes
The resource ID.
name
string
Yes
The resource name.
description
string | null
Yes
The resource description, if any.
icon
string | null
Yes
The emoji icon, if configured.
scope
"personal" | "team" | "org"
Yes
The visibility scope.
toolExposureMode
"full" | "search_and_run_only"
Yes
How tools are loaded for MCP clients and models.
accessAllTools
boolean
Yes
Whether search_tools/run_tool may dynamically access every tool the calling user can access.
accessAllSubagents
boolean
Yes
Whether the agent may delegate to every internal agent the calling user can access.
agentType
"agent" | "llm_proxy" | "mcp_gateway" | "profile"
Yes
The resource type.
systemPrompt
string | null
No
teams
object[]
Yes
The teams attached to it.
teams[].id
string
Yes
The team ID.
teams[].name
string
Yes
The team name.
labels
object[]
Yes
Assigned labels.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
tools
object[]
Yes
Assigned tools.
tools[].id
string
Yes
The assigned tool ID.
tools[].name
string
Yes
The tool name.
tools[].description
string | null
Yes
The tool description, if any.
tools[].catalogId
string | null
Yes
The MCP catalog ID the tool comes from, if any.
knowledgeBaseIds
string[]
Yes
Assigned knowledge base IDs.
connectorIds
string[]
Yes
Assigned knowledge connector IDs.
suggestedPrompts
object[]
Yes
Configured suggested prompts.
suggestedPrompts[].summaryTitle
string
Yes
The short title shown in the chat UI.
suggestedPrompts[].prompt
string
Yes
The suggested prompt text.
edit_mcp_gateway
Required RBAC permission: update on the MCP gateway (granted per item)
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the MCP gateway to edit. Use get_mcp_gateway to look it up by name first if needed.
description
string | null
No
New description for the MCP gateway.
icon
string | null
No
New emoji icon for the MCP gateway.
labels
object[]
No
Replace the MCP gateway's labels with this set.
labels[].key
string
Yes
labels[].value
string
Yes
name
string
No
New name for the MCP gateway.
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions). Defaults to false.
knowledgeBaseIds
string[]
No
Replace the MCP gateway's assigned knowledge bases with this set.
connectorIds
string[]
No
Replace the MCP gateway's directly assigned knowledge connectors with this set.
subAgentIds
string[]
No
Optional list of agent IDs that this MCP gateway can delegate to as subagents.
Tool Assignment
Tool
Description
Permission
bulk_assign_tools_to_agents
Assign multiple tools to multiple agents in bulk with validation and error handling
update on the agent (granted per item)
bulk_remove_tools_from_agents
Remove multiple tools from multiple agents in bulk.
update on the agent (granted per item)
bulk_assign_tools_to_mcp_gateways
Assign multiple tools to multiple MCP gateways in bulk with validation and error handling
update on the MCP gateway (granted per item)
bulk_assign_tools_to_agents
Required RBAC permission: update on the agent (granted per item)
Input
Parameter
Type
Required
Description
assignments
object[]
Yes
Assignments to create or update for agents.
assignments[].toolId
string
Yes
The ID of the tool to assign.
assignments[].resolveAtCallTime
boolean
No
When true, resolve credentials and execution target at tool call time. Prefer this for builder flows.
assignments[].credentialResolutionMode
"static" | "dynamic" | "enterprise_managed"
No
assignments[].mcpServerId
string | null
No
Optional MCP server installation to pin the tool to when using static credential resolution.
assignments[].agentId
string
Yes
The agent ID to assign the tool to.
Output
Field
Type
Required
Description
succeeded
object[]
Yes
Assignments that succeeded.
succeeded[].agentId
string
Yes
The target agent ID.
succeeded[].toolId
string
Yes
The tool ID.
succeeded[].error
string
No
Validation or assignment error.
succeeded[].errorCode
"not_found" | "validation_error" | "forbidden"
No
Structured assignment error code.
succeeded[].errorType
string
No
Structured assignment error type.
failed
object[]
Yes
Assignments that failed.
failed[].agentId
string
Yes
The target agent ID.
failed[].toolId
string
Yes
The tool ID.
failed[].error
string
No
Validation or assignment error.
failed[].errorCode
"not_found" | "validation_error" | "forbidden"
No
Structured assignment error code.
failed[].errorType
string
No
Structured assignment error type.
duplicates
object[]
Yes
Assignments skipped because they already existed.
duplicates[].agentId
string
Yes
The target agent ID.
duplicates[].toolId
string
Yes
The tool ID.
duplicates[].error
string
No
Validation or assignment error.
duplicates[].errorCode
"not_found" | "validation_error" | "forbidden"
No
Structured assignment error code.
duplicates[].errorType
string
No
Structured assignment error type.
bulk_remove_tools_from_agents
Required RBAC permission: update on the agent (granted per item)
Input
Parameter
Type
Required
Description
removals
object[]
Yes
Tool removals to apply to agents.
removals[].agentId
string
Yes
The agent ID to remove the tool from.
removals[].toolId
string
Yes
The ID of the tool to remove.
Output
Field
Type
Required
Description
succeeded
object[]
Yes
Removals that took effect.
succeeded[].agentId
string
Yes
The target agent ID.
succeeded[].toolId
string
Yes
The tool ID.
succeeded[].error
string
No
Permission or removal error.
notAssigned
object[]
Yes
Removals skipped because the tool was not assigned to the agent (Custom mode).
notAssigned[].agentId
string
Yes
The target agent ID.
notAssigned[].toolId
string
Yes
The tool ID.
notAssigned[].error
string
No
Permission or removal error.
failed
object[]
Yes
Removals that failed (e.g. no permission, agent not found, or a tool that cannot be excluded).
failed[].agentId
string
Yes
The target agent ID.
failed[].toolId
string
Yes
The tool ID.
failed[].error
string
No
Permission or removal error.
bulk_assign_tools_to_mcp_gateways
Required RBAC permission: update on the MCP gateway (granted per item)
Input
Parameter
Type
Required
Description
assignments
object[]
Yes
Assignments to create or update for MCP gateways.
assignments[].toolId
string
Yes
The ID of the tool to assign.
assignments[].resolveAtCallTime
boolean
No
When true, resolve credentials and execution target at tool call time. Prefer this for builder flows.
assignments[].credentialResolutionMode
"static" | "dynamic" | "enterprise_managed"
No
assignments[].mcpServerId
string | null
No
Optional MCP server installation to pin the tool to when using static credential resolution.
assignments[].mcpGatewayId
string
Yes
The MCP gateway ID to assign the tool to.
Output
Field
Type
Required
Description
succeeded
object[]
Yes
Assignments that succeeded.
succeeded[].mcpGatewayId
string
Yes
The target MCP gateway ID.
succeeded[].toolId
string
Yes
The tool ID.
succeeded[].error
string
No
Validation or assignment error.
succeeded[].errorCode
"not_found" | "validation_error" | "forbidden"
No
Structured assignment error code.
succeeded[].errorType
string
No
Structured assignment error type.
failed
object[]
Yes
Assignments that failed.
failed[].mcpGatewayId
string
Yes
The target MCP gateway ID.
failed[].toolId
string
Yes
The tool ID.
failed[].error
string
No
Validation or assignment error.
failed[].errorCode
"not_found" | "validation_error" | "forbidden"
No
Structured assignment error code.
failed[].errorType
string
No
Structured assignment error type.
duplicates
object[]
Yes
Assignments skipped because they already existed.
duplicates[].mcpGatewayId
string
Yes
The target MCP gateway ID.
duplicates[].toolId
string
Yes
The tool ID.
duplicates[].error
string
No
Validation or assignment error.
duplicates[].errorCode
"not_found" | "validation_error" | "forbidden"
No
Structured assignment error code.
duplicates[].errorType
string
No
Structured assignment error type.
Guardrails
Tool
Description
Permission
list_peer_messages
List held messages as JSON: {"messages":[{"message_id":"id","expires_at":"ISO-8601"}]}.
None
read_peer_message
Return a held message as text, or refusal feedback with remedy offers.
None
get_openappa_yell
Read a saved OpenAPPA report from one of your own sessions (any session in the organization with log:admin), including its originating user or service account.
List the external consults OpenAPPA recorded for one session, newest first: every annotator, context provider, authority, sanitizer and audience source it asked, with the outcome, the HTTP status, ...
Create a private policy repository from the OpenAPPA configuration template, seed it with the current policy and battery declarations, and start Git sync.
Pull the policy file from the connected Git repository now instead of waiting for the next scheduled sync, so a merged policy or validation pull request takes effect.
Check the review state of an OpenAPPA policy pull request, and once it merges whether Git sync applied it (applied), with an instruction for what to tell the user.
Read why the organization's guardrails policy blocked a tool call, and which remedy plans the policy offers.
None
execute_remedy_plan
Apply a remedy plan that the organization's guardrails policy offers for a blocked call.
None
get_guardrails_server_rules
Read one MCP server's own Guardrails rules: its file in the Git sync policy repository's self-service folder (path, e.g.
None
preview_guardrails_server_rules_change
Check a proposed rules file for one MCP server and return its diff, plus rootChange when appa.toml does not include the self-service folder yet and gains its <folder>/*.toml entry, once for e...
None
propose_guardrails_server_rules_change
Open a pull request on the policy repository that changes one MCP server's rules file, which governs every server whose tools carry its prefix, and adds the self-service folder's <folder>/*.toml ...
None
get_guardrails_server_rules_change_status
Where a pull request propose_guardrails_server_rules_change opened for this server stands: phase (check_pending, check_failed, check_passed, merge_pending, merge_refused, merged, applied or close...
None
list_runtime_credentials
List reusable credential definitions visible to the caller, including whether a personal or organization connection is configured.
Show the person one card in Archestra chat for the tokens these batteries need: what each battery adds, how to make its token, and a picker of the organization's credentials with an option to add a...
The complete policy text. Use it only for a first policy or a full rewrite. Leave it empty when you send edits.
edits
object[] | null
No
Exact-text replacements applied in order to the current policy, each to the result of the one before. Use them to change an existing policy. To insert rules, replace an anchor line with the new rules followed by that same anchor line.
edits[].oldText
string
Yes
Exact text copied from the current policy, including whitespace and line breaks. It must match one place unless replaceAll is true.
edits[].newText
string
Yes
The text that replaces oldText. Empty deletes oldText.
edits[].replaceAll
boolean | null
No
Replace every match of oldText instead of exactly one.
The complete policy text. Use it only for a first policy or a full rewrite. Leave it empty when you send edits.
edits
object[] | null
No
Exact-text replacements applied in order to the current policy, each to the result of the one before. Use them to change an existing policy. To insert rules, replace an anchor line with the new rules followed by that same anchor line.
edits[].oldText
string
Yes
Exact text copied from the current policy, including whitespace and line breaks. It must match one place unless replaceAll is true.
edits[].newText
string
Yes
The text that replaces oldText. Empty deletes oldText.
edits[].replaceAll
boolean | null
No
Replace every match of oldText instead of exactly one.
The MCP server's catalog ID, as the MCP registry shows it.
preview_guardrails_server_rules_change
Required RBAC permission: None
Input
Parameter
Type
Required
Description
mcpServerId
string
Yes
The MCP server's catalog ID, as the MCP registry shows it.
content
string
Yes
The complete file: [policy] with version = 2, then [[policy.tool]] rules for tools that carry the file's tool prefix only and any [[policy.annotator]] they use, named ..
expectedCommit
string
Yes
expectedCommit from get_guardrails_server_rules.
propose_guardrails_server_rules_change
Required RBAC permission: None
Input
Parameter
Type
Required
Description
mcpServerId
string
Yes
The MCP server's catalog ID, as the MCP registry shows it.
content
string
Yes
The complete file: [policy] with version = 2, then [[policy.tool]] rules for tools that carry the file's tool prefix only and any [[policy.annotator]] they use, named ..
expectedCommit
string
Yes
expectedCommit from get_guardrails_server_rules.
summary
string
Yes
What the change does and why, in plain words, for the reviewers.
get_guardrails_server_rules_change_status
Required RBAC permission: None
Input
Parameter
Type
Required
Description
mcpServerId
string
Yes
The MCP server's catalog ID, as the MCP registry shows it.
number
integer
Yes
wait
boolean
No
Return only once the phase moves on from since, settles, or some forty seconds pass.
Map an external identity provider group to a team for SSO team sync: users whose SSO group memberships match are automatically added to or removed from the team on login.
Optional new team description. Pass null to clear an existing description.
roles
string[]
No
Replace the team’s organization role identifiers. Members of this team and its descendants inherit their permissions. Pass [] to clear; omit to leave unchanged.
parent_id
string | null
No
Move the team under this parent. Pass null to move it to the root; omit to leave the hierarchy unchanged.
labels
object[]
No
Replace the team's labels with this set. Pass an empty array to remove all labels. Omit to leave labels unchanged.
labels[].key
string
Yes
labels[].value
string
Yes
Output
Field
Type
Required
Description
team
object
Yes
team.id
string
Yes
The team ID.
team.name
string
Yes
The team name.
team.description
string | null
Yes
The team description, if any.
team.roles
string[]
Yes
Organization role identifiers assigned to the team and inherited by members of this team and its descendants.
team.parentId
string | null
Yes
The parent team ID, or null when this is a root team.
Additional access requirement: Beyond team:read, the caller must be an organization-level team manager (a role granting team:update) or an admin of the target team.
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team to add the member to.
user
string
Yes
The user to add, identified by their user ID or email address. The user must already belong to the organization.
role
"admin" | "member"
No
The role to assign within the team. Defaults to 'member'.
Output
Field
Type
Required
Description
member
object
Yes
member.id
string
Yes
The team membership row ID.
member.teamId
string
Yes
The team the membership belongs to.
member.userId
string
Yes
The ID of the member user.
member.role
"admin" | "member"
Yes
The member's role within the team (admin or member).
member.syncedFromSso
boolean
Yes
Whether this membership is managed by SSO group sync.
Additional access requirement: Beyond team:read, the caller must be an organization-level team manager (a role granting team:update) or an admin of the target team.
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team.
user_id
string
Yes
The ID of the member user to update.
role
"admin" | "member"
Yes
The new role for the member (admin or member).
Output
Field
Type
Required
Description
member
object
Yes
member.id
string
Yes
The team membership row ID.
member.teamId
string
Yes
The team the membership belongs to.
member.userId
string
Yes
The ID of the member user.
member.role
"admin" | "member"
Yes
The member's role within the team (admin or member).
member.syncedFromSso
boolean
Yes
Whether this membership is managed by SSO group sync.
Additional access requirement: Beyond team:read, the caller must be an organization-level team manager (a role granting team:update) or an admin of the target team.
Input
Parameter
Type
Required
Description
team_id
string
Yes
The ID of the team.
user_id
string
Yes
The ID of the member user to remove from the team.
The external identity provider group identifier. Format varies by provider: LDAP Distinguished Name (e.g. cn=admins,ou=groups,dc=example,dc=com), OAuth/OIDC group name from the groups claim, SAML group attribute value, or Azure AD group object ID (GUID). Matched case-insensitively.
Only return items the caller reaches in one of these ways: mine (created by the caller), shared (shared with the caller or one of their teams), org (shared with the whole organization), others (not shared with the caller; visible only through admin access). Omit for everything the caller can read. Use ["mine"] for "my plugins".
shared_with
string[]
No
Only return items whose own permissions grant read to one of these subjects: org (the whole organization), role:, team:, user:, serviceAccount:. Omit for no filtering.
owner_ids
string[]
No
Only return items created by one of these user IDs. Omit for no filtering.
The client the payload targets: claude-code, claude-desktop, codex, copilot-cli, or cursor.
supportedPlatforms
string[]
No
Operating systems the payload supports.
files
object[]
Yes
The plugin's files as { path, content, encoding?, mode? }. Hook configuration bytes are stored verbatim — review them as code, they execute on developer machines.
Disabled plugins are left out of future setup commands; already-installed copies are unaffected.
supportedPlatforms
string[]
No
Operating systems the payload supports.
baseContentHash
string
No
Required when files is provided. Use the current contentHash from get_plugin; the replacement is rejected if newer bytes landed first.
files
object[]
No
WHEN PROVIDED, REPLACES THE PLUGIN'S ENTIRE file set. Omit it to edit only metadata/visibility. Manual plugins only — GitHub-sourced files are read-only. For a small change to one file, prefer edit_plugin over resending every file.
The plugin's current contentHash, as returned by get_plugin. The edit is rejected when the plugin's bytes have moved past it.
path
string
Yes
The plugin file to edit, from the file list returned by get_plugin. Only text (utf8) files are editable — binary files are not.
edits
object[]
No
str_replace edits applied in order to the target file; the whole edit is atomic (any failure leaves the plugin unchanged). Pass either edits or replacementContent, never both.
edits[].old_str
string
Yes
Exact text to replace; must occur exactly once in the target (add surrounding context to disambiguate).
edits[].new_str
string
Yes
Replacement text (may be empty to delete).
replacementContent
string
No
The complete new content of the target file, replacing it outright with no old_str matching. Pass either edits or replacementContent, never both.