AI Orchestrator — API Reference

⚙️ Tenant Configuration

Per-tenant orchestrator settings: HITL mode, rate limits, contact window, frequency caps.

GET /api/tenant-config/{parentId} Get orchestrator config for a tenant ▼

Path Parameters

Name	Type	Description
parentId	long	Tenant ID required

Example Response

{ "id": 1, "parentId": 1001, "hitlMode": "always_ask",
  "autoSendAfterMinutes": 15, "suggestionExpiryMinutes": 60,
  "listenerWaitHours": 24, "maxFollowupsBeforeRecycle": 3,
  "maxAiCallsPerEntityDay": 10, "maxAiCallsPerTenantDay": 500,
  "isOrchestratorEnabled": true,
  "contactWindowJson": null, "frequencyCapsJson": null }

PUT /api/tenant-config/{parentId} Create or update tenant config (upsert) ▼

Request Body — all fields optional

Field	Type	Default	Notes
hitlMode	string	always_ask	`always_ask` \| `auto_if_no_response` \| `fully_autonomous`
autoSendAfterMinutes	int	15	Auto-execute delay for auto_if_no_response mode
suggestionExpiryMinutes	int	60	HITL card TTL
listenerWaitHours	int	24	How long to wait for a reply before timeout
maxFollowupsBeforeRecycle	int	3	Recycle entity after N unanswered follow-ups
maxAiCallsPerEntityDay	int	10	Per-entity daily AI call cap
maxAiCallsPerTenantDay	int	500	Tenant-wide daily AI call cap
isOrchestratorEnabled	bool	true	Kill switch — disable all AI for this tenant
contactWindowJson	string	null	JSON: `{"start":"09:00","end":"20:00","timezone":"Asia/Kolkata","dnd_days":["sunday"]}`
frequencyCapsJson	string	null	JSON: `{"max_messages_per_day":5,"max_calls_per_day":2}`

POST /api/tenant-config/{parentId}/apply-preset Apply a named preset ▼

Query Parameters

Name	Values	Description
preset	`conservative` \| `balanced` \| `aggressive`	Preset name required

conservative = always_ask, 30 min cooldown · balanced = auto_if_no_response, 15 min · aggressive = fully_autonomous

🔧 Dev & Testing DEV ONLY

Development endpoints for smoke-testing and debugging. Remove or gate behind auth before production.

GET /api/dev/health Infrastructure health check ▼

{ "timestamp": "2026-06-03T...", "services": { "api":"ok",
  "hangfire":"configured", "masstransit":"configured", "semanticKernel":"configured" } }

