API Reference

La Public API es multi-tenant: cada petición debe incluir el Workspace ID y una API Key válida. Usa los ejemplos siguientes como plantilla y ajusta tus propios IDs.

Requisitos previos

Workspace habilitado y su identificador (WORKSPACE_ID).
API Key emitida por Agents Studio (X-API-Key). Las de producción empiezan con sk_prod_ y las de sandbox con sk_sbx_.
URL base del entorno, sin el prefijo de versión: los ejemplos agregan /v1.
- Producción: https://api-prod.studio.getsupervisor.ai
- Sandbox: https://sandbox.agents.studio.getsupervisor.ai
Node.js 18+ si usarás el SDK TypeScript.

Define estas variables de entorno para reutilizarlas en los ejemplos:

export API_BASE_URL="https://api-prod.studio.getsupervisor.ai"
export WORKSPACE_ID="00000000-1111-2222-3333-444455556666"
export API_KEY="sk_prod_..."

Instala el SDK o prepara tu cliente HTTP

TypeScript SDK
cURL / HTTP

Instala el paquete oficial y añade tipos de Fetch si los necesitas (para Node.js < 18).

npm install @getsupervisor/agents-studio-sdk

// src/client.ts
import { createClient } from '@getsupervisor/agents-studio-sdk';

const client = createClient({
  baseUrl: process.env.API_BASE_URL!,
  workspaceId: process.env.WORKSPACE_ID!,
  apiKey: process.env.API_KEY!,
  // Opcional: configura reintentos o timeout personalizados
  retry: { maxRetries: 2, baseDelayMs: 300 },
});

export default client;

Configura tus variables y usa curl (o tu HTTP client favorito) agregando los headers requeridos.Empieza comprobando conectividad contra GET /v1/health, el único endpoint que no pide autenticación:

curl -sS "$API_BASE_URL/v1/health"

Y con eso resuelto, cualquier llamada real lleva los dos headers:

curl -sS "$API_BASE_URL/v1/agents?limit=1" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Lista tus agentes

TypeScript SDK
cURL

import client from "./client";

const agents = await client.agents.list({ limit: 5 });

for (const item of agents.data) {
  console.log(`${item.agentId}: ${item.name} (${item.agentType})`);
}

if (agents.meta.hasNext) {
  const nextPage = await agents.next();
  console.log(`Siguiente página: ${nextPage.meta.page}`);
}

curl -sS "$API_BASE_URL/v1/agents?limit=5" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Incluye parámetros adicionales (filter, page) usando api-query-builder si lo necesitas.

Crea un agente

TypeScript SDK
cURL

import client from './client';

const draft = await client.agents.create({
  name: 'Onboarding Bot',
  agentType: 'chat',
  description: 'Acompaña a nuevos usuarios en su primera semana.',
});

console.log('Draft creado:', draft.agentId, draft.status);

curl -sS "$API_BASE_URL/v1/agents" \
  -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding Bot",
    "agentType": "chat",
    "description": "Acompaña a nuevos usuarios en su primera semana."
  }'

Conecta la tool `voice.calls`

Al crear una conexión de voz, la API rellena automáticamente descriptionUsage y usageExample con la guía estándar definida en voice-call-usage.template.ts.

El cuerpo no lleva workspaceId: el workspace lo resuelve la API Key. Y como la validación corre en modo estricto, cualquier campo que el contrato no declare hace fallar la petición con 400 (property workspaceId should not exist).

TypeScript SDK
cURL

import client from './client';

const agentId = '11111111-2222-3333-4444-555555555555';

const connection = await client.tools.connect('voice.calls', {
  agentId,
  metadata: { reason: 'demo-outbound', expectedOutcome: 'confirmar cita' },
});

console.log(connection.status); // connected

console.log(connection.descriptionUsage);
console.log(connection.usageExample);

curl -sS "$API_BASE_URL/v1/tools/voice.calls/connections" \
  -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: voice-conn-$(date +%s)" \
  -d '{
    "agentId": "11111111-2222-3333-4444-555555555555",
    "metadata": { "reason": "demo-outbound", "expectedOutcome": "confirmar cita" }
  }' | jq '{descriptionUsage, usageExample}'

La respuesta incluye la guía en descriptionUsage y usageExample, útil para mostrar la recomendación en tu UI. en tu UI.

