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

# Quickstart

> Tu primera llamada disparada por API en menos de 5 minutos.

## 1. Crea tu API key

Entra a [app.ryvo.so/developers](https://app.ryvo.so/developers), click en **Nueva API key**, ponle un nombre (ej. "n8n producción") y copia el token completo.

<Warning>
  El token se muestra **una sola vez**. Si lo pierdes, revoca esa key y crea una nueva.
</Warning>

## 2. Encuentra el `agent_id`

En el portal entra a **Agentes** y copia el ID del agente que quieres usar. Tiene formato `agent_xxx...`.

## 3. Dispara tu primera llamada

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.ryvo.so/v1/calls \
    -H "Authorization: Bearer ryvo_live_..." \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{
      "agent_id": "agent_8801kpabc123",
      "to": "+5215555550100",
      "metadata": {
        "lead_name": "Juan García",
        "deal_id": "OPP-42"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.ryvo.so/v1/calls", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.RYVO_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      agent_id: "agent_8801kpabc123",
      to: "+5215555550100",
      metadata: { lead_name: "Juan García", deal_id: "OPP-42" },
    }),
  })

  const call = await response.json()
  console.log(call.id) // call_conv_01abcdef
  ```

  ```python Python theme={null}
  import os, uuid, requests

  response = requests.post(
      "https://api.ryvo.so/v1/calls",
      headers={
          "Authorization": f"Bearer {os.environ['RYVO_API_KEY']}",
          "Content-Type": "application/json",
          "Idempotency-Key": str(uuid.uuid4()),
      },
      json={
          "agent_id": "agent_8801kpabc123",
          "to": "+5215555550100",
          "metadata": {"lead_name": "Juan García", "deal_id": "OPP-42"},
      },
  )

  call = response.json()
  print(call["id"])  # call_conv_01abcdef
  ```
</CodeGroup>

Respuesta esperada:

```json theme={null}
{
  "id": "call_conv_01abcdef",
  "agent_id": "agent_8801kpabc123",
  "to": "+5215555550100",
  "status": "initiated",
  "created_at": "2026-04-30T18:32:11.123Z"
}
```

## 4. (Opcional) Recibe el resultado por webhook

Si quieres saber cómo terminó la llamada, configura un webhook en `app.ryvo.so/developers`. Vas a recibir un `POST` con eventos como:

```json theme={null}
{
  "id": "evt_abc123",
  "type": "call.completed",
  "created_at": "2026-04-30T18:35:42.123Z",
  "data": {
    "id": "call_conv_01abcdef",
    "agent_id": "agent_8801kpabc123",
    "status": "completed",
    "duration_seconds": 211,
    "transcript_summary": "El lead aceptó agendar una demo para el 5 de mayo a las 11am.",
    "started_at": "2026-04-30T18:32:13Z",
    "ended_at": "2026-04-30T18:35:44Z"
  }
}
```

Lee [Webhooks → Verificar firmas](/webhooks/signature-verification) para validar que el evento viene de Ryvo y no de un atacante.

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Manejo de errores" icon="triangle-exclamation" href="/errors">
    Códigos que devolvemos y qué significa cada uno.
  </Card>

  <Card title="Idempotencia" icon="repeat" href="/idempotency">
    Cómo no disparar 2 llamadas si reintentas.
  </Card>

  <Card title="Eventos" icon="bolt" href="/webhooks/overview">
    Lista completa de eventos y sus payloads.
  </Card>

  <Card title="Referencia API" icon="code" href="/api-reference">
    Todos los endpoints en detalle.
  </Card>
</CardGroup>