RoxanAI API Documentation

Submits a text for policy review and returns the result immediately (synchronous).

curl -X POST https://roxanai.ir/api/v1/moderation/check \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"text": "sample text to check"}'

{"{"}
  "approved": false,
  "violations": ["hate_speech"],
  "confidence": 0.94,
  "rejectionReason": "..."
{"}"}

Queues a text for processing and immediately returns a tracking ID.

curl -X POST https://roxanai.ir/api/v1/webhook/check-async \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"text": "sample text"}'

{"{"}
  "status": "ok",
  "request_id": "a1b2c3...",
  "message": "Request queued..."
{"}"}

Tracks the status of an async request using the ID returned by check-async.

curl https://roxanai.ir/api/v1/webhook/status/a1b2c3 \
  -H "X-API-KEY: your_api_key"

{"{"}
  "requestId": "a1b2c3",
  "status": "Sent",
  "createdAt": "2026-08-30T09:12:00Z",
  "completedAt": "2026-08-30T09:12:04Z",
  "result": {"{"} "approved": true, ... {"}"},
  "errorMessage": null
{"}"}

Paginated history of this account's requests. Requires a tenant panel session, not X-API-KEY — use the panel to view history rather than calling this from your integration.

How results are delivered

Once processing finishes, the payload below is POSTed to your registered webhook URL (no signature/HMAC header in the current implementation).

{"{"}
  "request_id": "a1b2c3",
  "timestamp": "2026-08-30T09:12:04Z",
  "result": {"{"}
    "approved": true,
    "violations": [],
    "confidence": 0.12,
    "rejectionReason": null
  {"}"}
{"}"}

result here matches the same camelCase shape as the direct /api/v1/moderation/check response — approved, violations, confidence, rejectionReason.

After 5 failed attempts the final status becomes Failed and no further retry is made — the result is then only recoverable via GET status/{"{requestId}"}.

Installing the widget on a site

Most integrators never call the endpoints below directly — they just add the widget to their site and it calls these for them. Three ways to do that:

1. Plain HTML — works on any site or CMS

Paste this once, right before the closing </body> tag of your site's template:

<script src="https://roxanai.ir/widget/chatbot.js" data-slug="your-chatbot-slug"></script>

No extra <div> needed — the script draws its own chat bubble and panel. Appearance (colors, bot name, welcome message, position) comes from what's configured in the panel, not from the tag.

2. WordPress plugin

Install the RoxanAI Chatbot plugin, then under Settings → RoxanAI Chatbot enter your server address and slug and activate it. No code editing required.

3. Programmatic iframe — advanced

For opening the chat from your own button or event instead of the default bubble. Load this at page load (not on click):

<script src="https://roxanai.ir/widget/frame.js"
        data-slug="your-chatbot-slug"
        data-position="bottom-right"
        data-hide-bubble="true"></script>

This exposes window.$roxanai.toggle() globally — call it from any button to open or close the chat, with no default bubble shown. data-position is the only thing this tag controls; every other appearance setting still comes from the panel.

Sends a message to the chatbot and returns the full (non-streamed) answer.

curl -X POST https://roxanai.ir/api/v1/knowledgebase/chat/acme-support \
  -H "Content-Type: application/json" \
  -H "Origin: https://acme.com" \
  -d '{"question": "What does the basic plan cost?", "sessionToken": "..."}'

{"{"}
  "answer": "The basic plan is billed monthly...",
  "sessionToken": "sess_...",
  "remainingCredits": 482,
  "noContextFound": false,
  "botMessageId": 9931
{"}"}

Same request, but the answer streams back token by token as Server-Sent Events.

Records a user's thumbs up/down on a bot answer.

Message not found → 404 · success → 200

Creates the tenant's chatbot / knowledge base for the first time.

curl -X POST https://roxanai.ir/api/v1/knowledgebase/setup \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"companyName": "Acme Inc.", "welcomeMessage": "Hi, how can I help?"}'

Returns the current tenant's knowledge base, including every document and all widget settings.

{"{"}
  "id": 12,
  "title": "Pricing FAQ",
  "fileName": "pricing.docx",
  "sourceType": 1,
  "status": 2,
  "chunkCount": 14,
  "wordCount": 860,
  "errorMessage": null,
  "createdAt": "2026-08-20T10:00:00Z",
  "processedAt": "2026-08-20T10:00:42Z"
{"}"}

Issues a new public slug and retires the old one. No body. Response: 200 OK with the updated KnowledgeBaseDto.

Uploads a document to be chunked and embedded into the knowledge base.

curl -X POST https://roxanai.ir/api/v1/knowledgebase/12/upload \
  -H "X-API-KEY: your_api_key" \
  -F "file=@pricing.docx"

{"{"}
  "id": 13,
  "title": null,
  "fileName": "pricing",
  "originalFileName": "pricing.docx",
  "contentType": "application/octet-stream",
  "fileSizeBytes": 48213,
  "wordCount": 0,
  "contentText": null,
  "objectKey": "knowledge-base/{"{userId}"}/12/{"{guid}"}-pricing.docx",
  "sourceUrl": null,
  "sourceType": 1,
  "status": 0,
  "chunkCount": 0,
  "errorMessage": null,
  "createdAt": "2026-08-30T10:18:22Z",
  "processedAt": null
{"}"}

Fetches a web page, extracts its text, and embeds it — synchronously, unlike upload.

{"{"}
  "id": 14,
  "title": "Pricing — Acme",
  "fileName": "Pricing — Acme",
  "contentType": "text/html",
  "wordCount": 340,
  "contentText": "...",
  "sourceUrl": "https://acme.com/pricing",
  "sourceType": 2,
  "status": 2,
  "chunkCount": 9,
  "createdAt": "2026-08-30T10:19:04Z",
  "processedAt": "2026-08-30T10:19:25Z"
{"}"}

Create, edit, or remove a manual text document — content typed directly into the panel rather than uploaded or crawled.

Updates the widget's appearance and copy — colors, position, bot name, fallback messages, lead capture.