Ejecuta `voice.calls.startCall`

TypeScript SDK
cURL

import client from './client';

await client.tools.execute('voice.calls', {
  agentId: '11111111-2222-3333-4444-555555555555',
  action: 'startCall',
  args: {
    to: '+525500000000',
    metadata: { reason: 'confirmar cita', customerId: 'cust-789' },
  },
});

curl -sS "$API_BASE_URL/v1/tools/voice.calls/execute" \
  -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: voice-exec-$(date +%s)" \
  -d '{
    "agentId": "11111111-2222-3333-4444-555555555555",
    "action": "startCall",
    "args": {
      "to": "+525500000000",
      "metadata": { "reason": "confirmar cita", "customerId": "cust-789" }
    }
  }'

Manejo de errores e idempotencia

TypeScript SDK
cURL

import client from "./client";
import {
  HttpError,
  TimeoutError,
  NetworkError,
} from "@getsupervisor/agents-studio-sdk";

try {
  await client.tools.execute(
    "voice.calls",
    {
      agentId: "11111111-2222-3333-4444-555555555555",
      action: "startCall",
      args: { to: "+525500000000" },
    },
    { idempotencyKey: `voice-${Date.now()}` },
  );
} catch (err) {
  if (err instanceof HttpError) {
    console.error("HTTP error", err.status, err.body);
  } else if (err instanceof TimeoutError) {
    console.error("Timeout, reintenta más tarde");
  } else if (err instanceof NetworkError) {
    console.error("Error de red, reintento automático");
  } else {
    throw err;
  }
}

Reutiliza el encabezado Idempotency-Key para evitar duplicar ejecuciones.
Un 409 es un conflicto de estado, no un reintento: la conexión ya existe para esa tool y ese agente, o todavía no está connected. Resuélvelo antes de volver a llamar.
Los códigos 4xx señalan validaciones fallidas (payload incompleto, agente sin voz, etc.).

Un 429 no se reintenta del lado del servidor. Lo emite el throttler antes de llegar al handler, así que la operación no se ejecutó y no hay evento del workspace que revisar: el reintento con backoff exponencial te toca a ti. El límite se cuenta por API Key —no por workspace ni por IP—, así que repartir el tráfico entre varias keys es lo que cambia el resultado, no cambiar de IP.

curl -i "$API_BASE_URL/v1/tools/voice.calls/execute" \
  -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: voice-exec-idem-0001" \
  -d '{ "agentId": "11111111-2222-3333-4444-555555555555", "action": "startCall", "args": { "to": "+525500000000" } }'

Recursos adicionales

La especificación completa está disponible en openapi/public-api.yaml.
Cada entorno publica además el contrato que tiene desplegado en GET {API_BASE_URL}/v1/openapi.yaml. Es un endpoint público (no pide API Key ni Workspace ID) y es la fuente que conviene usar para generar clientes o mocks:
curl -sS "$API_BASE_URL/v1/openapi.yaml" -o openapi.yaml
Consulta la tabla de scopes en el SDK (apps/public-api/sdk/js/README.md) para validar los permisos necesarios por endpoint.
Para plantillas MCP vinculadas a voice.calls, revisa el archivo docs/mcp/tools_execution.md del repositorio.

Explora el OpenAPI

Lee el contrato completo y genera clientes o mocks desde la especificación oficial.

Empezar

Referencia de endpoints

Agentes

Herramientas del agente

Telefonía

Webhooks

MCP

Requisitos previos

Instala el SDK o prepara tu cliente HTTP

Lista tus agentes

Crea un agente

Conecta la tool `voice.calls`

Ejecuta `voice.calls.startCall`

Manejo de errores e idempotencia

Recursos adicionales

Explora el OpenAPI

​Requisitos previos

​Instala el SDK o prepara tu cliente HTTP

​Lista tus agentes

​Crea un agente

​Conecta la tool voice.calls

​Ejecuta voice.calls.startCall

​Manejo de errores e idempotencia

​Recursos adicionales

Explora el OpenAPI

Requisitos previos

Instala el SDK o prepara tu cliente HTTP

Lista tus agentes

Crea un agente

Conecta la tool `voice.calls`

Ejecuta `voice.calls.startCall`

Manejo de errores e idempotencia

Recursos adicionales