Live Contexts

When you submit data to a Context, you create a live context: an instance that accumulates facts over time until rules can execute.

Context = the schema definition (what facts you need for loan approval)
Live context = a specific instance (loan application APP-12345's data)

Lifecycle

A live context is created when you first submit data for a new identity:

POST /api/v1/contexts/loan-application/APP-12345
{ "annual_income": 85000 }

It persists as you submit more facts over time. Each submission merges into the existing state: new fields are added, existing fields are updated, missing fields are left alone.

When all schema-required facts are present, the status changes from pending to complete. This status describes the instance as a whole; an individual bound rule can execute earlier as soon as that rule's own inputs are present.

Eventually, live contexts expire based on their TTL (time-to-live) setting. Expired contexts are no longer accessible; POST requests to that identity create a fresh instance.

The Have/Need Pattern

Every API response tells you exactly where you stand:

{
  "status": "pending",
  "have": ["application_id", "credit_score", "annual_income"],
  "need": ["employment_verified"],
  "expires_at": "2024-01-22T10:30:00Z"
}

have: facts with values
need: required facts still missing
status: pending until need is empty, then complete

This makes it easy to show progress in your UI, decide what to fetch next, or debug why a rule isn't executing.

TTL and Expiration

Set TTL when creating your context (1 minute to 30 days). Each write to an instance extends its expiry by the full TTL, so actively-updated instances stay alive and idle ones age out.

Fetching State

Get the current state of any live context:

GET /api/v1/contexts/loan-application/APP-12345

The response reports base facts under state and expression-computed facts under a separate derived object, alongside the have/need arrays, per-asset execution metadata, timestamps, and expiration time. (POST responses combine base and derived facts in state.) Add ?include_relations=* (or a comma-separated list of relationship names) to embed related live instances in the response.

Instances can also be deleted explicitly. DELETE to the same path removes the instance and cancels any pending evaluations registered for it.

Facts & Schema Execution Mode