API Reference

Execute compliance simulations programmatically. All endpoints require an API key.

Authentication

Lumis uses Bearer token authentication. Generate an API key from Settings → API Keys. Keys are shown once at creation — store them securely.

Keys are stored as SHA-256 hashes. Lumis never retains the raw key value.

All requests

Authorization: Bearer lmk_live_••••••••••••••••••••••••

Treat your API key like a password. Rotate it immediately from the dashboard if it is ever exposed. Leaked keys can be deactivated under Settings → API Keys without affecting other keys in your workspace.

API keys require an active Pro trial or a paid Pro/Business plan. Keys are automatically paused when the trial expires and the workspace downgrades to Free. A paused request returns HTTP 402 with the header X-Lumis-Reason: trial_expired_keys_paused. Upgrade from the dashboard to restore access without regenerating keys.

Base URL

All API calls are routed to the Lumis edge environment via our standard REST endpoints.

The base REST URL for simulations is https://lumiscompliance.com/api/v1/simulate.

POST /api/v1/simulate

Run a compliance simulation. The payload is evaluated through the ruleset DAG and every node result is recorded in the audit trail.

Request body

Name	Type	Description
`rulesetId`required	`string`	The Convex document ID of the target ruleset (e.g. jx7abc123…)
`payload`required	`object`	Arbitrary JSON object representing the transaction or entity to evaluate. Max 64 KB.
`expected_outcome`	`"pass" \| "fail"`	Used for coverage analysis. Flags the simulation as matched or mismatched.
`test_suite`	`string`	Group related simulations together under a single test suite ID.
`tags`	`string[]`	Array of arbitrary string tags to annotate this simulation.

curl

curl -X POST https://lumiscompliance.com/api/v1/simulate \
  -H "Authorization: Bearer lmk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "rulesetId": "jx7abc123",
    "payload": {
      "transaction_amount": 1500,
      "user_region": "US",
      "id_verified": true,
      "risk_score": 0.12
    }
  }'

TypeScript (fetch)

const response = await fetch("https://lumiscompliance.com/api/v1/simulate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer lmk_live_••••••••",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    rulesetId: "jx7abc123",
    payload: {
      transaction_amount: 1500,
      user_region: "US",
      id_verified: true,
      risk_score: 0.12,
    }
  })
});
const result = await response.json();

Response

Name	Type	Description
`transactionId`	`string`	Unique ID of this simulation record in your audit log
`status`	`"passed" \| "failed" \| "error"`	Final verdict of the DAG evaluation
`stepsExecuted`	`number`	Number of DAG nodes that were evaluated
`passedNodeIds`	`string[]`	Array of node IDs that evaluated to passed
`failedNodeId`	`string \| null`	The first node that caused a failure, or null on pass
`auditTrail`	`AuditEntry[]`	Ordered log of every node evaluation with timestamps

Success response (200)

{
  "transactionId": "tx_9p2kx8f",
  "status": "passed",
  "stepsExecuted": 6,
  "passedNodeIds": ["kyc_check", "sanctions", "aml_threshold", "risk_band", "id_verify", "terminal_pass"],
  "failedNodeId": null,
  "auditTrail": [
    { "nodeId": "kyc_check", "status": "passed", "timestamp": 1714000001234 },
    { "nodeId": "sanctions",  "status": "passed", "timestamp": 1714000001280 }
  ]
}

POST /api/v1/simulate/batch

Run up to 50 payloads against a single ruleset in one call. Recommended for high-volume automated testing and regression suites.

Request body

Name	Type	Description
`rulesetId`required	`string`	The Convex document ID of the target ruleset
`payloads`required	`object[]`	Array of JSON objects to evaluate. Max 50 items.
`testSuiteId`	`string`	Group this entire batch of simulations under a single test suite ID.
`tags`	`string[]`	Apply arbitrary string tags to every simulation in this batch.

TypeScript (fetch)

const response = await fetch("https://lumiscompliance.com/api/v1/simulate/batch", {
  method: "POST",
  headers: {
    "Authorization": "Bearer lmk_live_••••••••",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    rulesetId: "jx7abc123",
    payloads: [
      { transaction_amount: 200, user_region: "US" },
      { transaction_amount: 9800, user_region: "EU" }
    ]
  })
});
const result = await response.json();
// Returns: { success: true, data: { transactionIds: ["tx_1", "tx_2"] } }

Batch calls consume quota identically to individual calls. A 50-row batch uses 50 simulations from your monthly allowance.

Error codes

Code	Meaning	Resolution
`UNAUTHORIZED`	Invalid or inactive API key	Regenerate a key from Settings → API Keys
`QUOTA_EXCEEDED`	Monthly simulation limit reached	Upgrade your plan or wait for quota reset
`NOT_FOUND`	Ruleset ID does not exist	Verify the rulesetId in your request
`FORBIDDEN`	Ruleset belongs to another workspace	Use a rulesetId owned by your workspace
`PAYLOAD_TOO_LARGE`	Payload exceeds 64 KB	Reduce payload size or split into multiple calls
`API_KEYS_DISABLED`	Trial expired or workspace on Free tier	Upgrade to Pro — check X-Lumis-Reason: trial_expired_keys_paused header
`USAGE_LIMIT_EXCEEDED`	Business 100K cap reached, no pay-as-you-go sub active	Enable pay-as-you-go from Settings → Billing — check X-Lumis-Reason: usage_cap_exceeded header
`RATE_LIMITED`	Too many requests in a short window	Back off and retry — token bucket refills at 10 req/s

Rate limits

Plan	Monthly simulations	Burst rate
Free	100	10 req / 10 s
Pro	25,000	10 req / 10 s
Business	100,000 + Metered	Custom SLA

Exceeding the free or pro tier limits will result in a 402 Payment Required error. Business usage is metered nightly and invoiced at month-end.