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

# Quickstart

> From zero to your first successful request to the Nuvia API

This guide takes you from scratch to your **first authenticated request** to the Nuvia API.

<Steps>
  <Step title="Get access to the Nuvia platform">
    You need an account in a company on Nuvia. API keys are created by a company user and belong
    to the company (the tenant).
  </Step>

  <Step title="Create an API key">
    Authenticated as a user, create a key with the minimum scope you need. For this guide, use
    `agents:read` (allows listing agents).

    ```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": "Quickstart", "scopes": ["agents:read"] }'
    ```

    The response includes the token in the `accessToken` field.

    <Warning>
      The full token appears **only once**, at creation. Nuvia doesn't store it, and there's no way
      to retrieve it later. Copy it and store it securely now. The full flow (listing, revoking,
      scopes) is in the [API key guide](/en/guia-api-key).
    </Warning>
  </Step>

  <Step title="Make your first authenticated call">
    Send the API key in the `Authorization: Bearer` header. Use here the same token you copied in
    Step 2: the `accessToken` value is your API key (in the examples below, the `NUVIA_API_KEY`
    variable). The example lists your company's agents:

    <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="Interpret the response">
    A successful response returns **`200 OK`**. List endpoints follow the `{ data, meta }` format,
    where `data` holds the items and `meta` holds the pagination:

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

    If you received `200` and a body with `data`, your integration is authenticated and working.
  </Step>

  <Step title="Handle common errors">
    * **`401`**: token missing, invalid, expired, or revoked. Check the `Authorization` header.
    * **`403`**: the key is valid, but doesn't have the scope required by the endpoint.

    Error formats and causes are detailed in [Authentication](/en/autenticacao).
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/en/api-reference">
    Explore all endpoints, parameters, and responses.
  </Card>

  <Card title="API key guide" icon="key" href="/en/guia-api-key">
    Scopes, revocation, and security best practices.
  </Card>
</CardGroup>