Skip to navigation

Tool Studio

View as Markdown

The Tool Studio entities live under /platform/extensions. They are the same objects you build in Tool Studio, so you can create and update them from code instead of the Tool Studio UI.

EntityPathWhat it is
HTTP Connectors/platform/extensions/http-connectorsBase URL and credentials for an external API
HTTP Actions/platform/extensions/http-actionsOne request to that API
Scripts/platform/extensions/scriptsPython code run as an action
Compound Actions/platform/extensions/compound-actionsSeveral steps run without the user
Data Types/platform/extensions/data-typesA business object and how to look it up
Conversational Processes/platform/extensions/conversational-processesThe user-facing flow: slots and steps
Plugins/platform/extensions/pluginsWhat triggers it, who can use it, and what it runs
Webhook Listeners/platform/extensions/listenersReceives events from an external system
MCP Servers/platform/extensions/mcp-workspace/serversA remote MCP server and its tools

Each collection supports list, create, get and update. There is no delete.

Build in order

A resource has to exist before anything that refers to it. Create them in this order, and keep the id from each response:

HTTP connector → HTTP action or script → compound action → data type → conversational process → plugin
webhook listener → system plugin
HTTP connector → MCP server

Send writes one at a time. Writes aren’t transactional: if a later step fails, the resources you already created stay, so reuse them or clean them up in Tool Studio.

id or name?

Most references take the other resource’s id. Two take a name:

FieldSend
connector_id (HTTP actions, MCP servers)the HTTP connector’s id
action_id and dynamic_lookup (http_action, compound_action, script_action)the action’s id
conversational_plugin_body_config_uuidthe conversational process’s id
listener_idthe webhook listener’s id
action_name inside compound action workflow_stepsthe action’s signature.name
A custom slot or argument type, {"custom": ...}the data type’s name, for example u_PurchaseOrder

A 400 with REFERENCE_VALIDATION_FAILED usually means a name was sent where an id belongs, or the other way around.

How updates work

PATCH /platform/extensions/<collection>/{id} takes a JSON merge-patch:

  • A field you leave out keeps its stored value, and null clears it.
  • Nested objects merge field by field.
  • Lists of objects merge row by row instead of being replaced. To remove or reorder rows, read the document and send the whole list back.
  • Lists of strings, Data Mapper expressions (*_bender, input_mapper, output_mapper), JSON schemas, workflow_steps and resolver_methods are replaced whole.
  • Fields that are alternatives to each other, such as allow_all and allow_emails, switch when you send the other one. Sending both is rejected.
  • Send version.num from your last read with a change_description. If the document changed since then, the update returns 409; read it again and retry.

Data Mapper fields in these collections take the short form, for example {"po_number": "data.po_number"}. Rules such as condition, skip_execution_condition and allowlist_rule are DSL. See MWDSL & Bender.

Reading

  • Reads return every field. Unset fields come back as empty values: "", 0, false, [] or null.
  • Secrets come back redacted and can’t be read back.
  • To copy a resource, remove id, updated_time, updated_by and version.num from the read body before you send it as a create.

There is no endpoint that runs an action or a plugin. After you create one, test it in Tool Studio, or try the plugin in chat as someone on its allow list.