COcomposiohq
Tools

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

Request

  • Base URL
    https://backend.composio.dev
  • URL
    https://backend.composio.dev/api/v3.1/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 latest published version ("latest") 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"
      }
    ]
  },
  "custom_connection_data": {
    "authScheme": "OAUTH2",
    "toolkitSlug": "github",
    "val": {
      "access_token": "secret-token"
    }
  },
  "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_infoobject nullable

Optional session information for tools that return session context

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

  • 98956f31abf3Revision changes
    • breaking

      added the new required request property /

    • breaking

      added the new required request property /

    • breaking

      added the new required request property /

    • breaking

      the request property / became not nullable

    • breaking

      the request property // became not nullable

    • breaking

      removed subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 subschema #6 subschema #7 subschema #8 subschema #9 subschema #10 subschema #11 from the request property oneOf list

    • breaking

      the request property type changed from string to no type

    • breaking

      the request property type changed from no type to object

    • breaking

      the response's property type changed from no type to object for status

    • info

      api operation id postV3_1ToolsExecuteByToolSlug removed and replaced with postToolsExecuteByToolSlug

    • info

      api tag Execution removed

    • info

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

    • info

      added the non-success response with the status

  • ad121cf38fe0Revision changes
    • info

      the request property /// became optional

    • info

      the request property /// became optional