Overview
Executes a specific tool from your stack with the provided input parameters. This endpoint allows you to programmatically invoke any enabled tool in your stack.
Endpoint
POST https://api.toolrouter.ai/v1/stacks/{stack_id}/tools/{tool_id}/invoke
Authentication
This endpoint requires an API key. Include it in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Path Parameters
The unique identifier of the stack containing the tool
The unique identifier of the tool to invoke
Request Body
Input parameters for the tool execution. The structure depends on the specific tool being invoked.
Use the List Stack Tools endpoint to see the required input schema for each tool.
Response
The response format varies depending on the tool being invoked. Each tool returns its results in a JSON object.
The output from the tool execution. Structure varies by tool.
Example Requests
Send Email via Gmail
Create Linear Issue
Search Emails
Example Responses
Gmail Send Email Response
{
"result": {
"message_id": "18c2e1b2f3a4d5e6",
"status": "sent",
"recipients": ["john@example.com", "jane@example.com"],
"timestamp": "2024-01-25T15:30:00Z"
}
}
Linear Create Issue Response
{
"result": {
"id": "issue_123abc456def",
"number": 42,
"title": "Fix login bug",
"url": "https://linear.app/company/issue/TEAM-42",
"state": "Backlog",
"team": {
"id": "team_abc123",
"name": "Engineering"
},
"created_at": "2024-01-25T15:30:00Z"
}
}
Gmail Search Emails Response
{
"result": {
"emails": [
{
"id": "email_123",
"subject": "Weekly team meeting",
"from": "john@example.com",
"snippet": "Let's discuss the project updates...",
"date": "2024-01-24T10:00:00Z"
},
{
"id": "email_456",
"subject": "Meeting notes",
"from": "john@example.com",
"snippet": "Here are the notes from yesterday's meeting...",
"date": "2024-01-23T14:30:00Z"
}
],
"total_count": 2
}
}
Error Handling
When a tool fails to execute properly, the response will include error details:
{
"detail": "Invalid email address format"
}
- Invalid parameters: Tool input doesn’t match the required schema
- Authentication failure: Tool credentials are missing or invalid
- Service unavailable: The external service (Gmail, Linear, etc.) is temporarily unavailable
- Rate limiting: Too many requests to the external service
- Permission denied: Credentials don’t have necessary permissions
Best Practices
Always validate your input parameters before making the request:
def validate_email_input(tool_input):
required_fields = ["to", "subject", "body"]
for field in required_fields:
if field not in tool_input:
raise ValueError(f"Missing required field: {field}")
if not isinstance(tool_input["to"], list):
raise ValueError("'to' field must be a list of email addresses")
return True
# Validate before invoking
try:
validate_email_input(email_data["tool_input"])
response = requests.post(endpoint, headers=headers, json=email_data)
except ValueError as e:
print(f"Invalid input: {e}")
Error Handling
Implement proper error handling for tool invocations:
import requests
from requests.exceptions import RequestException
def invoke_tool_safely(stack_id, tool_id, tool_input, headers):
try:
response = requests.post(
f"https://api.toolrouter.ai/v1/stacks/{stack_id}/tools/{tool_id}/invoke",
headers=headers,
json={"tool_input": tool_input},
timeout=30
)
if response.status_code == 200:
return response.json()
elif response.status_code == 500:
error_detail = response.json().get("detail", "Unknown error")
print(f"Tool execution failed: {error_detail}")
return None
else:
print(f"API error: {response.status_code} - {response.text}")
return None
except RequestException as e:
print(f"Request failed: {e}")
return None
Retry Logic
Implement retry logic for temporary failures:
import time
import random
def invoke_tool_with_retry(stack_id, tool_id, tool_input, headers, max_retries=3):
for attempt in range(max_retries):
result = invoke_tool_safely(stack_id, tool_id, tool_input, headers)
if result is not None:
return result
if attempt < max_retries - 1:
# Exponential backoff with jitter
delay = (2 ** attempt) + random.uniform(0, 1)
time.sleep(delay)
return None
Error Responses
Invalid tool input parameters
{
"detail": "Invalid input parameters for tool gmail_send_email"
}
Invalid or missing API key
{
"detail": "Unauthorized"
}
Stack or tool not found
{
"detail": "Stack not found"
}
{
"detail": "Tool gmail_send_email not found in stack"
}
Rate limit exceeded
{
"detail": "Too many requests"
}
500 Internal Server Error
Tool execution failed
{
"detail": "Gmail API authentication failed"
}
