API Reference

Base URL: https://your-domain.com/api
Authentication: x-customer-id header (auto-detected in dev mode).

POST/api/query

Execute a natural language query (NL2SQL)

Field	Type	Req	Note
query	string	✅	Natural language question (1–2000 chars)
customerId	UUID	—	Auto-detected in dev mode
connectionId	UUID	—	Single connection scope
connectionIds	UUID[]	—	Multi-connection scope
sessionId	UUID	—	Conversation session

{ success, answer, businessInsights, data, columns, sql, confidence, durationMs }

PATCH/api/query

Submit feedback on a query result

Field	Type	Req	Note
queryId	UUID	✅	Query to rate
feedback	"positive" \| "negative"	✅	Rating
comment	string	—	Optional correction (max 1000)

{ success: true }

POST/api/documents

Upload & process a document (SHA-256 dedup)

Auth: multipart/form-data

Field	Type	Req	Note
file	File	✅	Document file
customerId	string	✅	Customer UUID

{ document: { id, fileName, documentType, status }, processing: { summary, durationMs } }

GET/api/documents

List documents

Query: customerId — Required query param

POST/api/match

3-way invoice matching

Auth: x-customer-id header

Field	Type	Req	Note
invoiceId	UUID	—	Single invoice
documentId	UUID	—	Alias for invoiceId (from upload flow)
invoiceIds	UUID[]	—	Batch processing

GET/api/match

List match results

Auth: x-customer-id header

POST/api/agents

Create agent or execute agent query

Field	Type	Req	Note
name	string	✅	For creating (1–255)
agentType	string	✅	Agent domain type
agentId + query	UUID + string	—	For executing a query through agent

GET/api/agents

List agents for customer

POST/api/connections

Create data source connection (auto-profiles)

GET/api/connections

List connections

POST/api/connections/sync

Trigger immediate sync

GET/api/connections/sync

Sync config + job history

GET/api/dashboards

KPI data

Query: type — "executive" or "spend"

POST/api/contracts

Analyze a contract

GET/api/insights

AI-powered proactive insights

GET/api/notifications

List notifications

Auth: x-customer-id header

PATCH/api/notifications

Mark notifications as read

Auth: x-customer-id header

GET/api/entities

Entity graph operations

GET/api/vendors

Vendor directory

GET/api/health

Health check (no auth)

POST/api/legal/research

Legal research — ?action=search|memo

Field	Type	Req	Note
case_id	UUID	✅	Case context
query	string	✅	Research question (for search)

{ success, research: { cases[], statuteOfLimitations, likelihood } | memo: string }

GET/api/legal/research

Research history for a case — ?case_id=UUID

GET/api/receivables

Query: view — summary (default), aging, aging-bucket, unmatched, suggestions, statements

{ aging: { total, buckets[] }, unmatched[] } | { statements[] } | AgingSummary

POST/api/receivables

Import bank statement or run matching — ?action=import|match

Field	Type	Req	Note
bank_name	string	—	Bank name (for import)
statement_date	date	✅	Statement date (for import)
opening_balance	number	✅	Opening balance
closing_balance	number	✅	Closing balance
lines	array	✅	Transaction lines with amount, description, date
statement_id	UUID	✅	For action=match only

{ success, statement, matching: { matched, unmatched, needsReview } }

GET/api/compliance

Query: view — dashboard (default), rules, violations, checklists, checklist

{ activeRules, passRate, openViolations, criticalCount } | { rules[] } | { violations[] }

POST/api/compliance

Compliance operations — ?action=create-rule|scan|init-checklist|update-item|resolve-violation

Field	Type	Req	Note
rule_name	string	✅	Rule name (for create-rule)
rule_type	string	✅	data_quality \| regulatory \| internal_policy (for create-rule)
check_query	string	—	SQL query that returns violations
severity	"info"\|"warning"\|"critical"	—	Rule severity
period	string	✅	Close period e.g. 2026-04 (for init-checklist)
item_id	UUID	✅	Checklist item (for update-item)
violation_id	UUID	✅	Violation (for resolve-violation)

{ success, rule|checklist } | { success, checked, passed, failed, violations[] }

GET/api/procurement

Procurement data — ?view=spend&start_date=X&end_date=Y | ?view=journal-entries&period=X&status=X

Query: view — spend (default), journal-entries

{ categories: [{ category, amount, invoiceCount, topVendor }] } | { entries[] }

POST/api/procurement

Procurement operations — ?action=rfp|compare-vendors|journal-entry|post-journal-entry

Field	Type	Req	Note
category	string	✅	Procurement category (for rfp)
description	string	✅	What you need (for rfp, min 10 chars)
budget	number	—	Budget cap (for rfp)
proposals	array	✅	Vendor proposals (for compare-vendors, min 2)
entry_date	date	✅	Journal entry date
period	string	✅	Accounting period e.g. 2026-04
lines	array	✅	Debit/credit lines (min 2, must balance)
entry_id	UUID	✅	Entry to post (for post-journal-entry)

{ success, rfp: { title, scope, requirements[], evaluationCriteria[] } } | { success, entry }

Error Responses

All endpoints return errors in a consistent format:

{ "error": "Human-readable message", "details": "..." }

400 — Validation error401 — Missing customer identification404 — Resource not found500 — Internal server error