POST /api/dev/publish-signal Publish a hardcoded test signal to RabbitMQ (lead#42, tenant 1001) ▼

No request body needed. Always publishes: email_received for lead#42, tenant 1001.

{ "status": "published", "message": { "parentId":1001, "entityType":"lead",
  "entityId":42, "signalType":"email_received", ... } }

POST /api/dev/integration-test Full pipeline test — bypasses RabbitMQ, runs DecisionPipeline directly ▼

Creates tenant config for 1001 if missing. Returns full pipeline result including plan and HITL cards created.

{ "pipeline": { "wasProcessed":true, "planId":5,
    "decision": { "reasoning":"...", "aiModel":"gpt-4o-mini", "tokensUsed":620,
      "steps":[{"stepOrder":1,"toolKey":"draft_email","delayMinutes":0}] } },
  "hitlCards": [{ "cardRef":"abc123...", "title":"AI suggests: draft_email", "status":"pending" }] }

POST /api/dev/dry-run Simulate the full pipeline with NO database writes — shows what would happen ▼

Request Body

Field	Type		Description
parentId	long	required	Tenant ID
entityType	string	required	`lead` or `enquiry`
entityId	long	required	Entity ID from the monolith
signalType	string	required	e.g. `email_received`, `call_completed`
signalPayload	string	optional	JSON payload for the signal
mockSnapshot	object	optional	EntitySnapshot — use instead of calling the monolith API

// Example with mock data (no monolith required)
{ "parentId":1001, "entityType":"lead", "entityId":9999, "signalType":"email_received",
  "mockSnapshot":{ "name":"Priya Sharma", "status":"hot", "stage":"evaluation",
    "engagementScore":82, "minutesSinceLastInteraction":45,
    "slotsCollected":["name","phone"], "slotsMissing":["budget"],
    "pendingTasks":1, "pendingTickets":0 } }

Response — outcome values

Outcome	Meaning
SUCCESS	AI decided steps — shown in decision.steps[]
NOT_ROUTED	No agent configured for this signal type
BLOCKED_RECYCLED	Entity is recycled — orchestrator would skip
AI_ERROR	OpenAI API call failed

POST /api/dev/test-sk Test Semantic Kernel — calls LLM with EmailPlugin registered ▼

{ "response": "[DRAFT] To: john@example.com\nSubject: Follow-up on Enterprise Plan..." }

GET /api/dev/state-summary Live state snapshot — entity states, plans, HITL cards, listeners, audit ▼

Query Parameters

Name	Type	Default
parentId	long	1001

🃏 HITL Cards

Human-in-the-Loop approval cards. The AI creates cards for actions it wants to take; users approve, dismiss, or redirect them.

GET /api/hitl/cards All pending HITL cards for a tenant ▼

Query Parameters

Name	Type
parentId	long	required

GET /api/hitl/cards/{cardRef} Get a specific card by reference ▼

Path Parameters

Name	Description
cardRef	12-char hex card reference (e.g. `e40b48589d2e`)

POST /api/hitl/cards/{cardRef}/respond Respond to a HITL card ▼

Request Body

Field	Type		Description
action	string	required	`send` \| `dismiss` \| `rephrase` \| `tell_ai`
responseText	string	optional	Required for `rephrase` and `tell_ai`
actorUserId	long	optional	User ID for audit trail

Action behaviours

Action	What happens
send	Approve — executes the plan step immediately via Hangfire
dismiss	Skip — marks step as skipped, no action taken
rephrase	Re-send with new text — replaces message body, executes step
tell_ai	Give feedback — re-runs pipeline with user's text as new signal payload

// Request
{ "action": "rephrase", "responseText": "Hi, wanted to follow up about your interest in our Pro plan.", "actorUserId": 7 }
// Response
{ "result": "ok", "action": "rephrase", "planStepId": 3 }

GET /api/hitl/history HITL card history for an entity ▼

Query Parameters

Name	Type	Default
parentId	long	required
entityType	string	optional
entityId	long	optional
take	int	20

🤖 Agent Configs

Configure how AI agents behave per tenant: system prompt, tools, model, temperature, knowledge base.

GET /api/agent-configs/{parentId} List all agent configs for a tenant ▼

[{ "id":1, "agentKey":"lead_nurture", "displayName":"Lead Nurture Agent",
   "entityTypes":"lead,enquiry", "signalTypes":"email_received,whatsapp_received,...",
   "model":"gpt-4o-mini", "temperature":0.3, "maxTokens":2000, "isEnabled":true,
   "useKnowledgeBase":false, "priority":1 }]

GET /api/agent-configs/{parentId}/{agentKey} Get a single agent config with full system prompt ▼

PUT /api/agent-configs/{parentId}/{agentKey} Create or update an agent config (upsert) ▼

Request Body

Field	Type	Description
displayName	string	Human-readable agent name
entityTypes	string	Comma-separated: `lead,enquiry`
signalTypes	string	Comma-separated: `email_received,whatsapp_received`
systemPrompt	string	Full system prompt text
availableTools	string	Comma-separated tool keys
modelOverride	string	e.g. `gpt-4o` — overrides default model
temperature	double	0.0–1.0, default 0.3
maxTokens	int	Max LLM output tokens
maxSteps	int	Max plan steps agent can return
useKnowledgeBase	bool	Inject relevant KB chunks into prompt
knowledgeScope	string	Scope filter for KB retrieval: `products`, `pricing`, `all`
specialInstructions	string	Appended to system prompt at runtime
priority	int	Lower = checked first when routing (default 1)
isEnabled	bool	Disable agent without deleting

POST /api/agent-configs/{parentId}/seed-defaults Seed default agents: lead_nurture + voice_followup ▼

Idempotent — skips agents that already exist. Good starting point before customising prompts.

DELETE /api/agent-configs/{parentId}/{agentKey} Delete an agent config ▼

🔧 Agent Tools

Control which tools (actions) an agent can use, whether they require HITL, and per-tool constraints.

GET /api/agent-tools/registry All available tools from the monolith tool registry ▼

[{ "key":"draft_email", "label":"Draft Email", "category":"communication", "requiresHitl":true },
 { "key":"send_whatsapp", "label":"Send WhatsApp", "category":"communication", "requiresHitl":false },
 { "key":"create_task", "label":"Create Task", "category":"crm", "requiresHitl":false }, ...]

GET /api/agent-tools/{parentId}/{agentKey} Get tools assigned to a specific agent with their permissions ▼

PUT /api/agent-tools/{parentId}/{agentKey} Set all tools for an agent (replaces existing mappings) ▼

{ "tools": [
    { "toolKey": "draft_email",     "isEnabled": true, "requiresHitl": true },
    { "toolKey": "create_task",     "isEnabled": true, "requiresHitl": false },
    { "toolKey": "send_whatsapp",   "isEnabled": false }
  ] }

PATCH /api/agent-tools/{parentId}/{agentKey}/{toolKey} Toggle or configure a single tool ▼

{ "isEnabled": true, "requiresHitl": false,
  "paramConstraintsJson": "{\"max_message_length\": 500}" }

POST /api/agent-tools/{parentId}/{agentKey}/seed-from-registry Auto-assign all registry tools to this agent (all enabled by default) ▼

💬 Chat

Multi-channel, multi-modal chat. One session per channel per entity. Supports text, image, audio, and video.

GET /api/v1/chat/sessions Get or create the active chat session for an entity on a channel ▼

Query Parameters

Name	Type		Notes
parentId	long	required
entityType	string	required	`lead` \| `enquiry`
entityId	long	required
channel	string	optional	`webchat` (default) \| `whatsapp` \| `email` \| `sms` \| `in_app`

{ "id": 1, "channel": "whatsapp", "status": "active",
  "createdAt": "2026-06-03T...", "lastMessageAt": "2026-06-03T..." }

GET /api/v1/chat/sessions/{sessionId}/messages Paginated message history for a session (newest first) ▼

Query Parameters

Name	Type	Default
page	int	1
pageSize	int	50

[{ "id":2, "direction":"inbound", "senderType":"lead", "messageType":"audio",
   "textContent":null, "aiTranscript":"Can you send me the pricing details?",
   "aiDescription":null, "status":"delivered", "mediaUrl":"/tmp/orc-media/...",
   "createdAt":"2026-06-03T..." }]

POST /api/v1/chat/messages/text Send an outbound text message (agent/sales rep reply) ▼

// Request
{ "parentId":1001, "entityType":"lead", "entityId":42,
  "channel":"whatsapp", "textContent":"Hi! Thanks for reaching out. Here's the pricing..." }
// Response
{ "status": "sent" }

POST /api/v1/chat/messages/media Upload and send a media message — image, audio, or video (max 100 MB) ▼

Request — multipart/form-data

Field	Type
file	file	required
parentId	long	required
entityType	string	required
entityId	long	required
channel	string	optional
caption	string	optional

Processing (async via Hangfire)

Type	Processing
image	GPT-4o Vision → `aiDescription`
audio	OpenAI Whisper → `aiTranscript`
video	FFmpeg audio strip → Whisper + keyframe → GPT-4o Vision

// Response (202 Accepted)
{ "chatMessageId": 5, "status": "processing", "storageUrl": "/tmp/orc-media/..." }

Subscribe to SignalR ChatMessageProcessed for the transcript/description when ready.

POST /api/v1/chat/inbound Webhook — inbound message from external channel provider (WhatsApp gateway, SMS, etc.) ▼

{ "parentId":1001, "entityType":"lead", "entityId":42,
  "channel":"whatsapp", "messageType":"text",
  "textContent":"I'm interested, please send the brochure",
  "externalMessageId":"wamid.abc123" }
// Response
{ "chatMessageId": 6 }

Also triggers the full DecisionPipeline — the AI sees the inbound message in its context and may create a plan + HITL cards.

🧠 Knowledge Base (RAG)

pgvector-backed knowledge store. Ingest product docs, pricing, FAQs — agents with useKnowledgeBase=true automatically retrieve relevant chunks.

GET /api/knowledge/{parentId}/documents List all ingested documents for a tenant ▼

[{ "documentId":"pricing_2026.pdf", "scope":"pricing", "chunkCount":12,
   "createdAt":"2026-06-03T..." }]

POST /api/knowledge/{parentId}/ingest Embed and store document chunks (max 500 chunks per call, idempotent) ▼

// Request
{ "documentId": "pricing_2026.pdf",
  "scope": "pricing",
  "chunks": [
    { "text": "Pro plan: ₹12,000/month for up to 10 users.", "metadata": {"page": "2"} },
    { "text": "Enterprise plan: custom pricing, unlimited users.", "metadata": {"page": "3"} }
  ] }
// Response
{ "success":true, "documentId":"pricing_2026.pdf", "scope":"pricing", "chunksIngested":2 }

Scope values

Scope	Use for
products	Product descriptions, features
pricing	Pricing, plans, discounts
policies	Refund, SLA, terms policies
faq	Frequently asked questions
all	General — retrieved for any query

POST /api/knowledge/{parentId}/upload Upload a raw file — server extracts text, chunks, embeds, and stores automatically ▼

Request — multipart/form-data · max 20 MB

Field	Type	Description
file	File	required — PDF, DOCX, TXT, CSV, MD
scope	string	all — products \| pricing \| policies \| faq \| all
documentId	string	optional — defaults to filename

How it works

1. PDF → word grouping per page via PdfPig | DOCX → paragraph elements | TXT/CSV/MD → line split
2. Chunks into ~400-word windows with 60-word overlap
3. Batch embeds all chunks via text-embedding-ada-002
4. Stores in orc_knowledge_chunks (pgvector) — re-upload replaces old chunks

// Response
{ "success": true, "documentId": "pricing.pdf", "scope": "pricing",
  "filename": "pricing.pdf", "sizeBytes": 204800, "chunksIngested": 14 }

GET /api/knowledge/{parentId}/search Test RAG retrieval — returns top-K relevant chunks for a query ▼

Query Parameters

Name	Type	Default
q	string	required
scope	string	optional
topK	int	5

{ "query":"what does the pro plan include", "scope":null, "topK":5, "resultCount":2,
  "results":[
    { "text":"Pro plan: ₹12,000/month for up to 10 users...", "documentId":"pricing_2026.pdf",
      "scope":"pricing", "relevance":0.9231 },
    { "text":"Free trial: 14 days, all Pro features included.", "documentId":"pricing_2026.pdf",
      "scope":"pricing", "relevance":0.7841 }
  ] }

DELETE /api/knowledge/{parentId}/documents/{documentId} Delete all chunks for a specific document ▼

DELETE /api/knowledge/{parentId} Delete the entire knowledge base for a tenant ▼

Irreversible. Deletes all embedded chunks for the tenant.

📜 Audit Logs

Immutable structured log of every AI decision, plan step, HITL action, and error.

GET /api/audit Filtered, paginated audit log ▼

Query Parameters

Name	Type	Default	Description
parentId	long	required
entityType	string	optional	Filter by entity type
entityId	long	optional	Filter by entity ID
planId	long	optional	Filter by plan
eventType	string	optional	e.g. `decision_made`, `step_executed`
errorsOnly	bool	optional	Only return error events
from	DateTimeOffset	optional	Start of range
to	DateTimeOffset	optional	End of range
page	int	1
pageSize	int	50	Max 200

Event types

Event	When
decision_requested	Signal passed cost guard, agent called
decision_made	Agent returned a plan
cost_guard_blocked	Signal rejected by cost guard
step_scheduled	Plan step queued in Hangfire
step_executed	Plan step ran successfully
step_failed	Plan step execution failed
hitl_card_created	HITL card pushed to user
hitl_response	User responded to a HITL card
listener_created	Wait-for-reply listener registered
listener_matched	Inbound reply matched listener
listener_timed_out	Listener expired without reply

GET /api/audit/stats Aggregated tenant statistics over N days ▼

Query Parameters

Name	Type	Default
parentId	long	required
days	int	7

{ "decisionsMade":42, "totalTokens":28400, "hitlCreated":38,
  "stepsExecuted":31, "totalErrors":2, "entitiesRecycled":0 }

GET /api/audit/entity-timeline All audit events for a specific entity, chronologically ▼

Query Parameters

Name	Type	Default
parentId	long	required
entityType	string	required
entityId	long	required
take	int	50

⚡ SignalR Hub WS

Hub path: /hubs/orchestrator · Use @microsoft/signalr

CLIENT→SERVER JoinTenantGroup(parentId) Subscribe to all events for a tenant ▼

await connection.invoke("JoinTenantGroup", 1001);

CLIENT→SERVER JoinChatSession(sessionId) Subscribe to events for a specific chat session ▼

await connection.invoke("JoinChatSession", 1);

CLIENT→SERVER SendTypingIndicator(sessionId, isTyping) Broadcast typing state to other session subscribers ▼

await connection.invoke("SendTypingIndicator", 1, true);

Server → Client events

SERVER→CLIENT HitlCardCreated New HITL card pushed to tenant group ▼

{ cardRef, cardType, title, body, agentKey, entityType, entityId,
  availableActions, autoAction, autoExecuteAt, createdAt }

SERVER→CLIENT HitlCardResponded User responded to a card ▼

{ cardRef, action, respondedAt }

SERVER→CLIENT ChatMessageReceived New chat message (inbound or outbound) — sent to tenant group ▼

{ sessionId, messageId, direction, senderType, messageType,
  textContent, mediaUrl, status, createdAt }

SERVER→CLIENT ChatMessageProcessed Media processing complete — contains Whisper transcript or GPT-4V description ▼

{ messageId, sessionId, transcript, description, textForLlm, status }

SERVER→CLIENT TypingIndicator Real-time typing state for a chat session ▼

{ sessionId, connectionId, isTyping }