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.

TypeScript SDK
cURL

import client from './client';

const workspaceId = client.workspace.get() ?? process.env.WORKSPACE_ID!;
const agentId = '11111111-2222-3333-4444-555555555555';

const connection = await client.tools.connect('voice.calls', {
  workspaceId,
  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 '{
    "workspaceId": "'$WORKSPACE_ID'",
    "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', {
  workspaceId: process.env.WORKSPACE_ID!,
  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 '{
    "workspaceId": "'$WORKSPACE_ID'",
    "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',
    {
      workspaceId: process.env.WORKSPACE_ID!,
      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.
Las respuestas 409/429 indican que la llamada será reintentada internamente; revisa los eventos del workspace.
Los códigos 4xx señalan validaciones fallidas (payload incompleto, agente sin voz, etc.).

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-123" \
  -d '{ "workspaceId": "'$WORKSPACE_ID'", "agentId": "...", "action": "startCall", "args": { "to": "+5255" } }'

Recursos adicionales

La especificación completa está disponible en openapi/public-api.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