Skip to main content
POST
/
v1
/
tools
/
{toolId}
/
execute
Ejecutar una acción de la tool para el agente indicado
curl --request POST \
  --url https://agents.studio.getsupervisor.ai/v1/tools/{toolId}/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-workspace-id: <x-workspace-id>' \
  --data '
{
  "workspaceId": "11111111-1111-4111-8111-111111111111",
  "agentId": "22222222-2222-4222-8222-222222222222",
  "action": "scheduleCall",
  "args": {
    "proposed_datetime_iso": "2025-07-02T15:00:00-06:00",
    "notes": "Confirmar demo",
    "metadata": {
      "leadId": "lead-987"
    }
  }
}
'
{
  "status": "ok",
  "result": {
    "status": "scheduled",
    "scheduledFor": "2025-07-02T21:00:00Z",
    "referenceId": "arn:aws:states:us-east-1:123456789012:execution:schedule-call:demo-001"
  },
  "metadata": {
    "proposedAt": "2025-07-02T21:00:00Z",
    "scheduledStart": "2025-07-02T21:00:00Z",
    "scheduledEnd": "2025-07-02T21:30:00Z",
    "scheduledStartLocal": "2025-07-02T16:00:00-05:00",
    "scheduledEndLocal": "2025-07-02T16:30:00-05:00",
    "timezone": "America/Mexico_City",
    "windowSource": "standard_hours",
    "windowDayOfWeek": "wednesday"
  },
  "toolId": "b4fec2ee-5b69-4f13-8502-0ba34d1a6c98",
  "toolAgentConnectionId": "cb917332-1d51-4791-af92-35a714c916a4",
  "providerRef": "retell-agent-001"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-workspace-id
string<uuid>
required

Identificador del workspace multi-tenant.

​
Idempotency-Key
string
required

Clave única por operación para asegurar idempotencia en requests mutativos.

Required string length: 16 - 128

Path Parameters

​
toolId
string
required

Identificador interno de la tool (snake_case)

Body

application/json
​
workspaceId
string<uuid>
required

Workspace que origina la ejecución.

​
agentId
string<uuid>
required

Agente en contexto para la ejecución.

​
action
string
required

Acción solicitada dentro de la tool (create, syncAgent, etc.).

Minimum string length: 1
​
args
object

Payload validado según el contrato de la tool.

Response

Ejecución completada de forma síncrona

​
status
enum<string>
required

Resultado alto nivel de la operación.

Available options:
ok,
queued,
error
​
toolId
string
required
​
result
object

Respuesta específica del adapter.

​
metadata
object
​
toolAgentConnectionId
string<uuid> | null

Conexión utilizada para la ejecución, cuando aplica.

​
providerRef
string | null

Identificador del recurso manipulado en el proveedor externo.

​
message
string | null

Mensaje adicional (warnings, información del adapter).