Records

Records are the materialised projections that you read and write. Each record contains a flat data object where all fields — whether contributed by external sources or computed by the platform — appear as a single data surface.

Records are not created directly through the API. They are created by the platform's resolution pipeline when contributions are processed. You can read, update, and delete records.

Endpoints

Method	Path	Description
GET	/records	List records
GET	/records/{recordId}	Get a record
PATCH	/records/{recordId}	Update a record
DELETE	/records/{recordId}	Delete a record
PATCH	/records/bulk	Batch update records
DELETE	/records/bulk	Batch delete records

All endpoints are unscoped — the record UUID is globally unique.

Get a record

GET /records/{recordId}

Response 200 OK

{
  "recordId": "01957c3a-def0-7000-8000-000000000001",
  "modelId": "01957c3a-1234-7000-8000-000000000001",
  "contextId": "01957c3a-5678-7000-8000-000000000001",
  "freshness": "resolved",
  "sha256": "a1b2c3d4e5f6...",
  "data": {
    "firstName": "Sarah",
    "lastName": "Jones",
    "annualIncome": 54800,
    "totalExposure": 1250000
  },
  "createdAt": "2026-02-10T14:30:00Z",
  "updatedAt": "2026-02-13T09:15:00Z",
  "createdBy": "user_01957c3a-..."
}

Freshness

The freshness field indicates whether the record reflects all available evidence:

Value	Meaning
resolved	All evidence has been processed. The data is current.
stale	New evidence has arrived but has not been processed yet.
computing	The platform is currently re-resolving the record.

Always check freshness before making decisions based on record data. If freshness is stale or computing, the data may not reflect the latest evidence.

Content integrity

The sha256 field is a SHA-256 hash of the record's data object, computed by the platform on every materialisation pass. You can compare a locally held hash against the current value to detect changes without re-fetching the full record body. The hash is immutable between version bumps — if the sha256 has not changed, the data has not changed.

For full details on ETags, optimistic concurrency, and content integrity, see Versioning & Concurrency.

Including model context

Pass ?include=modelContext to add field descriptions, types, resolution policies, and relationship topology to the response. This is useful for LLM consumers and UIs that need to understand the data shape:

GET /records/{recordId}?include=modelContext

{
  "recordId": "01957c3a-...",
  "modelId": "01957c3a-...",
  "contextId": "01957c3a-...",
  "freshness": "resolved",
  "sha256": "a1b2c3d4e5f6...",
  "data": {
    "firstName": "Sarah",
    "annualIncome": 54800
  },
  "modelContext": {
    "fields": {
      "firstName": {
        "type": "text",
        "description": "Applicant's legal first name",
        "resolutionPolicy": "latest_wins",
        "contributorCount": 2
      },
      "annualIncome": {
        "type": "currency",
        "description": "Gross annual income from primary employment",
        "resolutionPolicy": "highest_confidence",
        "contributorCount": 3
      }
    },
    "relationships": {
      "applicant_employment": {
        "count": 2,
        "targetModel": "Employment"
      },
      "application_collateral": {
        "count": 1,
        "targetModel": "Property"
      }
    }
  },
  "createdAt": "2026-02-10T14:30:00Z",
  "updatedAt": "2026-02-13T09:15:00Z",
  "createdBy": "user_01957c3a-..."
}

List records

GET /records

Supports standard filtering and sorting.

Useful filters

GET /records?filter[contextId][eq]=uuid          # All records in a context
GET /records?filter[modelId][eq]=uuid            # All records of a type
GET /records?filter[freshness][eq]=resolved      # Only resolved records
GET /records?filter[data.annualIncome][gte]=50000 # Filter on dynamic fields

Update a record

PATCH /records/{recordId}

Every update is a partial update — provide only the fields you want to change. The platform creates a contribution internally (at maximum confidence) and marks the containing context stale for reprocessing.

Request

{
  "data": {
    "annualIncome": 55000
  }
}

Response 200 OK

{
  "recordId": "01957c3a-...",
  "modelId": "01957c3a-...",
  "contextId": "01957c3a-...",
  "freshness": "stale",
  "data": {
    "firstName": "Sarah",
    "lastName": "Jones",
    "annualIncome": 55000
  },
  "createdAt": "2026-02-10T14:30:00Z",
  "updatedAt": "2026-02-20T11:00:00Z"
}

The record is returned immediately with freshness: stale. Once the platform resolves the new contribution, freshness transitions to resolved.

Computed fields are read-only. If your PATCH includes values for fields defined as computed in the model, the request is rejected with 422 Unprocessable Entity.

Delete a record

DELETE /records/{recordId}

Performs a soft delete — the record is excluded from list results and system operations but retained for auditing. Bound contributions are preserved as immutable evidence. Relationships involving the deleted record are also soft-deleted, and dependent rule evaluations are marked stale.

Response 204 No Content

Bulk operations

See Bulk Operations for the general pattern.

PATCH  /records/bulk   # Batch update
DELETE /records/bulk    # Batch delete

Each item in the array carries its own recordId and is processed independently with partial success semantics.