Skip to content

API & External/Internal Interfaces (ICD)

Field Value
Document ID DA-API-001
Pillar Software Engineering
Standard Alignment Interface Control Document (ICD)
Status Active / Synchronized with Codebase
Last Updated 2026-11-21
Source of Truth app/main.py, app/dashboard.py, app/management.py, app/admin_accounts.py, app/ai_management.py, app/documents.py, app/knowledge_review.py, app/knowledge_authority.py, app/knowledge_graph.py, app/knowledge_intake.py, app/broadcasts.py, app/ticket_notifications.py, app/analytics.py, app/assistant.py, app/cloudflare_ai.py, app/identity.py, app/media.py, app/handoff.py, app/quota.py, app/worker.py

Dirman Assist exposes 103 HTTP route handlers split across two FastAPI services—13 routes on the private api service (app/main.py, port 8080, loopback 127.0.0.1:18081) and 90 routes (plus static /assets) on the public dashboard service (app/dashboard.py, port 8082, loopback 127.0.0.1:18082, Traefik HTTPS https://assist.p3mdi.id)—alongside outbound HTTP clients for WAHA and Google/Cloudflare AI and 7 PostgreSQL-backed asynchronous worker queues.


2. Private API Service (app/main.py — 13 Routes)

Section titled “2. Private API Service (app/main.py — 13 Routes)”
  • Base URL: http://127.0.0.1:18081 (host) / http://api:8080 (Docker private network)
  • Global Limits: Streamed body cap 65,536 bytes (413 on overflow); interactive OpenAPI docs disabled (docs_url=None, redoc_url=None, openapi_url=None).
  • Authentication: Authorization: Bearer <token> (max 512 chars, matched by SHA-256 digest in credentials joined with active members). Per-member limit: 10 requests/minute (429).
Method Path Auth / Scope Request / Query Contract Response & Status Codes
GET /health Public (internal/loopback) None 200: status, database, ai_configured, members_configured, outbound_enabled, public_intake
POST /webhooks/waha x-webhook-hmac (HMAC-SHA512) WAHA message / message.any JSON event (session='default', timestamp ±300s) 202: {"status": "queued" | "duplicate" | "taken_over" | "ignored"}; 401 invalid HMAC/timestamp; 429/503 rate/queue cap
POST /v1/assist Bearer + assist {"question": str (1..4000)} 202: {"id": "api:<uuid>", "status": "queued" | "duplicate"}; 429/503
GET /v1/jobs/{jid} Bearer + assist + can_access Path jid: str 200: {id, member_id, state, answer, created_at}; 404 if missing or foreign member
POST /v1/tickets Bearer + tickets:write {"subject": str (1..200), "description": str (1..4000)} 201: Created tickets row + ticket_open_events
GET /v1/tickets Bearer + tickets:read Query limit: int = 50 (clamped 1..100) 200: List of tickets (owner-filtered for member, all for support/admin)
GET /v1/tickets/{tid} Bearer + tickets:read + can_access Path tid: int 200: {ticket, events} (member role receives only action/status detail keys)
PATCH /v1/tickets/{tid} Bearer + tickets:write + support|admin TicketUpdate: status?, priority?, category?, due_at?, expected_version?, assigned_to?, note? 200: Updated ticket; 409 stale expected_version; 422 invalid assignee
POST /v1/members Bearer + admin scope & role {"name", "email?", "phone?" (7-16 digits), "role", "active"} 201: Created members row; 409 duplicate phone
PATCH /v1/members/{mid}/disable Bearer + admin Path mid: UUID 200: {"status": "disabled"}; 422 self-disable attempt
DELETE /v1/credentials/{digest} Bearer + admin Path digest: str (SHA-256 hex) 200: {"status": "revoked"}
POST /v1/faq Bearer + admin FaqIn: question, answer, source, aliases?, approved?, category?, expires_at? 201: Created faq row
GET /v1/faq Bearer + assist None 200: Up to 100 ELIGIBLE faq rows (source_case_id removed)

3. Management Dashboard Service (app/dashboard.py + 11 Routers — 90 Routes)

Section titled “3. Management Dashboard Service (app/dashboard.py + 11 Routers — 90 Routes)”
  • Base URL: https://assist.p3mdi.id (public Traefik HTTPS) / http://127.0.0.1:18082 (loopback)
  • Auth Model: Cookie __Host-dirman_session (HttpOnly; Secure; SameSite=Strict) required on all /manage/api/* endpoints except /login and /reset-password. All mutations (POST/PUT/PATCH/DELETE) enforce Origin == DASHBOARD_ORIGIN and X-CSRF-Token matching __Host-dirman_csrf.
  • Body Limit: 65,536 bytes globally (dashboard_body_limit), except POST /manage/api/documents which permits up to 32 MiB (33,554,432 bytes) under a single-slot PDF_REQUEST_SLOT lock (429 if busy).

3.1 Shell, Auth, Overview & Core Management (app/dashboard.py — 19 Routes + /assets)

Section titled “3.1 Shell, Auth, Overview & Core Management (app/dashboard.py — 19 Routes + /assets)”
Method Path Auth Purpose & Key Contract
GET / Public Serves app/dashboard_static/index.html
GET /reset Public Serves index.html for #TOKEN password-reset flow
GET /assets/* Public StaticFiles mount for self-hosted CSS, JS, Manrope-Variable.ttf, SVG, PNG
GET /health Public SELECT 1 DB check -> {"status": "ok"}
POST /manage/api/login Same-Origin {username, password} -> 5/10m throttle -> sets session + CSRF cookies
GET /manage/api/me Admin Returns {id, name, role}
POST /manage/api/logout Admin + CSRF Deletes session row and clears cookies
POST /manage/api/password Admin + CSRF {current_password, new_password (12..128)} -> updates hash, clears all sessions/resets
GET /manage/api/overview Admin Query days (7|30) -> KPI counts, WIB daily trend, status breakdown, KB categories, api:8080/health, latest 10 management_events
GET /manage/api/knowledge Admin Query q, category, publication (''|published|draft|expired), manual_only -> up to 200 faq rows
POST /manage/api/knowledge Admin + CSRF Article (FaqIn + optional source_document_id, source_page) -> 201
PUT /manage/api/knowledge/{fid} Admin + CSRF Edits manual FAQ (409 if document_id IS NOT NULL—must edit via PDF endpoint)
DELETE /manage/api/knowledge/{fid} Admin + CSRF Deletes manual FAQ (409 if owned by PDF)
GET /manage/api/tickets Admin Query q, status, priority, category, assignee (me|unassigned|UUID), requester, overdue, sort (newest|oldest|priority|due) -> up to 200 tickets
GET /manage/api/tickets/{tid} Admin Returns {ticket, events} with owner_name
PATCH /manage/api/tickets/{tid} Admin + CSRF Delegates to main.update_ticket with expected_version optimistic check + audit
GET /manage/api/members Admin Query q, staff_only, active -> up to 200 members
POST /manage/api/members Admin + CSRF Delegates to main.add_member + audit (201)
PATCH /manage/api/members/{mid} Admin + CSRF Updates profile/role/active; prevents self-demotion & last-admin disable; revokes sessions/resets if demoted/contact changed
POST /manage/api/knowledge-search Admin + CSRF {question, context[]} -> executes live retrieval.retrieve() diagnostics without AI or WhatsApp calls

3.2 Cases, Handoff, CRM, Bulk Tickets & Password Recovery (app/management.py — 17 Routes)

Section titled “3.2 Cases, Handoff, CRM, Bulk Tickets & Password Recovery (app/management.py — 17 Routes)”
Method Path Purpose & Key Contract
POST /manage/api/ticket-bulk Atomic update of 1..50 tickets with per-ticket versions map (409 aborts entire transaction)
GET /manage/api/members/{mid}/account Returns dashboard_accounts metadata (id, username, enabled, created_at)
PUT /manage/api/members/{mid}/account Creates or updates dashboard login for active admin; revokes sessions on username/enabled change
POST /manage/api/members/{mid}/reset-link Issues single-use 30m reset link (https://assist.p3mdi.id/reset#TOKEN, max 5/hour/target)
POST /manage/api/reset-password Public + Same-Origin: consumes {token, new_password (12..128)}, updates password, revokes all sessions
GET /manage/api/cases Query q, status (handoff|mine|unassigned|due_soon|overdue|waiting_staff|waiting_user|has_media|open|closed) -> up to 200 prioritized inbox rows
GET /manage/api/cases/{cid} Query before cursor (100 msgs/page) -> case, member, messages, staff_replies, notes, tickets, customer_context, staff_members, canned_responses
GET /manage/api/cases/{cid}/messages/{mid}/media Streams private media_bytes (inline or ?download=1 attachment)
GET /manage/api/cases/{cid}/handoff Lightweight 5s polling state (status, handoff_active, staff_owner, last_message, note_count, replies[])
POST /manage/api/cases/{cid}/handoff {action: "claim" | "release" | "resume"} -> manages human takeover and bot resumption
POST /manage/api/cases/{cid}/replies {id: UUID, body} -> idempotently queues staff_replies (202 Accepted) if case claimed by caller
PATCH /manage/api/cases/{cid} Updates status, priority, category, tags (max 8 normalized tags), staff_owner
POST /manage/api/cases/{cid}/notes {body} -> appends internal staff note to case_notes (201)
POST /manage/api/cases/{cid}/tickets Escalates case into a linked ticket (201)
GET /manage/api/canned-responses Lists canned response templates (seeds 4 defaults if empty and untouched)
POST /manage/api/canned-responses Upserts template by shortcut (^[a-z0-9_-]+$) (201)
DELETE /manage/api/canned-responses/{rid} Deletes template by ID

3.3 Admin Account CRUD (app/admin_accounts.py — 4 Routes)

Section titled “3.3 Admin Account CRUD (app/admin_accounts.py — 4 Routes)”
Method Path Purpose & Key Contract
GET /manage/api/admins Lists administrator profiles joined with dashboard_accounts (q filter, max 200)
POST /manage/api/admins Creates new admin member + dashboard_accounts with random 48-byte password (201)
PATCH /manage/api/admins/{mid} Updates admin profile/username/enabled; revokes sessions/resets on change; guards last active admin
DELETE /manage/api/admins/{mid} Deletes dashboard_accounts login while preserving members, cases, and audit history

3.4 AI Configuration, Usage & Testing (app/ai_management.py — 9 Routes)

Section titled “3.4 AI Configuration, Usage & Testing (app/ai_management.py — 9 Routes)”
Method Path Purpose & Key Contract
GET /manage/api/ai-config Returns active revision ID, config, defaults, 10 section descriptors, and default_prompt
GET /manage/api/ai-config/usage Returns live RPM/TPM/RPD (Pacific day for Google, UTC day for Cloudflare), 7-day history, token p50/p90, limits, cooldowns
PUT /manage/api/ai-config/usage/limits/{model} Saves operator-entered Google AI Studio rpm, tpm, rpd caps for gemma-4-26b-a4b-it or gemma-4-31b-it
PUT /manage/api/ai-config Saves new ai_config_revisions pointer with optimistic expected_revision check (409 on race)
GET /manage/api/ai-config/revisions Lists latest 50 configuration revisions
GET /manage/api/ai-config/revisions/{rid} Fetches full revision config JSON by ID
POST /manage/api/ai-config/preview Compiles draft prompt locally in actions or image mode without AI call
POST /manage/api/ai-config/tests Queues sandboxed worker dry-run (202, max 5/min/admin, max 5 queued, optional use_knowledge + draft_id)
GET /manage/api/ai-config/tests/{jid} Polls sandboxed dry-run test result (owner-only, 1h TTL)

3.5 PDF Document Knowledge (app/documents.py — 12 Routes)

Section titled “3.5 PDF Document Knowledge (app/documents.py — 12 Routes)”
Method Path Purpose & Key Contract
GET /manage/api/documents Lists up to 100 uploaded PDFs with byte size and extracted sections_count
POST /manage/api/documents Raw application/pdf body (<= 32 MB) + query params title, filename, category, visibility, auto_publish, expires_at?, replaces? (201)
GET /manage/api/documents/{did} Document metadata + ordered extracted faq sections
GET /manage/api/documents/{did}/file Downloads original PDF (application/pdf, attachment; filename="source.pdf")
GET /manage/api/documents/{did}/preview/{page} Renders single page PNG via pdftoppm subprocess under PDF_REQUEST_SLOT (1..MAX_PAGES)
POST /manage/api/documents/{did}/search Lexical token search across this document’s sections (including unapproved drafts), top 5 (>= 0.35 hit ratio)
PATCH /manage/api/documents/{did} Updates metadata (version check); reverts published document to review and unapproves sections
PATCH /manage/api/documents/{did}/sections/{fid} Edits extracted section question/answer/aliases (version check); reverts doc to review
POST /manage/api/documents/{did}/publish Publishes review document, retires replaces predecessor atomically, sets faq.approved = (visibility == 'public')
POST /manage/api/documents/{did}/unpublish Reverts published document to review and sets faq.approved = false
POST /manage/api/documents/{did}/retry Requeues failed document (< 5 active queue check)
DELETE /manage/api/documents/{did} Query version: int -> deletes PDF and cascading faq sections (blocked while processing)

3.6 Knowledge Governance, Graph, Checks & Intake (19 Routes)

Section titled “3.6 Knowledge Governance, Graph, Checks & Intake (19 Routes)”
  • Case Drafts & Saved Checks (app/knowledge_review.py — 6 Routes):
    • POST /manage/api/cases/{case_id}/knowledge-drafts (creates sanitized unapproved FAQ draft from closed/resolved case)
    • GET /manage/api/knowledge-checks, POST /manage/api/knowledge-checks, PUT /manage/api/knowledge-checks/{check_id}, DELETE /manage/api/knowledge-checks/{check_id}, POST /manage/api/knowledge-checks/{check_id}/run (optional draft_id simulation)
  • Source Authority Governance (app/knowledge_authority.py — 5 Routes):
    • GET /manage/api/knowledge-governance/review (latest 400 passages, up to 40 word-overlap candidate pairs >=0.30 Jaccard & >=3 shared tokens, recorded decisions with stale MD5 flags, pending docs)
    • GET /manage/api/knowledge-governance/articles (search up to 30 passages)
    • PUT /manage/api/knowledge-governance/decision (records prefer|replaces|coexists|conflict with cycle detection & revision locks)
    • DELETE /manage/api/knowledge-governance/decision/{left_id}/{right_id} (undoes decision + logs event)
    • GET /manage/api/knowledge-governance/history/{left_id}/{right_id}
  • Knowledge Graph (app/knowledge_graph.py — 1 Route):
    • GET /manage/api/knowledge-graph (read-only 8s statement timeout; up to 1,000 faq nodes, 1,000 knowledge_relations edges, latest 50 knowledge_checks, topic categorization policy/counts)
  • WhatsApp Knowledge Intake (app/knowledge_intake.py — 7 Routes):
    • GET /manage/api/knowledge-intake/contributors, PUT /manage/api/knowledge-intake/contributors, PUT /manage/api/knowledge-intake/contributors/{phone}, DELETE /manage/api/knowledge-intake/contributors/{phone}
    • GET /manage/api/knowledge-intake (latest 100 submissions)
    • POST /manage/api/knowledge-intake/{sid}/review (approve|reject with note >= 10 chars, staleness check)
    • GET /manage/api/knowledge-intake/{sid}/history

3.7 Broadcasts, On-Duty Alerts & Operational Analytics (10 Routes)

Section titled “3.7 Broadcasts, On-Duty Alerts & Operational Analytics (10 Routes)”
  • Broadcasts (app/broadcasts.py — 7 Routes):
    • GET /manage/api/broadcasts/recipients & PUT /manage/api/broadcasts/recipients/{mid} (opt-in/out + evidence)
    • GET /manage/api/broadcasts, POST /manage/api/broadcasts (draft, max 50 opted-in recipients), GET /manage/api/broadcasts/{cid} (preview + preview_digest + 200 deliveries)
    • POST /manage/api/broadcasts/{cid}/approve (requires version, preview_digest, acknowledge_waha_risk: true)
    • POST /manage/api/broadcasts/{cid}/control (action: "pause" | "cancel")
  • On-Duty Admin Alerts (app/ticket_notifications.py — 2 Routes):
    • GET /manage/api/admin-duty (roster, waiting ticket count, latest 50 deliveries)
    • PUT /manage/api/admin-duty/me ({"on_duty": bool}, requires valid saved phone on profile)
  • Operational Analytics (app/analytics.py — 1 Route):
    • GET /manage/api/analytics (query days in {7, 30, 90}; runs inside REPEATABLE READ READ ONLY snapshot; returns KPIs, flow, service percentiles, assignees, categories, 30d traffic + 7×24 WIB heatmap, AI telemetry, KB/queue readiness, 7d MAE forecast, capacity plan, recommendations, and definitions)

Communicates over the internal private Docker network (http://waha:3000, X-Api-Key: ${WAHA_API_KEY_PLAIN}). Outbound messages require OUTBOUND_ENABLED == 'true'.

Endpoint Caller Purpose Safety & Side-Effect Handling
GET /api/default/lids/{lid} identity.py Resolve @lid privacy ID to @c.us phone Verifies response lid == sender and pn matches digits @c.us
GET /api/sessions/default broadcasts.py, ticket_notifications.py Verify status == 'WORKING' Offline session holds alerts/pauses broadcasts before claiming send
GET /api/default/chats/{phone}@c.us/messages handoff.py (recent_native_reply) Detect native WhatsApp phone replies (source=='app') If check fails, worker holds bot reply (not_sent)
GET /api/files/<path> media.py (load_image) Download inbound screenshot Strict canonical_media_url allowlist, no redirects, 5 MB cap
POST /api/sendText assistant.py (send_whatsapp) Send text to {phone}@c.us (session: 'default') Records returned id in waha_sent_messages; no auto-retry on failure
POST /api/sessions & /api/default/auth/qr scripts/pair.py (host loopback 127.0.0.1:13000) Owner QR pairing Saves PNG to secrets/whatsapp-qr.png (0o600)

5. AI Provider Interfaces & Quota Budgeting

Section titled “5. AI Provider Interfaces & Quota Budgeting”

5.1 Primary: Google Generative Language API (app/assistant.py, app/topic_categorization.py)

Section titled “5.1 Primary: Google Generative Language API (app/assistant.py, app/topic_categorization.py)”
  • Endpoint: POST https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
  • Header: x-goog-api-key: ${GOOGLE_API_KEY}
  • Allowed Models (ai_settings.GoogleModel): gemma-4-26b-a4b-it (default) and gemma-4-31b-it.
  • Payload:
    • systemInstruction: Compiled 10 editable sections + FIXED_RULES + (IMAGE_RULES if image) + (ACTION_RULES or TEXT_RULES) + KNOWLEDGE_RULES.
    • contents: Up to 15 historical user/model pairs (MAX_CHARS = 75,000, replaying historical answers as {"scope":"helpdesk","action":"none","answer":"<text>"}), followed by current turn JSON (as_of_wib, knowledge_catalog, retrieval, retrieval_diagnostics, verified_evidence) and optional inlineData JPEG screenshot.
    • generationConfig: maxOutputTokens (128..8192, default 450, >= 2048 when thinking == 'high'), temperature (0..2, default 0.2), optional topP/topK, thinkingConfig: {'thinkingLevel': 'minimal' | 'high'}, plus strict responseMimeType: 'application/json' and responseSchema (when knowledge_bundle is supplied).
  • Thought Filtering: Provider response parts with part.get('thought') == True are stripped before parsing or returning results.

5.2 Fallback: Cloudflare Workers AI (app/cloudflare_ai.py)

Section titled “5.2 Fallback: Cloudflare Workers AI (app/cloudflare_ai.py)”
  • Activation: Only active when CLOUDFLARE_AI_ENABLED=true, CLOUDFLARE_FREE_PLAN_CONFIRMED=true, 32-hex CLOUDFLARE_ACCOUNT_ID, and CLOUDFLARE_API_TOKEN are all present.
  • Endpoint: POST https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1/chat/completions (Authorization: Bearer <CLOUDFLARE_API_TOKEN>)
  • Model: @cf/google/gemma-4-26b-a4b-it (tracked as cloudflare/@cf/google/gemma-4-26b-a4b-it in ai_usage).
  • Contract Translation (request_body): Converts Google systemInstruction/contents/inlineData into OpenAI-compatible messages (data URLs for images), sets response_format: {'type': 'json_object'}, maps thinkingLevel == 'high' to chat_template_kwargs.enable_thinking, omits Google-only topK, and adapts response JSON back into Google candidates/usageMetadata structure. Error code 3036 sets cooldown until next UTC midnight.

5.3 Local Quota & Cooldown Interface (app/quota.py)

Section titled “5.3 Local Quota & Cooldown Interface (app/quota.py)”
  • permit_request(model) checks provider_cooldowns (until_at > now()) and optional env caps AI_RPM (minute:YYYYMMDDHHMM in budgets) and AI_RPD (day:YYYYMMDD Pacific in budgets).
  • 429 responses parse google.rpc.QuotaFailure (permodel + perday -> Pacific midnight) and RetryInfo/Retry-After (1..90000 seconds) into provider_cooldowns.

Queue Table Producer Consumer Claim & Concurrency Pattern
jobs api (/webhooks/waha, /v1/assist) worker (app.worker) Lock 902711 on enqueue (< 100 active); worker claims 1 oldest ready job per member (ready_at <= now(), FOR UPDATE OF j SKIP LOCKED), batches up to 6 text msgs in 3s window; retries up to 2 failures (attempts >= 2 -> failed)
staff_replies dashboard (/replies, /handoff) & api (native takeover notice) worker (Priority 1) FOR UPDATE SKIP LOCKED; commits state='sending' before WAHA sendText -> 'sent' or 'not_sent'
ticket_notifications main.create_ticket / update_ticket_in -> ticket_open_events worker (Priority 2) Fans out to admin_duty, gated by ticket_notification_gate (5s gap; 30s backoff if WAHA offline), commits sending before WAHA call -> 'sent' or 'unconfirmed'
ai_config_tests dashboard (POST /manage/api/ai-config/tests) worker (Priority 4) FOR UPDATE OF t SKIP LOCKED; 1h TTL; scrubs question after completion
broadcast_deliveries dashboard (approve) -> broadcast_runs worker (Priority 5) Lock 902725; 09.00–18.00 WIB, broadcast_gate 30s gap, 100/day & 1/phone/day caps, defers open handoffs, commits sending before WAHA -> pauses campaign on unconfirmed
knowledge_documents dashboard (POST /manage/api/documents) pdf-worker (app.documents) Session lock 902722 + FOR UPDATE; spawns sandboxed app.pdf_extract subprocess; updates pages/processed_pages progress
faq -> knowledge_topics topic-worker (app.topic_categorization) topic-worker Session lock 902729; polls every 60s; runs 4-article batches only after 10m chat idle, 15m run gap, and strict quota checks (<=20% RPD/RPM, <=50% TPM, <=12 runs/day)