Inicio rápido

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

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).

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).

cURL

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.

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.

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:

curl https://api.nuvia.ai/v1/agents \
  -H "Authorization: Bearer $NUVIA_API_KEY"

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

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

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()

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:

{
  "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.

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.

Próximos pasos

Referencia de la API

Explore todos los endpoints, parámetros y respuestas.

Guía de API key

Scopes, revocación y buenas prácticas de seguridad.

Primeros pasos

Guías

Próximos pasos

Referencia de la API

Guía de API key

​Próximos pasos

Referencia de la API

Guía de API key

Próximos pasos