API Reference

Quick Start

Start in drie stappen:

1. 1Maak een account aan en genereer een API key via API Keys.
2. 2Voeg content toe via de dashboard of de Ingest API.
3. 3Stel je eerste vraag via POST /v1/ask.

curl -X POST https://axoverna.com/api/v1/ask \
  -H "Authorization: Bearer nx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Which supplement helps with joint pain?"
  }'

Authentication

Alle API requests vereisen een Bearer token in de Authorization header.

Authorization: Bearer nx_live_YOUR_API_KEY

Er zijn drie typen API keys met verschillende toegangsniveaus:

Workspace Scoping

API keys zijn workspace-scoped of account-wide:

Auth: nx_live_ or nx_adm_

Stel een vraag over je productcatalogus. Retourneert een AI-gegenereerd antwoord met bronvermeldingen en confidence score.

Request Parameters

Response

{
  "answer": "Joint Formula with glucosamine, MSM, and vitamin C...",
  "confidence": 0.94,
  "sources": [
    { "type": "product", "id": "JF-001", "title": "Joint Formula", "score": 0.96 },
    { "type": "manual", "page": 12, "title": "Product Guide", "score": 0.91 }
  ],
  "tokens_used": 342,
  "session_id": "sess_abc123"
}

Streaming (SSE)

Wanneer stream: true, retourneert de API een Server-Sent Events stream:

data: {"type":"chunk","text":"Joint Formula"}
data: {"type":"chunk","text":" with glucosamine..."}
data: {"type":"sources","sources":[...]}
data: {"type":"done","tokens_used":342}

Auth: nx_live_ or nx_adm_

Haal ruwe context chunks op uit je kennisbank zonder LLM-call. Ideaal voor externe content generatie: gebruik de chunks als context voor je eigen LLM om blogs, productbeschrijvingen of andere content te genereren.

Request Parameters

Response

{
  "chunks": [
    {
      "item_id": "uuid",
      "title": "Joint Formula",
      "text": "Joint Formula with glucosamine, MSM, and vitamin C supports...",
      "section": "Product Description",
      "page_number": null,
      "chunk_index": 0,
      "score": 0.94,
      "metadata": { "category": "supplements" },
      "domain": "products"
    }
  ],
  "total_chunks": 5,
  "query_log_id": "uuid"
}

Example: Content Generation

# 1. Get context from Axoverna
curl -X POST https://axoverna.com/api/v1/context \
  -H "Authorization: Bearer nx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "joint supplements benefits",
    "top_k": 15
  }'

# 2. Use the chunks as context for your own LLM prompt
#    to generate blogs, product pages, or other content.

Auth: nx_live_ or nx_adm_

Conversational chat met sessigeheugen. Ondersteunt vervolgvragen — de context van vorige berichten wordt automatisch meegenomen. Retourneert altijd een SSE stream.

Request Parameters

SSE Stream Events

event: sources
data: [{"item_id":"uuid","title":"Joint Formula","score":0.96}]

event: delta
data: "Joint Formula bevat glucosamine,"

event: delta
data: " MSM en vitamine C..."

event: followups
data: ["Wat is de aanbevolen dosering?","Is het geschikt voor vegetariërs?","Welke alternatieven zijn er?"]

event: done
data: {"confidence":0.94,"tokens_used":312,"query_log_id":"uuid","session_id":"sess_abc123"}

Two-sided conversation endpoints for chatting between your end-users and a human support agent, with automatic translation per participant language. Messages are stored in their source language and carry a translations JSONB map keyed by ISO language code. Realtime via Server-Sent Events.

Flow at a glance

1. Customer opens the widget on your site — conversation is created automatically.
2. When an agent is online and speaks the customer's language, the conversation is auto-assigned; otherwise it lands in the queue where any agent can claim it.
3. Agent types in their own language; customer sees it translated. Customer types back; agent sees their translation.
4. Realtime updates both sides via SSE. Messages stored in both languages so reloads show the same history.

Auth model

All endpoints require a workspace-scoped API key. nx_live_ keys act as the end-user (customer/widget side); nx_adm_ keys act as the support agent. nx_ing_ keys are not allowed. Rate limits: 30 msg/min per live key, configurable per admin key.

Endpoints

Image attachments

POST /v1/chat/conversations/:id/messages accepts multipart/form-data with an attachment field. PNG, JPEG, or WebP up to 5 MB. Images are stored in Vercel Blob and attached to the message with url, mime, and size metadata. Rendered inline in the inbox and widget bubbles.

Plan gating

Human chat is enabled on paid plans. Free workspaces get 402 PLAN_UPGRADE_REQUIRED. Canceled subscriptions get 402 BILLING_CANCELED. Seats per plan: Starter 1, Professional 3, Growth 5, Business 15, Enterprise unlimited. Translation tokens are metered into the workspace's monthly token usage.

Quick example

# 1. Create a conversation in Spanish
curl -X POST https://axoverna.com/api/v1/chat/conversations \
  -H "Authorization: Bearer nx_adm_..." \
  -H "Content-Type: application/json" \
  -d '{"end_user_language":"es","handoff_mode":"human_first","subject":"Support"}'
# → { "id": "...", "status": "open", ... }

# 2. Send an English agent message — gets auto-translated to Spanish
curl -X POST https://axoverna.com/api/v1/chat/conversations/<id>/messages \
  -H "Authorization: Bearer nx_adm_..." \
  -H "Content-Type: application/json" \
  -d '{"body":"Hello! How can I help?","source_language":"en","sender_type":"agent"}'
# → { ..., "translations": { "en": "Hello! How can I help?", "es": "¡Hola! ¿Cómo puedo ayudar?" } }

