Execute tool

Execute a specific tool operation with provided arguments and authentication. This is the primary endpoint for integrating with third-party services and executing tools. You can provide structured arguments or use natural language processing by providing a text description of what you want to accomplish.

post/api/v3.1/tools/execute/{tool_slug}

Path parameters

tool_slugstring required

The tool slug to execute

Headers

x-llm-gateway-headersstring

JSON object containing custom headers to pass to LLM providers (OpenAI, Bedrock, etc.)

Example:{"x-custom-header": "value", "authorization": "Bearer token"}

Request body

connected_account_idstring

Unique identifier for the connected account to use for authentication

entity_idstring

Deprecated: please use user_id instead. Entity identifier for multi-entity connected accounts (e.g. multiple repositories, organizations)

user_idstring

User id for multi-user connected accounts (e.g. multiple users, organizations)

versionstring

Tool version to execute (defaults to "00000000_00" if not specified)

argumentsobject

Key-value pairs of arguments required by the tool (mutually exclusive with text)

textstring

Natural language description of the task to perform (mutually exclusive with arguments)

allow_tracingboolean nullable

Deprecated. Enable debug tracing for tool execution (useful for debugging)

Example request

{
  "connected_account_id": "ca_1a2b3c4d5e6f",
  "entity_id": "repo-123",
  "user_id": "user-123",
  "version": "latest",
  "custom_auth_params": {
    "base_url": "https://api.example.com",
    "parameters": [
      {
        "name": "x-api-key",
        "value": "secret-key",
        "in": "header"
      }
    ]
  },
  "arguments": {
    "repository": "octocat/Hello-World",
    "workflow_id": "main.yml",
    "ref": "main",
    "inputs": {
      "environment": "production"
    }
  },
  "text": "Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment"
}

Response

Successfully executed action and received response

dataobject required

Tool execution output data that varies based on the specific tool

errorstring nullable required

Error message if the tool execution was not successful (null if successful)

successfulboolean required

Indicates if the tool execution was successful

{"stackTrail":"paths:/api/v3.1/tools/execute/{tool_slug}:post:responses:200:content:application/json:schema:properties:session_info","oasType":"schema","type":"unknown","description":"Optional session information for tools that return session context","example":{"session_id":"session-12345","expires_at":"2023-01-01T13:00:00Z"},"nullable":true}

log_idstring

Unique identifier for the execution log (useful for debugging and support)

Example response

{
  "data": {
    "run_id": 12345678,
    "status": "queued",
    "created_at": "2023-01-01T12:00:00Z",
    "html_url": "https://github.com/octocat/Hello-World/actions/runs/12345678"
  },
  "successful": true,
  "session_info": {
    "session_id": "session-12345",
    "expires_at": "2023-01-01T13:00:00Z"
  },
  "log_id": "log_1a2b3c4d5e6f"
}

Changes

Changed in 4 of the 61 revisions of this API.5

Jun 23, 2026ad121cf38fe02See the full diff
- ○
  the request property custom_connection_data/oneOf[subschema #11]/val/client_id became optional
  request-property-became-optional
- ○
  the request property custom_connection_data/oneOf[subschema #11]/val/client_secret became optional
  request-property-became-optional
May 23, 2026b7d6dfeda6161See the full diff
- ○
  the endpoint scheme security CookieAuth was removed from the API
  api-security-removed
May 11, 202623348819b35e1See the full diff
- ○
  added the new optional request property custom_connection_data/oneOf[subschema #1]/val/extra_token_data
  new-optional-request-property
May 5, 202652c71f747c651See the full diff
- ○
  endpoint added
  endpoint-added

Full history