API & Authentication

The Navieo SDK connects directly to Navieo's backend API — no proxy route or server-side setup needed. Authentication is handled via your publishable API key.

How It Works

When a user asks a question in the chat widget, the SDK sends the query directly to Navieo's API:

SDK sends request — The widget POSTs the user's query, current route, and chat mode to https://api.navieo.io/api/guide
Authentication — Your publishable API key is sent via the x-api-key header
RAG pipeline — Navieo embeds the query, searches your synced sitemap and docs, and generates tour steps
Response — The SDK receives structured tour steps and renders the visual walkthrough

You don't need to configure any AI models, API keys for AI providers, or embedding pipelines. Navieo manages all of this.

Setting Up Authentication

Get your API key from the dashboard and add it to your environment:

NEXT_PUBLIC_NAVIEO_PUBLISHABLE_KEY=nv_pub_your_key_here

The SDK reads NEXT_PUBLIC_NAVIEO_PUBLISHABLE_KEY automatically and includes it in every request. The NEXT_PUBLIC_ prefix is required by Next.js to expose it to browser code. For non-Next.js frameworks, set the variable in whatever way your bundler supports (e.g., Vite uses VITE_ prefix).

API Key Types

Your API key from the dashboard serves two purposes:

Usage	Environment Variable	Where
SDK requests (browser)	`NEXT_PUBLIC_NAVIEO_PUBLISHABLE_KEY`	Client-side — sent with chat widget queries
CLI push (terminal)	`NAVIEO_SECRET_KEY`	Server-side — used when running `navieo push`

Each app has two keys: a publishable key (nv_pub_*) safe for client-side usage, and a secret key (nv_secret_*) for server-side write operations like navieo push. Never expose the secret key to browsers.

Response Format

The API returns JSON matching this structure:

{
  "steps": [
    {
      "route": "/settings",
      "elementId": "profile-section",
      "selector": {
        "cssSelector": "#profile-section",
        "navieoId": "profile-section",
        "ariaLabel": "Profile settings",
        "text": "Profile"
      },
      "tooltipTitle": "Open Profile",
      "tooltipText": "Click here to access your profile settings.",
      "action": "highlight"
    }
  ],
  "answer": "Here's how to update your profile:"
}

In Ask mode, the response has empty steps and a text answer. In Guide mode, steps are populated and the widget launches a visual tour.

The selector object supports multiple strategies for finding elements — CSS selectors, aria labels, and text content — falling back gracefully if one doesn't match.

Security

Your API key identifies your application and controls access to your app's data
Each key is scoped to a single app — it can only access that app's sitemap and embeddings
The backend validates the API key on every request and resolves the app from it
Rate limiting is applied per-app to prevent abuse