Tool Execution API (Preview)
Run one or more Galadri tools directly over HTTP. Preview.
Use the Tool Execution API when your backend, job runner, or provider webhook already knows which tool actions it wants to execute. This is the direct HTTP surface for batched tool work outside the conversational Chat API.
Preview endpoint
`/v1/tools/execute` is available for early integrations, but it is still in preview and may change before general availability.
When to use this instead of chat
Use chat when you want the model to decide whether tools are needed. Use the Tool Execution API when your application already knows the exact tool actions it wants to run.
Endpoint
/v1/tools/executeRequest Context
| Field | Type | Description |
|---|---|---|
agent_id | string | Required. Agent slug or ID used for tool allowlisting, policy, and credential resolution. |
end_user_id | UUID | Galadri's internal end-user UUID. Optional unless a requested tool requires end-user context. |
session_id | UUID | Optional. Useful for continuity, audit linkage, and resolving end-user context from an existing session. |
channel | string | Optional caller metadata for adapters or future channel-aware policy. |
Partial failures are normal
Mixed batches can succeed per action. If one action needs end-user context and another does not, Galadri returns a per-action error rather than failing the whole request.
POST /v1/tools/execute
Submit one or more tool actions in a single request. Independent actions can be batched together to reduce network round trips and keep orchestration simple on your side.
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | string | Agent slug or ID used for tool allowlisting, policy, and credential resolution. |
actionsrequired | ToolAction[] | One or more tool actions. Each action contains a canonical tool slug and args object. |
end_user_id | UUID | Galadri's internal end-user UUID. Optional unless a requested tool requires end-user context. |
session_id | UUID | Optional. If provided, Galadri resolves end-user context from the session when possible. |
channel | string | Optional caller metadata for adapters or future channel-aware policy. |
curl -X POST https://api.galadri.com/v1/tools/execute \
-H "Authorization: Bearer gld_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "main-agent",
"end_user_id": "5361a22a-d4a9-4c57-b98b-c70c72f5865f",
"actions": [
{ "tool": "gas-price-lookup", "args": { "location": "Buffalo, NY" } },
{ "tool": "traffic", "args": { "action": "nearby_incidents", "location": "Battery Park, New York City" } }
]
}'{
"results": [
{ "tool": "gas-price-lookup", "status": "success", "data": { "stations": [] } },
{ "tool": "traffic", "status": "success", "data": { "incidents": [] } }
]
}Provider Webhook Tools
Some voice providers can call Galadri tools through an explicit server webhook instead of routing every turn through chat. This is useful for persistent provider agents that need a stable tool endpoint.
Recommended server tool shape
| Field | Type | Description |
|---|---|---|
Tool name | string | execute_actions |
Webhook URL | string | https://api.galadri.com/v1/comms/voice/tool-call/execute_actions |
Session transport | header or JSON body | Pass the active call session as X-Call-Session-Id or call_session_id. |
Webhook auth | secret header | Send X-Galadri-Tool-Secret and match it to ELEVENLABS_TOOL_WEBHOOK_SECRET. |
{
"call_session_id": "{{galadri_call_session_id}}",
"actions": [
{
"tool": "gas-price-lookup",
"args": { "location": "Pittsburgh, New York" }
}
]
}Related Docs
For the model-facing batching pattern, see Meta-tool Pattern. For direct email, SMS, and call endpoints, see Communications API. For channel setup and credential behavior, see Communications.