Tool API

The Tool API allows external systems to invoke tools directly and receive JSON responses. This is designed for widgets, backend integrations, and API consumers who need to call tools without going through an agent.

Authentication

This endpoint supports both API Key and Signed JWT authentication.

API Key (server-to-server):

curl -X POST https://service.ensembleapp.ai/api/tools/{toolId}/invoke \
  -H "x-api-key: sk_your_api_key" \
  -H "x-tenant-id: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{"args": {"a": 5, "b": 3}}'

Signed JWT (frontend integrations):

curl -X POST https://service.ensembleapp.ai/api/tools/{toolId}/invoke \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{"args": {"a": 5, "b": 3}}'

See Authentication for details on creating API keys, signing JWTs, and choosing the right method.

Endpoint

Invoke Tool

POST /api/tools/:toolId/invoke

Request Body:

{
  "args": { ... },              // Optional: tool arguments (defaults to empty object)
  "dataContext": { ... },       // Optional: key/value context data
  "version": "latest"           // Optional: 'latest' (default), 'published', or version number
}

Success Response:

{
  "success": true,
  "data": { ... },              // Tool invocation result
  "debug": {
    "executionTime": 42         // Execution time in milliseconds
  }
}

Error Response (tool invocation failed):

{
  "success": false,
  "error": {
    "message": "JavaScript tool execution failed",
    "details": ["Error details here"],
    "code": "EXECUTION_ERROR"
  }
}

Examples

Calculator Tool

curl -X POST https://service.ensembleapp.ai/api/tools/calculator/invoke \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_abc123..." \
  -H "x-tenant-id: my-tenant" \
  -d '{"args": {"a": 5, "b": 3}}'

{
  "success": true,
  "data": 8,
  "debug": {
    "executionTime": 12
  }
}

With Version Selection

Invoke a specific version of a tool:

# Invoke published version
curl -X POST .../api/tools/my-tool/invoke \
  -d '{"args": {"input": "test"}, "version": "published"}'

# Invoke specific version number
curl -X POST .../api/tools/my-tool/invoke \
  -d '{"args": {"input": "test"}, "version": 1}'

With Data Context

Pass contextual data the tool can access:

curl -X POST .../api/tools/order-processor/invoke \
  -d '{
    "args": {"orderId": "12345"},
    "dataContext": {
      "environment": "production",
      "region": "US-West"
    }
  }'

Error Responses

Status	Error	Description
401	`Invalid or disabled API key`	Check API key and tenant ID
404	`Tool not found`	Tool doesn't exist, wrong version, or not in tenant
500	`Tool invocation failed`	Server-side error during invocation

Note: Tool invocation errors (e.g., JavaScript runtime errors) return status 200 with success: false in the response body, allowing you to distinguish between infrastructure failures (5xx) and tool logic failures.

On this page