Quickstart

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

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

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

cURL

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.

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.

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:

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

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:

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

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.

Next steps

API reference

Explore all endpoints, parameters, and responses.

API key guide

Scopes, revocation, and security best practices.

Getting started

Guides

Next steps

API reference

API key guide

​Next steps

API reference

API key guide

Next steps