> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lexq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Provenance

> Read decision lineage and the PII reveal audit ledger programmatically — built for audit automation and SIEM collection.

The Provenance API is the machine-readable side of [Decision Provenance](/guides/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.

```text theme={null}
Base URL: https://api.lexq.io/api/v1/partners
Header:   x-api-key: YOUR_API_KEY
```

## Get a Decision's Lineage

```text theme={null}
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 |

```bash theme={null}
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:

```json theme={null}
{
  "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

```text theme={null}
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.

```bash theme={null}
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"
```

```json theme={null}
{
  "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.

<Info>
  **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.
</Info>

## 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](/api/errors) for the full code table.