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

# Inicio rápido

> De cero a su primera solicitud exitosa en la API de Nuvia

Esta guía lo lleva desde cero hasta la **primera solicitud autenticada** en la API de Nuvia.

<Steps>
  <Step title="Tenga acceso a la plataforma Nuvia">
    Necesita una cuenta en una empresa de Nuvia. Las API keys las crea un usuario de la
    empresa y pertenecen a la empresa (el tenant).
  </Step>

  <Step title="Cree una API key">
    Autenticado como usuario, cree una clave con el scope mínimo necesario. Para esta
    guía, use `agents:read` (permite listar agentes).

    ```bash cURL theme={null}
    curl -X POST https://api.nuvia.ai/v1/api-keys \
      -H "Authorization: Bearer $NUVIA_USER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "name": "Inicio rápido", "scopes": ["agents:read"] }'
    ```

    La respuesta trae el token en el campo `accessToken`.

    <Warning>
      El token completo aparece **una única vez**, en la creación. Nuvia no lo almacena y no hay
      forma de recuperarlo después. Cópielo y guárdelo con seguridad ahora. El flujo completo
      (listar, revocar, scopes) está en la [Guía de API key](/es/guia-api-key).
    </Warning>
  </Step>

  <Step title="Haga la primera llamada autenticada">
    Envíe la API key en el header `Authorization: Bearer`. Use aquí el mismo token que copió en
    el paso 2: el valor de `accessToken` es su API key (en los ejemplos abajo, la variable
    `NUVIA_API_KEY`). El ejemplo lista los agentes de su empresa:

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.nuvia.ai/v1/agents \
        -H "Authorization: Bearer $NUVIA_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch("https://api.nuvia.ai/v1/agents", {
        headers: {
          Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
        },
      });

      const { data, meta } = await res.json();
      ```

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

      res = requests.get(
          "https://api.nuvia.ai/v1/agents",
          headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
      )

      body = res.json()
      ```
    </CodeGroup>
  </Step>

  <Step title="Interprete la respuesta">
    Una respuesta exitosa retorna **`200 OK`**. Los endpoints de listado siguen el formato
    `{ data, meta }`, donde `data` trae los elementos y `meta` trae la paginación:

    ```json theme={null}
    {
      "data": [
        { "id": "652f1a9c8b3e4d0012a7f4c1", "name": "Agente de Ventas" }
      ],
      "meta": {
        "page": 1,
        "rowsPerPage": 20,
        "totalCount": 1,
        "hasNextPage": false,
        "hasPreviousPage": false
      }
    }
    ```

    Si recibió `200` y un cuerpo con `data`, su integración está autenticada y funcionando.
  </Step>

  <Step title="Trate los errores comunes">
    * **`401`**: token ausente, inválido, expirado o revocado. Revise el header `Authorization`.
    * **`403`**: la clave es válida, pero no tiene el scope exigido por el endpoint.

    Los formatos de error y las causas están detallados en [Autenticación](/es/autenticacao).
  </Step>
</Steps>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Referencia de la API" icon="code" href="/es/api-reference">
    Explore todos los endpoints, parámetros y respuestas.
  </Card>

  <Card title="Guía de API key" icon="key" href="/es/guia-api-key">
    Scopes, revocación y buenas prácticas de seguridad.
  </Card>
</CardGroup>