COcomposiohq
Tools
Execution

Execute tool

Changed on

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/tools/execute/{tool_slug}

Request

  • Base URL
    https://backend.composio.dev
  • URL
    https://backend.composio.dev/api/v3/tools/execute/{tool_slug}
  • Auth
    • API key in header x-api-key
    • or API key in header x-user-api-key

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

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 the pinned version ("00000000_00") when omitted.

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

{
  "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

session_infounknown
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

  • 36ea9a0cd3fbRevision changes
    • breaking

      removed subschema #1 subschema #2 from the request property oneOf list

    • info

      added subschema #1 subschema #2 to the request property oneOf list

  • da0faa944f15Revision changes
    • breaking

      removed the enum value hosted_account of the request property /

    • info

      added the new instant_account enum value to the request property /