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

# Início rápido

> Do zero à sua primeira requisição bem-sucedida na API da Nuvia

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

<Steps>
  <Step title="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).
  </Step>

  <Step title="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).

    ```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": "Início rápido", "scopes": ["agents:read"] }'
    ```

    A resposta traz o token no campo `accessToken`.

    <Warning>
      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](/guia-api-key).
    </Warning>
  </Step>

  <Step title="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:

    <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 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:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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](/autenticacao).
  </Step>
</Steps>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Referência da API" icon="code" href="/api-reference">
    Explore todos os endpoints, parâmetros e respostas.
  </Card>

  <Card title="Guia de API Key" icon="key" href="/guia-api-key">
    Escopos, revogação e boas práticas de segurança.
  </Card>
</CardGroup>