Decisioning Contexts

A decisioning context is the boundary around a decision — a mortgage case, a loan application, an onboarding journey. It contains exactly the records, contributions, relationships, and rule evaluations relevant to that decision. Data within one context cannot leak into another.

Endpoints

Method	Path	Description
POST	/contexts	Create a context
GET	/contexts	List contexts
GET	/contexts/{contextId}	Get a context
PATCH	/contexts/{contextId}	Update context metadata
PUT	/contexts/{contextId}/status/{targetStatus}	Lifecycle transition
DELETE	/contexts/{contextId}	Delete a context

Two status dimensions

Contexts carry two independent status dimensions:

Business status

The business lifecycle, managed explicitly by you:

active ⇄ completed → archived

Status	Meaning
active	The decision is in progress. Accepts new evidence, pipeline processing is live.
completed	The decision has been made. The context is frozen for the customer but remains queryable.
archived	Cold storage. No new records, contributions, or evidence can be added.

The transition from active to completed is reversible — a completed context can be reopened to active if it receives a late correction or amendment. The transition to archived is permanent.

Freshness

The pipeline state, managed automatically by the platform:

Value	Meaning
resolved	All evidence has been processed.
stale	New evidence has arrived but has not been processed yet.
computing	The platform is currently processing.

These dimensions are independent. A context can be completed (business decision made) and stale (late evidence being processed) at the same time.

Create a context

POST /contexts

Request

{
  "name": "Sarah Jones — Mortgage Application",
  "type": "mortgage_application",
  "metadata": {
    "applicationRef": "APP-2026-00142"
  }
}

Field	Required	Description
name	No	Human-readable name
type	No	Classification (e.g., mortgage_application, onboarding)
metadata	No	Arbitrary key-value pairs for customer-defined properties

Response 201 Created

{
  "contextId": "01957c3a-5678-7000-8000-000000000001",
  "name": "Sarah Jones — Mortgage Application",
  "type": "mortgage_application",
  "status": "active",
  "freshness": "resolved",
  "metadata": {
    "applicationRef": "APP-2026-00142"
  },
  "createdAt": "2026-02-20T10:01:00Z",
  "updatedAt": "2026-02-20T10:01:00Z",
  "createdBy": "user_01957c3a-..."
}

A new context starts with status: active and freshness: resolved (no evidence yet).

Get a context

GET /contexts/{contextId}

Returns the context with both status dimensions.

Pass ?include=summary to add record counts, rule evaluation outcomes, and staleness indicators:

GET /contexts/{contextId}?include=summary

{
  "contextId": "01957c3a-5678-7000-8000-000000000001",
  "name": "Sarah Jones — Mortgage Application",
  "status": "active",
  "freshness": "resolved",
  "summary": {
    "recordCount": 3,
    "contributionCount": 7,
    "evaluations": {
      "total": 5,
      "passed": 3,
      "failed": 1,
      "stale": 1
    }
  },
  "createdAt": "2026-02-20T10:01:00Z",
  "updatedAt": "2026-02-20T14:30:00Z"
}

List contexts

GET /contexts

Supports standard filtering and sorting.

Useful filters

GET /contexts?filter[status][eq]=active                # Open cases
GET /contexts?filter[freshness][eq]=resolved           # Fully resolved
GET /contexts?filter[type][eq]=mortgage_application    # By type
GET /contexts?filter[createdAt][gte]=2026-01-01T00:00:00Z  # By date range

Update context metadata

PATCH /contexts/{contextId}

Updates context metadata — name, type, and customer-defined properties. status and freshness are not modifiable through PATCH.

Request

{
  "name": "Sarah Jones — Mortgage Application (Amended)",
  "metadata": {
    "applicationRef": "APP-2026-00142",
    "amendmentReason": "Income correction"
  }
}

Response 200 OK

Returns the full updated context.

Lifecycle transition

PUT /contexts/{contextId}/status/{targetStatus}

Transitions the business lifecycle. The server validates that the transition is permitted.

Examples

# Complete a case
PUT /contexts/{contextId}/status/completed

# Reopen a completed case (e.g., late amendment received)
PUT /contexts/{contextId}/status/active

# Archive a completed case
PUT /contexts/{contextId}/status/archived

Completing a context does not affect its freshness — if evidence is still being processed, the pipeline converges independently.

Reopening a completed context transitions it back to active, allowing new evidence and pipeline processing to resume.

Archiving a context freezes it entirely — no new records, contributions, or evidence can be added. Archival is permanent and cannot be reversed.

Error cases

Scenario	Status
Invalid transition (e.g., archived → active)	422 Unprocessable Entity

Delete a context

DELETE /contexts/{contextId}

Performs a soft delete — the context is excluded from list results but retained with all its data for auditing.

Precondition

The context must be in archived status. If not, the request is rejected with 409 Conflict.

Scenario	Status
Context not archived	409 Conflict

Response 204 No Content

Resolution

When evidence arrives (via contribution ingestion or record update), the containing context is marked stale. The platform's resolution pipeline automatically processes stale contexts — claiming the context, running the full resolution pass, and atomically persisting the results. The context transitions through computing and back to resolved when processing completes.

You do not need to trigger resolution manually. To observe convergence, either poll the context's freshness field or subscribe to webhook events.