Execute a tool
POST /v1/execute with the real request fields and synchronous or asynchronous envelopes.
POST /v1/execute validates the canonical schema, resolves a connection, invokes the adapter, and records the execution.
Request
curl "$EYEBALL_EXECUTOR_URL/v1/execute" \
-H "Authorization: Bearer $EYEBALL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: reservation:res_42:email" \
--data '{
"tool": "gmail.send_email",
"userId": "demo_user",
"input": {
"to": ["guest@example.com"],
"subject": "Reservation confirmed",
"body": "Friday at 7 PM for four guests."
},
"mode": "sync"
}'| Field | Required | Meaning |
|---|---|---|
tool | Yes | Canonical dotted or reversible restricted name |
userId | Yes | External user whose connection is selected |
input | Yes | Canonical JSON object |
mode | No | sync or async; defaults from tool annotations |
connectionId | No | Explicit scoped connection |
The idempotency key is an HTTP header, not a JSON field.
When the bearer key is user-pinned, userId must match that pin. The same rule applies to X-Eyeball-User-Id when that header is present.
Succeeded response
{
"executionId": "exe_01JZ6WA0Q73ZQ5B51SRYB6M4Z8",
"tool": "gmail.send_email",
"toolVersion": "1.0.0",
"catalogVersion": "1.1",
"status": "succeeded",
"output": {
"messageId": "msg_123"
},
"latencyMs": 84
}Failed response
A synchronous tool failure is a terminal HTTP 200 response, not a transport error:
{
"executionId": "exe_01JZ6WA0Q73ZQ5B51SRYB6M4Z8",
"tool": "gmail.send_email",
"toolVersion": "1.0.0",
"catalogVersion": "1.1",
"status": "failed",
"error": {
"code": "provider_unavailable",
"message": "The provider is temporarily unavailable.",
"retryable": true
},
"latencyMs": 84
}Cancelled response
A synchronous request can race with cancellation, and an idempotent replay can resolve to an already-cancelled execution. Like a tool failure, cancellation is a terminal HTTP 200 execution response:
{
"executionId": "exe_01JZ6WA0Q73ZQ5B51SRYB6M4Z8",
"tool": "gmail.send_email",
"toolVersion": "1.0.0",
"catalogVersion": "1.1",
"status": "cancelled",
"error": {
"code": "execution_cancelled",
"message": "Execution was cancelled before provider dispatch.",
"retryable": false
},
"latencyMs": 19,
"cancellation": {
"dispatchMayHaveBegun": false
}
}Pending or running response
{
"executionId": "exe_01JZ6WA0Q73ZQ5B51SRYB6M4Z8",
"tool": "voice-agents.start_agent_call",
"toolVersion": "1.0.0",
"catalogVersion": "1.1",
"status": "pending"
}Poll pending work at GET /v1/executions/:id.
Async mode returns HTTP 202 with pending. Replaying the same async request while its execution is in flight returns HTTP 202 with the latest pending or running state. A synchronous replay waits for the original execution and returns its terminal succeeded, failed, or cancelled HTTP 200 response.