Provenance

The Provenance API is the machine-readable side of Decision Provenance: pull the sealed lineage of any decision, and collect the PII reveal audit ledger on a schedule. All endpoints authenticate with an API key and return the standard {result, data} envelope.

Base URL: https://api.lexq.io/api/v1/partners
Header:   x-api-key: YOUR_API_KEY

Get a Decision’s Lineage

GET /provenance/{traceId}

Roles: Admin, User, Viewer, API client.

Path parameter	Description
`traceId`	Trace ID of the execution, as returned by the Execution API or listed in execution history

curl "https://api.lexq.io/api/v1/partners/provenance/8f3c1a2e-1d44-4c1b-9a3e-0f5b7c2d9e10" \
  -H "x-api-key: YOUR_API_KEY"

Response, abridged — facts marked as PII arrive masked, and maskedKeys names them:

{
  "result": "SUCCESS",
  "data": {
    "traceId": "8f3c1a2e-1d44-4c1b-9a3e-0f5b7c2d9e10",
    "requestFacts": {
      "customer_segment": "••••••",
      "purchase_subtotal_usd": 129.9
    },
    "maskedKeys": ["customer_segment"],
    "lineage": {
      "authored":  { "name": "Jane Kim", "at": "2026-06-28T09:14:02Z" },
      "published": { "name": "Jane Kim", "at": "2026-06-30T11:40:55Z" },
      "deployed":  { "name": "Jane Kim", "at": "2026-07-01T08:02:19Z" }
    }
  }
}

The full payload additionally carries the decision outcome, the deterministic reason for every evaluated rule, and the rule snapshot fingerprint.

Error	Status	Meaning
`AN-026`	404	Decision trace not found

PII Reveal — Not an API Surface

Revealing a masked value is deliberately console-only (Admin and User roles). API keys calling POST /provenance/{traceId}/reveal receive 403 — an integration or agent can never pull PII plaintext. Every console reveal writes an audit row before the value is shown, and revealing a fact that is not marked as PII fails with AN-027.

List Reveal Audits

GET /provenance/reveal-audits

Roles: Admin, User, Viewer, API client — the ledger is readable by more roles than can reveal, because oversight is broader than the act.

Query parameter	Match	Description
`page`, `size`	—	Zero-based page and page size
`traceId`	Exact	Filter by trace
`revealedBy`	Exact	Filter by operator ID
`factKey`	Partial, case-insensitive	Filter by fact key
`startDate`, `endDate`	Tenant timezone	Date range (`yyyy-MM-dd`)

Results are fixed to reverse-chronological order.

curl "https://api.lexq.io/api/v1/partners/provenance/reveal-audits?startDate=2026-07-01&factKey=customer&size=50" \
  -H "x-api-key: YOUR_API_KEY"

{
  "result": "SUCCESS",
  "data": {
    "content": [
      {
        "traceId": "8f3c1a2e-1d44-4c1b-9a3e-0f5b7c2d9e10",
        "factKey": "customer_segment",
        "revealedBy": "6a2f31c0-9b7d-4e2a-8c11-3d5e9f0a1b2c",
        "revealedByName": "Jane Kim",
        "revealedAt": "2026-07-06T14:23:11Z"
      }
    ],
    "pageNo": 0,
    "totalPages": 1,
    "totalElements": 7
  }
}

Values are never present — the ledger stores who revealed which fact of which trace, and when. Nothing else exists to leak.

SIEM collection — schedule this endpoint with an API key (for example, daily with yesterday’s date range) to automate the periodic access-log inspection that privacy regulations commonly require. The response is already the report.

Retention Guarantees

Lineage stays resolvable because audit retention refuses to delete what it references: a version with recorded executions cannot be removed (AN-028), and if an audit record cannot be sealed, the operation itself is rejected (AN-029). See the error reference for the full code table.

Overview

Policy Execution

Get a Decision’s Lineage

PII Reveal — Not an API Surface

List Reveal Audits

Retention Guarantees

​Get a Decision’s Lineage

​PII Reveal — Not an API Surface

​List Reveal Audits

​Retention Guarantees

Get a Decision’s Lineage

PII Reveal — Not an API Surface

List Reveal Audits

Retention Guarantees