API Reference

Complete REST API for inferonIQ. All endpoints require authentication via session cookie or API key unless noted.

Base URL: https://app.inferoniq.com (SaaS) or your BYOC deployment URL

Auth: Session cookie (browser) or Authorization: Bearer <api-key>

Content-Type: application/json (except file uploads: multipart/form-data)

NL2SQL Query

Execute natural language questions against connected databases.

POST/api/query

Execute natural language query

Translates natural language to SQL, executes safely, returns structured results with business insights.

Request Body:

querystringrequired— Natural language question

connectionIdstring (UUID)— Target connection

streamboolean— Enable SSE streaming

Response Example:

{
  "sql": "SELECT vendor_name, SUM(amount) ...",
  "data": [
    {
      "vendor_name": "Acme",
      "total": 142500
    }
  ],
  "confidence": 0.94
}

Documents

Upload, classify, and extract data from invoices, contracts, and receipts.

POST/api/documents/upload-url

Get presigned upload URL (large files)

For files > 4MB. Returns a signed URL to upload directly to storage. After uploading, call POST /api/documents with the storagePath.

Request Body:

fileNamestringrequired— Original file name

fileSizenumberrequired— File size in bytes

mimeTypestring— MIME type (optional)

Response Example:

{
  "uploadUrl": "https://storage...",
  "storagePath": "customer_id/file.pdf",
  "expiresIn": 600
}

POST/api/documents

Upload & process document

Two modes: (1) multipart/form-data with file for direct upload (≤ 4MB), (2) application/json with storagePath for presigned uploads (up to 50MB). Returns classification + extraction preview.

Request Body:

fileFile (multipart)— Direct upload mode

storagePathstring— Presigned upload mode — path from upload-url response

Response Example:

{
  "id": "doc-uuid",
  "type": "invoice",
  "extractedFields": {
    "vendor": "Acme",
    "total": 14805
  }
}

GET/api/documents

List documents

Paginated list of uploaded documents with metadata and extraction status.

Query Params:

typestring — Filter by document type

limitnumber — Page size (default 50)

Connections

Manage database and storage connections.

GET/api/connections

List connections

Returns all configured database and storage connections for your tenant.

POST/api/connections

Create connection

Add a new database or storage connection with encrypted credentials.

Request Body:

namestringrequired— Display name

hoststringrequired— Database host

portnumber— Port (auto-detected by type)

databasestringrequired— Database name

usernamestringrequired— Auth username

passwordstringrequired— Auth password (encrypted at rest)

POST/api/connections/test

Test connection

Validates connectivity and credentials without saving.

3-Way Matching

Invoice ↔ Purchase Order ↔ Goods Receipt reconciliation.

POST/api/invoices/match

Run 3-Way Match

Executes the 7-phase matching pipeline on an uploaded invoice.

Request Body:

documentIdstring (UUID)required— Invoice document ID

Response Example:

{
  "matchResult": "3-way",
  "confidence": 0.97,
  "exceptions": [],
  "autoApproved": true
}

GET/api/invoices/matches

List match results

Paginated list of all match results with exception details.

Contracts

Contract intelligence — clause extraction and compliance monitoring.

POST/api/contracts/analyze

Analyze contract

AI extracts clauses, pricing terms, SLA targets, renewal dates, and obligations.

Request Body:

documentIdstring (UUID)required— Contract document ID

GET/api/contracts

List contracts

All analyzed contracts with metadata, risk scores, and expiry dates.

License

License validation and usage information.

GET/api/license

Get license status

Returns current license plan, limits, usage counters, and expiry.

Response Example:

{
  "plan": "business",
  "status": "active",
  "expiresAt": "2027-01-01",
  "usage": {
    "queries": 1250,
    "limit": 25000
  }
}

POST/api/license/activate

Activate license key

Activate a new Ed25519-signed license key (BYOC deployments).

Request Body:

keystringrequired— License key string

Health

Platform health and connectivity checks.

GET/api/health

Health check

Returns platform status, database connectivity, and version info. No auth required.

Response Example:

{
  "status": "healthy",
  "version": "3.7.0",
  "database": "connected"
}

Rate Limits & Usage

Rate limits are per-customer, enforced at the license level:

Plan	Queries/mo	Documents/mo	Connections
Trial	100	50	1
Team	5,000	2,000	5
Business	25,000	10,000	20
Enterprise	Unlimited	Unlimited	Unlimited

Exceeding limits returns 429 Too Many Requests with a Retry-After header.