Início rápido

Este guia leva você da estaca zero até a primeira requisição autenticada na API da Nuvia.

Tenha acesso à plataforma Nuvia

Você precisa de uma conta em uma empresa na Nuvia. As API Keys são criadas por um usuário da empresa e pertencem à empresa (o tenant).

Crie uma API Key

Autenticado como usuário, crie uma chave com o escopo mínimo de que você precisa. Para este guia, 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": "Início rápido", "scopes": ["agents:read"] }'

A resposta traz o token no campo accessToken.

O token completo aparece uma única vez, na criação. A Nuvia não o armazena e não há como recuperá-lo depois. Copie e guarde com segurança agora. O fluxo completo (listar, revogar, escopos) está no Guia de API Key.

Faça a primeira chamada autenticada

Envie a API Key no header Authorization: Bearer. Use aqui o mesmo token que você copiou no Step 2 — o valor de accessToken é a sua API Key (nos exemplos abaixo, a variável NUVIA_API_KEY). O exemplo lista os agentes da sua 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 a resposta

Uma resposta bem-sucedida retorna 200 OK. Endpoints de listagem seguem o formato { data, meta } — data com os itens e meta com a paginação:

{
  "data": [
    { "id": "652f1a9c8b3e4d0012a7f4c1", "name": "Agente de Vendas" }
  ],
  "meta": {
    "page": 1,
    "rowsPerPage": 20,
    "totalCount": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

Se você recebeu 200 e um corpo com data, sua integração está autenticada e funcionando.

Trate os erros comuns

401 — token ausente, inválido, expirado ou revogado. Confira o header Authorization.
403 — a chave é válida, mas não tem o escopo exigido pelo endpoint.

Os formatos de erro e as causas estão detalhados em Autenticação.

Próximos passos

Referência da API

Explore todos os endpoints, parâmetros e respostas.

Guia de API Key

Escopos, revogação e boas práticas de segurança.

Primeiros passos

Guias

Próximos passos

Referência da API

Guia de API Key

​Próximos passos

Referência da API

Guia de API Key

Próximos passos