Skip to main content

API Overview

This section documents the public APIs for running conversations and managing configuration.

nambikk.ai is the execution and decision layer for conversational AI. The API exposes that runtime in a controlled, auditable way.

Base URL​

https://your-api-domain.com/api/v1

Required Headers​

All API requests require a tenant identifier:

tenant-id: your-tenant-id

Recommended headers:

user-id: external-user-id
x-request-id: your-trace-id

user-id is used as a fallback if you do not pass context.identity.user_id in the Converse API.

Authentication​

Authentication is currently handled at the tenant boundary using the tenant-id header. If you deploy behind an API gateway, enforce authentication there.

Content Type​

Use JSON for all request bodies unless otherwise noted:

Content-Type: application/json

Response Conventions​

Conversation endpoints return:

{
  "conversation_id": "uuid",
  "response": {
    "message": "string",
    "phase": "string",
    "awaiting_input": true,
    "options": [{"id": "string", "label": "string"}]
  },
  "state": {
    "status": "active",
    "capability": "capability-slug"
  }
}

Management endpoints return objects or { items: [] } lists.