Overview

Base URL for production: https://chatbot.najahapps.com/api

All endpoints accept and return application/json (UTF-8). The chat endpoint also supports Server-Sent Events when stream: true is set in the request body. All responses include a session_id you should echo back on subsequent turns to keep conversation context coherent.

Authentication

The public chat endpoints require no authentication. They are intended for embedding on third-party sites and are rate-limited per client IP (see Rate limits). If your integration needs higher limits or domain-scoped admin write access, contact the NNU team for an account.

The chatbot honors X-Forwarded-For for rate-limit attribution, so requests routed through a reverse proxy will be metered against the original client IP. Make sure your proxy forwards that header.

Rate limits

Public API requests are metered per client IP over two fixed windows. The limits are configured by the university administration and may change without notice; the numbers below are the defaults, not a guarantee.

LimitWindowDefault
Per-minute60 seconds, fixed20 requests
Per-hour3600 seconds, fixed200 requests

Exceeding either limit returns HTTP 429 Too Many Requests with a JSON body of {"detail": "Rate limit exceeded. Please try again later."}. Counters reset at the end of their window and no Retry-After header is sent, so back off instead of polling: the per-minute window clears within a minute, the per-hour window within the hour.

POST/chat

The primary endpoint. Sends a user message and receives a grounded, cited answer.

Request body

FieldTypeRequiredDescription
messagestringyesThe user's question. Max 500 characters by default.
session_idstringnoOpaque session id returned by a previous call. Pass it back to preserve conversation context (last 10 turns).
lang_hintstringno"ar" or "en". Influences answer language. If omitted, the bot auto-detects from the message script.
domainstringnoDomain slug (e.g. "fmhs"). Scopes retrieval to that domain's documents. If omitted, all globally-visible content is used.
streambooleannoIf true, response is an SSE stream — see streaming below.

Response (non-streaming)

{
  "session_id": "c3d8d550-3eee-4682-b75c-d1dacba11c33",
  "answer":     "The FMHS Optometry Clinic is located in New Campus, Building 19, Room 19B1020...",
  "intent":     "contact_info",
  "confidence": 0.92,
  "citations": [
    {
      "title":          "Medical Support for FMHS Students",
      "document_id":    14,
      "chunk_id":       231,
      "effective_date": null,
      "source_url":     "https://fmhs.najah.edu/en/students/students-support/medical-support/",
      "snippet":        "Optometry Clinic delivers specialized diagnostic and treatment service..."
    }
  ],
  "handoff":           null,
  "tool_calls_made":   ["search_contacts", "search_knowledge_base"],
  "tokens_used":       3151,
  "clarification_needed": null,
  "follow_up_suggestions": []
}

Examples

curl -X POST https://chatbot.najahapps.com/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the admission requirements for the MD program?",
    "domain":  "fmhs",
    "lang_hint": "en"
  }'

POST/chat · streaming

Set stream: true in the request body and the server returns an text/event-stream response. Each event is one of:

Event typePayloadDescription
session{ session_id }Sent first; capture this to reuse on the next turn.
intent{ intent, confidence }Once intent classification completes.
status{ message }Human-readable progress hint (e.g. "Thinking...").
tool_call{ tools: [name, ...] }Names of tools the agent is about to invoke.
token{ content: string }Partial answer text. Append to your buffer in order received.
doneFull ChatResponseFinal event with the complete answer + citations + tool_calls_made.
error{ message }Sent on safety refusal or unrecoverable error.
// EventSource doesn't support POST, so use fetch + ReadableStream.
const resp = await fetch("https://chatbot.najahapps.com/api/chat", {
  method:  "POST",
  headers: { "Content-Type": "application/json", "Accept": "text/event-stream" },
  body: JSON.stringify({
    message: "How do I book a counseling appointment?",
    domain:  "fmhs",
    stream:  true,
  }),
});

const reader = resp.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
let answer = "";

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  let idx;
  while ((idx = buffer.indexOf("\n\n")) !== -1) {
    const raw = buffer.slice(0, idx);
    buffer = buffer.slice(idx + 2);
    if (!raw.startsWith("data: ")) continue;
    const evt = JSON.parse(raw.slice(6));

    if (evt.type === "token")    answer += evt.content;
    if (evt.type === "tool_call") console.log("tools:", evt.tools);
    if (evt.type === "done")     console.log("final:", evt.answer);
  }
}

GET/domains/public

Lists all active domains (faculties / units) you can scope the chat to. Each entry's slug is what you pass as domain in /chat.

curl https://chatbot.najahapps.com/api/domains/public

# response:
[
  { "slug": "fmhs", "name_en": "Faculty of Medicine and Health Sciences",
                    "name_ar": "كلية الطب وعلوم الصحة" }
]

GET/domain/{slug}/config

Public widget config for a domain. Use this if you're rendering your own UI (rather than embedding the iframe widget) and want to honor the domain's preferred title, subtitle, and brand color.

curl https://chatbot.najahapps.com/api/domain/fmhs/config

# response:
{
  "slug": "fmhs",
  "name_en": "Faculty of Medicine and Health Sciences",
  "name_ar": "كلية الطب وعلوم الصحة",
  "widget_title_en":    "FMHS Assistant",
  "widget_title_ar":    "مساعد كلية الطب",
  "widget_subtitle_en": "Ask about programs, policies, and student support",
  "widget_subtitle_ar": "اسأل عن البرامج والسياسات ودعم الطلاب",
  "primary_color":      "#1d3e6b"
}

GET/doc/{document_id}

Retrieves the full text of a cited document. Use this to render a "source card" inline when a user clicks one of the citations from a chat response. Only documents whose status = "active" are exposed.

The response includes the full document text plus per-chunk character offsets:

curl https://chatbot.najahapps.com/api/doc/14

# response (truncated):
{
  "id": 14,
  "title": "Medical Support for FMHS Students",
  "language": "en",
  "raw_text": "# Medical Support for FMHS Students\n\nSeveral medical-support resources...",
  "effective_date": null,
  "source_url": "https://fmhs.najah.edu/en/students/students-support/medical-support/",
  "chunks": [
    { "id": 230, "index": 0, "start_offset": 0,   "end_offset": 420 },
    { "id": 231, "index": 1, "start_offset": 350, "end_offset": 870 }
  ]
}

Schemas

Citation

FieldTypeDescription
titlestringDisplay name of the source document.
document_idintID for GET /doc/{id}.
chunk_idintThe specific chunk whose content was retrieved.
effective_datestring?ISO date if the document carries an effective date.
source_urlstring?Origin URL on najah.edu, when known.
snippetstring?First ~160 characters of the chunk — useful for source cards.

Handoff

If the bot's safety filter blocks a request, the response carries a handoff object pointing the user to a human contact (e.g. the admissions office). Otherwise null.

FieldTypeDescription
typestringCurrently always "contact".
unitstring?Office name (e.g. "Admissions Office").
phonestring?Phone number.
emailstring?Email.

Error codes

HTTPWhenBody
400Validation failed (e.g. message too long).{"detail": "..."}
404Unknown domain slug or document id.{"detail": "..."}
429Rate limit exceeded.{"detail": "Rate limit exceeded..."}
500Unexpected server error. Safe to retry.{"detail": "Internal server error"}

Best practices

Questions about access, rate limits, or domain-scoped accounts: info@najah.edu.