# 3. Subscribe to realtime events
curl -N https://axoverna.com/api/v1/chat/conversations/<id>/stream \
  -H "Authorization: Bearer nx_adm_..."

Translation

Target languages are derived from the conversation's end_user_language and the assigned agent's users.languages array. Translation is best-effort — failures don't block the send; a background worker retries and publishes a message.updated SSE event when the missing language arrives. Clients read message.translations[lang], falling back to message.body when a language isn't yet present.

Auth: nx_live_ or nx_adm_

Stuur feedback over een antwoord. Wordt gebruikt om de kwaliteit te meten en het model te verbeteren.

Request Parameters

Response

{ "success": true }

Auth: nx_ing_ or nx_adm_

Voeg items toe aan je knowledge base. Ondersteunt JSON batch (max 100 items) en multipart/form-data voor PDF uploads.

JSON Batch - Request Parameters

JSON Batch - Response

{
  "items_queued": 3,
  "job_ids": ["job_abc", "job_def", "job_ghi"],
  "status": "queued"
}

PDF Upload (multipart/form-data)

curl -X POST https://axoverna.com/api/v1/ingest/items \
  -H "Authorization: Bearer nx_ing_YOUR_KEY" \
  -F "file=@product-guide.pdf" \
  -F "type=manual" \
  -F "title=Product Guide 2025"

Auth: nx_ing_ or nx_adm_

Synchroniseer je volledige catalogus. Items worden vergeleken op external_id. Nieuwe items worden toegevoegd, gewijzigde items geüpdatet, en ontbrekende items verwijderd.

Request Parameters

Response

{
  "to_add": 5,
  "to_update": 2,
  "to_delete": 1,
  "job_ids": ["job_abc", "job_def"],
  "status": "queued"
}

Items die niet in het request voorkomen maar wel in je workspace bestaan worden soft-deleted. Wijzigingen worden gedetecteerd op basis van content, title en metadata.

Auth: nx_ing_ or nx_adm_

Analyseer een URL voordat je een web source aanmaakt. Detecteert automatisch sitemaps, paginaaantallen, SPA-status en stelt de optimale crawl-strategie en sync-planning voor.

Request Parameters

Response

{
  "recommended_mode": "sitemap",
  "sitemap_url": "https://example.com/sitemap.xml",
  "page_count": 47,
  "is_spa": false,
  "suggested_schedule": "daily",
  "suggested_max_pages": 50,
  "internal_links": 12
}

Gebruik de teruggegeven waarden als defaults bij het aanmaken van een web source via het dashboard of API.recommended_mode is een van single, sitemap, of crawl.

Domain Management

Domeinen groeperen je content in logische categorieën (bijv. "products", "manuals", "faq"). Elk domein heeft eigen chunking-instellingen en een zoekgewicht. Gebruik domeinen om queries te filteren en de zoekresultaten te verbeteren.

Auth: nx_adm_

Lijst alle domeinen voor de huidige workspace.

{
  "domains": [
    {
      "slug": "products",
      "label": "Products",
      "description": "Product catalog items",
      "active": true,
      "search_weight": 1.0,
      "split_method": "recursive",
      "chunk_min_tokens": 100,
      "chunk_max_tokens": 600,
      "chunk_overlap": 0.1,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

Auth: nx_adm_

Maak een nieuw domein aan.

Request Parameters

{
  "slug": "manuals",
  "label": "Manuals",
  "active": true,
  "search_weight": 1.0,
  "split_method": "recursive",
  "chunk_min_tokens": 100,
  "chunk_max_tokens": 600
}

Auth: nx_adm_

Update een bestaand domein. Alle velden zijn optioneel — alleen meegegeven velden worden gewijzigd.

Request Parameters

{ "status": "updated" }

Auth: nx_adm_

Verwijder een domein en alle gekoppelde items.

{ "status": "deleted" }

Auth: nx_live_, nx_ing_ or nx_adm_

Controleer de status van een ingestion job. Poll dit endpoint na het aanmaken van items om te weten wanneer de content geïndexeerd is.

Response

{
  "id": "job_abc123",
  "type": "embed_item",
  "status": "done",
  "item_title": "Joint Formula",
  "item_type": "product",
  "attempts": 1,
  "error": null,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:05Z"
}

Mogelijke statussen: queued, running, done, failed.

Widget Embed

Voeg de Axoverna chat widget toe aan je website met een enkel script tag. De widget is volledig aanpasbaar via data-attributen.

• ✓Conversational chat met sessigeheugen — vervolgvragen werken automatisch, context wordt bijgehouden.
• ✓Slimme vervolgvragen — na elk antwoord toont de widget 2–3 suggesties voor vervolgvragen.
• ✓Nieuw gesprek (↻) — gebruikers kunnen de context resetten via de herstart-knop.
• ✓De widget gebruikt automatisch /v1/chat voor conversational mode, met fallback naar /v1/ask.

<script
  src="https://axoverna.com/widget.js"
  data-api-key="nx_live_YOUR_KEY"
  data-api-url="https://axoverna.com"
  data-title="Product Assistant"
  data-placeholder="Ask a question..."
  data-position="bottom-right"
  data-accent="#00D4C8"
></script>

Data Attributes

Error Codes

De API retourneert standaard HTTP status codes. Foutresponses bevatten altijd een error veld.

{
  "error": "Query limit exceeded for this billing period"
}

Rate Limiting

De API gebruikt een sliding window rate limiter. Limieten zijn afhankelijk van je plan en gelden per API key.

Bij overschrijding ontvang je een 429 Too Many Requests response. De Retry-After header geeft aan hoeveel seconden je moet wachten.

Naast rate limiting geldt ook een maandelijks query budget op basis van je plan. Controleer je gebruik via het Usage dashboard.