Conversation API

Request example

{
  "user_id": "usr-42",
  "message": "Help me choose a starter plan and explain how it differs from Pro.",
  "image_b64": null,
  "image_mime": null,
  "voice_b64": null,
  "voice_mime": null,
  "persona": {
    "name": "Nora",
    "gender": "female",
    "sociality": "ambivert",
    "archetypes": ["Sage", "Explorer"],
    "role": "You are the private AI assistant for Acme. You answer product and support questions, rely on the official knowledge base, keep replies concise, and escalate billing disputes to a human."
  }
}

cURL · bash

curl -X POST "https://<PRIVATE_DEPLOYMENT_URL>/api/v1/conversation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: req-usr-42-001" \
  -H "Content-Type: application/json" \
  -d '{
  "user_id": "usr-42",
  "message": "Help me choose a starter plan and explain how it differs from Pro.",
  "image_b64": null,
  "image_mime": null,
  "voice_b64": null,
  "voice_mime": null,
  "persona": {
    "name": "Nora",
    "gender": "female",
    "sociality": "ambivert",
    "archetypes": ["Sage", "Explorer"],
    "role": "You are the private AI assistant for Acme. You answer product and support questions, rely on the official knowledge base, keep replies concise, and escalate billing disputes to a human."
  }
}'

JavaScript / fetch · ts

const API_URL = 'https://<PRIVATE_DEPLOYMENT_URL>';
const API_KEY = 'YOUR_API_KEY';

const body = {
  "user_id": "usr-42",
  "message": "Help me choose a starter plan and explain how it differs from Pro.",
  "image_b64": null,
  "image_mime": null,
  "voice_b64": null,
  "voice_mime": null,
  "persona": {
    "name": "Nora",
    "gender": "female",
    "sociality": "ambivert",
    "archetypes": ["Sage", "Explorer"],
    "role": "You are the private AI assistant for Acme. You answer product and support questions, rely on the official knowledge base, keep replies concise, and escalate billing disputes to a human."
  }
};

const response = await fetch(`${API_URL}/api/v1/conversation`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'req-usr-42-001'
  },
  body: JSON.stringify(body)
});

console.log(response.status, await response.json());

Python / requests · py

import requests

API_URL = 'https://<PRIVATE_DEPLOYMENT_URL>'
API_KEY = 'YOUR_API_KEY'

payload = {
  "user_id": "usr-42",
  "message": "Help me choose a starter plan and explain how it differs from Pro.",
  "image_b64": null,
  "image_mime": null,
  "voice_b64": null,
  "voice_mime": null,
  "persona": {
    "name": "Nora",
    "gender": "female",
    "sociality": "ambivert",
    "archetypes": ["Sage", "Explorer"],
    "role": "You are the private AI assistant for Acme. You answer product and support questions, rely on the official knowledge base, keep replies concise, and escalate billing disputes to a human."
  }
}

resp = requests.post(
    f"{API_URL}/api/v1/conversation",
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json',
        'Idempotency-Key': 'req-usr-42-001',
    },
    json=payload,
    timeout=30,
)
print(resp.status_code, resp.json())