Docs

How InsightService is put together

Configuration, the data it reads and the API behind every screen.

Getting started

How a deployment fits together

A Python (FastAPI) API, a React app and PostgreSQL. InsightService reads the firm’s systems from a source schema and keeps its inbox, cases, replies, remediations, requests, decisions and agent runs in its own schema.

1

Connect the sources

Point SERVICE_SOURCE_SCHEMA at your contacts, customers, accounts, fees, knowledge base and prior complaints, or at views over them.

2

Set the policy

Replace the illustrative clock, interest rate, threshold and sampling values with your own, and publish the case controls in Rules Studio.

3

Add people

Service agents, team leads and administrators, through the identity service or your SSO.

Configuration

The settings that matter

Set in the environment of the API. Every policy value is a placeholder until you set it.

VariableWhat it sets
INSIGHT_DATABASE_URL, INSIGHT_DATABASE_SECRET, INSIGHT_DATABASE_SCHEMAThe PostgreSQL connection (or a secret reference for it) and the schema InsightService keeps its own work in (service by default)
SERVICE_SOURCE_SCHEMAThe schema holding the firm’s systems: customers, accounts, fees, transactions, contacts, the knowledge base and prior complaints. Read only
SERVICE_ACK_DAYS, SERVICE_FINAL_WEEKS, SERVICE_DUE_SOON_DAYSThe complaint clock: acknowledge within days, final response within weeks, “due soon” days before (defaults 5, 8, 7; illustrative)
SERVICE_REMEDIATION_RATE, SERVICE_APPROVAL_THRESHOLDAnnual simple interest added to a refund, and the total above which a team lead approves (defaults 0.08 and 250 GBP; illustrative)
SERVICE_QA_SAMPLE_RATE, SERVICE_SYSTEMIC_CUSTOMERSThe share of closed cases sampled for QA, and the customer count behind the rising-cause systemic test (defaults 0.2 and 5; illustrative)
SERVICE_AGENTS_LLM, SERVICE_COPILOT_LLM, SERVICE_CLAUDE_MODELWhether the agents and the copilot use a language model, and which; 0 means rules only
SERVICE_AGENTS_MAX_LEVELAn autonomy ceiling for the tenant; actions are hard-capped at L2 regardless
SERVICE_COMMS_LIVE, SERVICE_APP_URLWhether sending a reply or request delivers it, and the address the customer’s request link points to
SERVICE_ALLOW_TEMPLATE_SENDSet to 0 to refuse sending a final letter that still contains template wording
SERVICE_CORS_ORIGINSThe web origins allowed to call the API (* is never honoured)
Data

What InsightService reads

The demo builds these tables for a fictional bank and insurer; a deployment maps them to the firm’s systems.

Source tableWhat it holds
firm_profile, productsThe firm and its products, each with a product line
customersCustomers, their contact preferences and any vulnerability already on record
accounts, fees, transactionsAccounts and policies, fees by fee run, and transactions
contactsInbound emails, web forms, chat transcripts and call notes, with threads
kb_articlesThe knowledge base replies are grounded in
prior_complaintsComplaints handled before InsightService, with outcome and root cause
API

Every screen is an API call

Authenticated with the session’s bearer token; the customer request page and the health checks are the only public routes.

AreaEndpoints (under /api/service)
ReferenceGET /reference
InboxGET /inbox, POST /inbox/sync, GET /inbox/{id}, POST /inbox/{id}/classify, POST /inbox/{id}/case
CasesGET /cases, GET /cases/{id}, PUT /cases/{id}/owner, GET /cases/{id}/timeline, POST /cases/{id}/classify, POST /cases/{id}/research, GET /cases/{id}/customer, POST /cases/{id}/root-causes, POST /cases/{id}/vulnerability, POST /cases/{id}/outcome
RemediationPOST /cases/{id}/remediation/calculate, POST /cases/{id}/remediation, GET /cases/{id}/remediations, POST /remediations/{id}/submit, POST /remediations/{id}/decide, GET /remediations
RepliesGET|POST /cases/{id}/replies, PUT /replies/{id}, POST /replies/{id}/send, POST /replies/{id}/cancel
RequestsGET|POST /cases/{id}/requests, PUT /requests/{id}, POST /requests/{id}/send, POST /requests/{id}/cancel; the customer’s page uses GET|POST /api/public/request/{token}
ClosePOST /cases/{id}/submit, POST /cases/{id}/close, GET /cases/{id}/decision
Knowledge baseGET /kb, GET /kb/{article_id}
OversightGET /root-causes, GET /root-causes/analytics, POST /root-causes/analyse, POST /root-causes/{id}/acknowledge, GET /qa, POST /qa/sample, POST /qa/{id}
Agents (under /api/service_agents)POST /cases/{id}/run, GET /cases/{id}, POST|GET /portfolio/{which}, GET /prepared, POST /prepared/{id}/answer, GET /autonomy, PUT /autonomy/{agent}/level, PUT /autonomy/{agent}/enabled, GET /activity, GET /metrics
Rules, home and healthRules Studio under /api/service_rules; GET /api/me, the home under /api; GET /api/health, GET /api/ready; the copilot under /api/assist, /api/chat and /api/conversation

Questions about a deployment?

Tell us about your systems and we’ll map them to InsightService’s sources with you.

Request a demo