> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getsupervisor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Guía práctica para consumir la Public API con TypeScript (SDK oficial) o llamadas HTTP/cURL.

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

## Requisitos previos

* Workspace habilitado y su identificador (`WORKSPACE_ID`).
* API Key emitida por Agents Studio (`X-API-Key`).
* URL base del entorno (prod: `https://api-prod.studio.getsupervisor.ai/v1`).
* Node.js 18+ si usarás el SDK TypeScript.

Define estas variables de entorno para reutilizarlas en los ejemplos:

```bash theme={null}
export API_BASE_URL="https://api-prod.studio.getsupervisor.ai/v1"
export WORKSPACE_ID="00000000-1111-2222-3333-444455556666"
export API_KEY="sk_live_..."
```

## Instala el SDK o prepara tu cliente HTTP

<Tabs>
  <Tab title="TypeScript SDK">
    Instala el paquete oficial y añade tipos de Fetch si los necesitas (para Node.js \< 18).

    ```bash theme={null}
    npm install @getsupervisor/agents-studio-sdk
    ```

    ```ts theme={null}
    // 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;
    ```
  </Tab>

  <Tab title="cURL / HTTP">
    Configura tus variables y usa `curl` (o tu HTTP client favorito) agregando
    los headers requeridos.

    ```bash theme={null}
    curl -sS "$API_BASE_URL/status" \
      -H "X-API-Key: $API_KEY" \
      -H "X-Workspace-Id: $WORKSPACE_ID"
    ```
  </Tab>
</Tabs>

## Lista tus agentes

<Tabs>
  <Tab title="TypeScript SDK">
    ```ts theme={null}
    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}`);
    }
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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.
  </Tab>
</Tabs>

## Crea un agente

<Tabs>
  <Tab title="TypeScript SDK">
    ```ts theme={null}
    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);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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."
      }'
    ```
  </Tab>
</Tabs>

## 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`.

<Tabs>
  <Tab title="TypeScript SDK">
    ```ts theme={null}
    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);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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.
  </Tab>
</Tabs>

## Ejecuta `voice.calls.startCall`

<Tabs>
  <Tab title="TypeScript SDK">
    ```ts theme={null}
    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' },
      },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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" }
        }
      }'
    ```
  </Tab>
</Tabs>

## Manejo de errores e idempotencia

<Tabs>
  <Tab title="TypeScript SDK">
    ```ts theme={null}
    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;
      }
    }
    ```
  </Tab>

  <Tab title="cURL">
    * 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.).

    ```bash theme={null}
    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" } }'
    ```
  </Tab>
</Tabs>

## Recursos adicionales

* La especificación completa está disponible en [`openapi/public-api.yaml`](/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.

<Card title="Explora el OpenAPI" icon="terminal" href="/openapi/public-api.yaml">
  Lee el contrato completo y genera clientes o mocks desde la especificación
  oficial.
</Card>