Sign in

v4

latestOpenAPI 3.1.1Apache 2.02026-07-31107278570.4 KB
Tool Calling

Execute a tool using a connected account

Executes a tool action using authentication credentials from a connected account. Specify the tool by name and provide required parameters as JSON. The connected account can be identified by ID, or by combination of organization/user, connector, and identifier. Returns the execution result data and a unique execution ID for tracking. Use this endpoint to perform actions like sending emails, creating calendar events, or managing resources in external services.

post/api/v1/execute_tool

Request body

agent_run_idstring

Optional. Customer-supplied identifier grouping multiple tool calls into a single agent run. Useful for correlating logs across an agentic workflow.

connected_account_idstring

Optional. The unique ID of the connected account. Use this to directly identify the connected account instead of using identifier + connector combination.

connectorstring

Optional. The name of the connector/provider (e.g., 'Google Workspace', 'Slack', 'Notion'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed. Use this in combination with identifier to identify the connected account.

identifierstring

Optional. The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). Use this in combination with connector to identify the connected account.

organization_idstring

Optional. The organization ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple organizations.

paramsobject

JSON object containing the parameters required for tool execution. The structure depends on the specific tool being executed.

tool_namestring

Name of the tool to execute

user_idstring

Optional. The user ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple users.

Example request

{
  "agent_run_id": "run_abc123",
  "connected_account_id": "ca_123",
  "connector": "Google Workspace",
  "identifier": "user@example.com",
  "organization_id": "org_123",
  "params": {
    "body": "Hello World",
    "subject": "Hello",
    "to": "user@example.com"
  },
  "tool_name": "send_email",
  "user_id": "user_123"
}

Response

Tool executed successfully with result data and execution ID

dataobject

Free-flowing JSON parameters for the tool execution

execution_idstring

Unique identifier for the tool execution

Example response

{
  "data": {
    "body": "Hello World",
    "subject": "Hello",
    "to": "user@example.com"
  },
  "execution_id": "123456789"
}