> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # List contract versions > Lists registered contract versions across the whole catalog, one page at a time. Use it to discover fact types, or every contract that declares a reference type. **Rules** - Every filter is optional and they combine: `producer`, `namespace`, `type`, `status` (`ACTIVE` or `DEPRECATED`; both by default) and `referenceType`, which answers who uses this reference type by matching every version that declares it. - Items are ordered by producer, namespace, fact type and schema version compared as text, so `1.10.0` sorts before `1.9.0`; use `listContractVersions` for semantic version order within one fact type. - Items carry no payload schema: read it with `getContract`. - Paged by an opaque cursor: pass a page's `nextCursor` to read the next page; `nextCursor` is omitted on the last page. `limit` is 1 to 100 (default 50). **Responses** - `200` one page; an empty page when nothing matches. - `422` `SF-0092` a bad filter value, `limit` or cursor. - `503` `SF-0094` retry later. ## OpenAPI ````yaml /en/openapi/v3-current/system-facts.yaml get /v1/contracts openapi: 3.1.0 info: description: > ## What System Facts does System Facts is the shared record of what happened in your business flows. Each service that takes part in a flow (a producer) sends an immutable fact when a business moment happens, such as an order placed or a payment settled. System Facts validates every fact against the contract its producer registered, stores it once, and links the facts that share a reference into one flow. A reader can then ask what happened to order `ORD-2026-000123` and get every fact of that flow, from every producer, in one answer. A stored fact never changes: System Facts records and correlates, it does not edit history. ## Concepts - **Producer**: a service that sends facts, such as `checkout-api` or `payments-api`. - **Namespace**: the dotted name a producer sends its facts under, such as `acme.checkout`; the first service that registers a contract for a producer and namespace becomes their owner. - **Fact type**: the name of one kind of business moment, such as `checkout.order_placed`. - **Contract**: one semantic version of a fact type, with the JSON Schema of its payload and the references its facts carry. - **Reference type**: a named kind of business identifier, such as `acme.order_id`, registered once with its scope, correlation, sensitivity and searchable settings. - **Reference**: one identifier a fact carries: a reference type, a value and a scope, such as `acme.order_id` `ORD-2026-000123` with scope `storeId: store-sp-01`. - **Subject**: the business entity a fact is about, given as a type and an id, such as `checkout.order` `ORD-2026-000123`. - **Fact**: one immutable record that a business moment happened, sent as an envelope with its subject, its references and its payload (`data`). - **Flow**: the group of facts linked by their references, identified by a `flowAggregationId`. - **Correlation and merge**: a reference whose type has `correlation: exact` links its fact to every fact carrying the same reference, and when one fact links two flows they merge into one, the absorbed flow id still resolving to the surviving flow. - **Sensitivity**: how a reference value or a payload field is stored and shown: `none`, `masked`, `hashed` or `encrypted`. - **Searchable**: a reference type registered with `searchable: true` can be used to list every fact that carries it. ## Integrate in four steps 1. **Register the reference types** your facts carry with `registerReferenceType`, such as `acme.order_id` and `acme.payment_id`. 2. **Register a contract version** of each fact type with `registerContract` from your deploy pipeline, before the producer rolls out: the registration must succeed before facts are accepted. 3. **Send facts** with `ingestFact`, one envelope per business moment, using the producer's service credential for the tenant. 4. **Read the flows** with `getFlow` (by flow id), `findFlowByReference` (the one flow of a reference) or `listFlowsByReference` (every fact carrying a searchable reference). Every write is idempotent, so a producer can safely resend after a timeout. ## Authentication and permissions Every request except the public health probes sends `Authorization: Bearer `. Facts and flows belong to the tenant of the token; the reference-type and contract catalogs are shared by every tenant of the deployment. | Operation | Permission | |-----------|------------| | `getReferenceType`, `listReferenceTypes`, `getContract`, `listContractVersions`, `listContracts` | `contracts:read` | | `registerReferenceType`, `registerContract` | `contracts:read`, `contracts:write` and `catalog:reserved` (every catalog name sits under a reserved prefix) | | `deprecateContract` | `contracts:read` and `contracts:write`, plus `catalog:deprecate` for a version whose namespace you do not own | | `ingestFact` | `facts:read` and `facts:write` | | `getFlow`, `findFlowByReference`, `listFlowsByReference` | `facts:read`; with `facts:reveal`, encrypted values come back in clear form | ## Conventions - **Tenant**: always taken from the token, never from a path, a query parameter or a body. - **Idempotent writes**: a first registration or ingest answers `201`; the same request again answers `200` and changes nothing (`ingestFact` adds `duplicate: true`). - **Immutability**: a contract version, a reference type and a fact never change; different content under the same identity answers `409` (a reference type may only gain a display `mask`, once). - **Pagination**: a list answers one page and a `nextCursor`; send it back as the page's cursor parameter to read the next page, treat it as opaque, and stop when it is omitted. - **Timestamps**: RFC 3339 in UTC, such as `2026-10-19T14:32:10Z`. - **Size**: a fact envelope is at most 256 KiB by default; a larger one answers `413` SF-0012. - **Names**: the first dotted segment of every namespace and reference-type name must be one of the deployment's reserved prefixes (`REFERENCE_TYPE_RESERVED_PREFIXES`, default `lerian`); this document uses `acme`. - **Errors**: every error is `application/problem+json` (RFC 9457) with a stable `code`; the table below lists every code, when it answers and whether to retry. ## Sensitivity and protected values A reference type's `sensitivity` decides how its values are shown on reads, and a contract can mark payload fields the same way with `x-sensitivity`. - `none`: returned as sent. - `masked`: returned as `****` plus the last 4 characters of a value of 12 or more (`****` alone otherwise), and never in clear form. With `mask: document` it shows `***.456.789-**` for 11 digits and `**.345.678/0001-**` for 14; any other digit count is refused at ingest. - `hashed`: returned as the keyed digest `hmac-sha256:v1:`, and never in clear form. - `encrypted`: also stored sealed (AES-256-GCM); returned masked, or in clear form to a caller holding `facts:reveal`. Every class correlates exactly as `none` does, because matching starts from the clear value, and every stored digest is keyed, never a plain hash. A protected value comes back flagged `protected: true`, and protected payload fields are listed in `protectedFields`. To find a flow by a protected reference, always send the clear value: System Facts digests it and matches the stored digest. ## Error codes | Code | HTTP | Name | When | What to do | Retry | |------|------|------|------|------------|-------| | SF-0001 | 422 | Contract Not Registered | No contract version is registered for the producer, namespace, fact type and schema version the request names (a deprecated version answers SF-0019). | Register the contract version from your deploy pipeline, before the producer rolls out, then send the request again. | After a fix | | SF-0002 | 409 | Contract Content Conflict | A contract version with the same identity is already registered with different content. | Published versions are immutable: bump the schema version, using the differences listed in errors[] to choose the bump. | No | | SF-0003 | 409 | Incompatible Contract Change | The new minor or patch version is not compatible with the versions already registered for the fact type. | Fix the schema so it stays compatible, or register the change as a new major version. | No | | SF-0004 | 422 | Invalid Contract Schema | The contract schema is not a valid, self-contained JSON Schema, or a declared reference asks for a correlation its reference type does not allow. | Give the schema an absolute $id, keep every $ref inside the document (#/$defs), and fix the members listed in errors[]. | No | | SF-0005 | 403 | Namespace Not Owned | The namespace is bound to another producer service, or the fact is sent for a producer and namespace your service did not register. | Register and send only under a namespace your service owns, with the service credential of the owning producer. | No | | SF-0006 | 422 | Invalid Envelope | The fact envelope or the query is malformed: a member is missing, has the wrong format or is not part of the envelope, or a listing period is empty. | Fix the members listed in errors[] and send the request again. | No | | SF-0007 | 422 | Payload Contract Violation | The fact payload (data) does not validate against the JSON Schema of the registered contract. | Fix the payload fields listed in errors[] so they match the contract. | No | | SF-0008 | 422 | Reference Violation | The fact carries a reference the contract does not declare, a scope key its reference type does not declare, or more than five distinct exact-correlation references. | Send only the references and scope keys that the contract and its reference types declare. | No | | SF-0009 | 404 | Flow Not Found | No flow exists with the given flow identifier. | Verify the identifier: an identifier absorbed by a merge still resolves, an unknown one does not. | No | | SF-0010 | 404 | Reference Not Found | No flow carries a reference with the given type, value and scope. | Verify the reference type, the value and every scope key of the query. | No | | SF-0011 | 409 | Ambiguous Reference | More than one flow carries the reference, so the lookup cannot choose one. | Pick a flow from candidates[] and read it by its flowAggregationId. | No | | SF-0012 | 413 | Payload Too Large | The request body is larger than the configured size limit (256 KiB by default for a fact envelope). | Reduce the request body; for a fact, send a statement about an occurrence, not a document. | No | | SF-0013 | 401 | Unauthenticated | The request carries no valid bearer token. | Send a valid bearer token issued for the tenant; a producer uses its service credential. | After a fix | | SF-0014 | 403 | Unauthorized | The token is valid but lacks a permission the operation requires, such as catalog:reserved, which every catalog registration needs because every catalog name sits under a reserved prefix. | Ask the tenant administrator to grant the permission the operation lists, then send the request again. | After a fix | | SF-0015 | 500 | Internal Error | The service failed for a reason the request did not cause. | Retry later with the same request; writes are idempotent, so a retry is safe. | Yes, later | | SF-0016 | 409 | Fact Content Conflict | A fact with the same factId is already stored with different content. | Facts are immutable: send a changed occurrence as a new fact with a new factId, and check the producer that reused the identifier. | No | | SF-0017 | 404 | Contract Version Not Found | The catalog holds no contract version with the given producer, namespace, fact type and schema version. | Verify the four path segments, and register the version from your deploy pipeline if it is missing. | No | | SF-0018 | 422 | Contract Hash Mismatch | The content hash sent with the contract does not match the content it accompanies. | Recompute the content hash over the same content you are sending. | No | | SF-0019 | 422 | Contract Version Not Active | The contract version is deprecated and no longer accepts facts. | Send the fact against an active version of the same fact type. | No | | SF-0020 | 403 | Emission Not Enabled | An operator has disabled fact emission for this tenant. | Keep the fact pending and retry later; facts are accepted again once an operator enables emission. | Yes, later | | SF-0021 | 422 | Reference Type Not Registered | The contract declares a reference type the reference-type catalog does not hold; errors[] lists every missing type. | Have the owner register each reference type before you register the contract that uses it. | After a fix | | SF-0022 | 409 | Reference Type Conflict | A reference type with the same name is already registered with a different definition. | Reference types are immutable: use a new type name for a new meaning. | No | | SF-0023 | 422 | Name Outside Reserved Prefix | The namespace or reference-type name does not start with one of the reserved prefixes of the deployment. | Use a name whose first dotted segment is a reserved prefix of the deployment. | No | | SF-0024 | 422 | Reference Type Not Searchable | Flows are listed by a reference type that is not registered, or is registered with searchable: false. | List flows only by a reference type registered with searchable: true, or read the one flow of an exact reference with findFlowByReference. | No | | SF-0025 | 422 | Invalid Payload Field Sensitivity | An x-sensitivity or x-mask annotation in the contract schema is misplaced or carries an unknown value. | Declare x-sensitivity (masked, hashed or encrypted) only on a string property reached through properties, and x-mask only next to masked or encrypted. | No | | SF-0026 | 422 | Payload Protection Unavailable | The contract version the fact names carries malformed sensitivity annotations, so its payload cannot be protected and nothing is stored. | Register a corrected contract version and send the fact against it. | After a fix | | SF-0027 | 403 | Producer Credential Required | In multi-tenant mode, the credential does not name a producer service, so namespace ownership cannot be decided. | Use the service credential of the producer for the tenant, and rotate a credential issued before it carried the producer name. | After a fix | | SF-0028 | 403 | Undeclared Source Service | In multi-tenant mode, the service credential of the producer was created without naming its producer service. | Ask the tenant administrator to recreate the credential with its producer service set; rotating the same credential does not fix this. | After a fix | | SF-0090 | 400 | Invalid Request | The request is malformed, such as a body that is not valid JSON. | Fix the request syntax and send it again. | No | | SF-0091 | 404 | Not Found | The requested resource does not exist, such as an unknown reference type or path. | Verify the path and the resource name; a reference type exists only after its owner registers it. | No | | SF-0092 | 422 | Unprocessable Request | The request does not match the request schema of the operation, such as an unexpected member or an invalid cursor. | Fix the members listed in errors[] so the request matches the schema of the operation. | No | | SF-0093 | 409 | Conflict | The request conflicts with the current state of a resource. | Read the resource again and send a request consistent with its current state. | No | | SF-0094 | 503 | Service Unavailable | The service cannot answer right now: it is starting, the authorization service is temporarily unavailable, or the correlation keys of the fact stayed busy. | Retry later with the same request, honoring Retry-After when the response carries it. | Yes, later | | SF-0095 | 429 | Rate Limit Exceeded | The caller sent more requests than the rate limit allows. | Wait for the Retry-After delay before the next request. | Yes, later | | SF-0096 | 400 | Request Failed | The request was refused for a client-side reason no more specific code describes; the response keeps the HTTP status of that reason, such as 405 or 415. | Read the detail member, fix the request and send it again. | No | title: System Facts API version: v1.0.1 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: >- The catalog of business identifiers a fact can carry, such as `acme.order_id`. Register each type once, before any contract declares it: its scope, correlation and sensitivity apply to every contract that uses it. name: Reference Types - description: >- Versioned contracts of each fact type: the payload JSON Schema and the references its facts carry. Register a version from your deploy pipeline before the producer rolls out, read it back, list the catalog, and deprecate a version you no longer send. name: Contracts - description: >- Send one immutable fact per business moment. Each fact is validated against its active contract version and linked to a flow through its references. name: Facts - description: >- Read what happened: one flow by its id, the flow of one reference, or every fact carrying a searchable reference. Protected values come back in their protected form unless you hold `facts:reveal`. name: Flows paths: /v1/contracts: get: tags: - Contracts summary: List contract versions description: >- Lists registered contract versions across the whole catalog, one page at a time. Use it to discover fact types, or every contract that declares a reference type. **Rules** - Every filter is optional and they combine: `producer`, `namespace`, `type`, `status` (`ACTIVE` or `DEPRECATED`; both by default) and `referenceType`, which answers who uses this reference type by matching every version that declares it. - Items are ordered by producer, namespace, fact type and schema version compared as text, so `1.10.0` sorts before `1.9.0`; use `listContractVersions` for semantic version order within one fact type. - Items carry no payload schema: read it with `getContract`. - Paged by an opaque cursor: pass a page's `nextCursor` to read the next page; `nextCursor` is omitted on the last page. `limit` is 1 to 100 (default 50). **Responses** - `200` one page; an empty page when nothing matches. - `422` `SF-0092` a bad filter value, `limit` or cursor. - `503` `SF-0094` retry later. operationId: listContracts parameters: - description: Only contract versions of this producer. explode: false in: query name: producer schema: description: Only contract versions of this producer. maxLength: 64 type: string - description: Only contract versions in this namespace. explode: false in: query name: namespace schema: description: Only contract versions in this namespace. maxLength: 128 type: string - description: Only contract versions of this fact type. explode: false in: query name: type schema: description: Only contract versions of this fact type. maxLength: 128 type: string - description: >- Only contract versions in this lifecycle status; every status by default. Allowed values: `ACTIVE`, `DEPRECATED`. explode: false in: query name: status schema: description: >- Only contract versions in this lifecycle status; every status by default. Allowed values: `ACTIVE`, `DEPRECATED`. enum: - ACTIVE - DEPRECATED type: string - description: >- Only contract versions that declare this reference type ("who uses this type"). explode: false in: query name: referenceType schema: description: >- Only contract versions that declare this reference type ("who uses this type"). examples: - acme.order_id maxLength: 128 type: string - description: Page size, from 1 to 100; defaults to 50. explode: false in: query name: limit schema: default: 50 description: Page size, from 1 to 100; defaults to 50. format: int64 maximum: 100 minimum: 1 type: integer - description: >- Opaque `nextCursor` of the previous page; omit it to read the first page. explode: false in: query name: cursor schema: description: >- Opaque `nextCursor` of the previous page; omit it to read the first page. maxLength: 256 type: string responses: '200': content: application/json: examples: whoUsesOrderId: summary: The two contract versions that declare acme.order_id value: items: - producer: checkout-api namespace: acme.checkout type: checkout.order_placed schemaVersion: 1.0.0 status: ACTIVE hash: >- sha256:eb6a1bb7bc5d2d9315dd133af563678ec0dab58488b23fcb0179ee54ea43c34c team: checkout-squad createdAt: '2026-10-19T12:00:00Z' referenceTypes: - acme.order_id - acme.customer_document - producer: payments-api namespace: acme.payments type: payments.payment_settled schemaVersion: 1.0.0 status: ACTIVE hash: >- sha256:52d037060d5031b8435ff5b4cc76fc2ddf0314cee12ebc17ddb24c4227456125 team: payments-squad createdAt: '2026-10-19T12:00:00Z' referenceTypes: - acme.payment_id - acme.order_id limit: 50 schema: $ref: '#/components/schemas/ContractPageBody' description: >- One page of contract versions without their payload schemas, in text order, empty when nothing matches; `nextCursor` is omitted on the last page. '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: '`SF-0013` The request carries no valid bearer token.' '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: '`SF-0014` The token lacks the `contracts:read` permission.' '422': content: application/problem+json: examples: malformedCursor: summary: A cursor that is not the nextCursor of a previous page value: code: SF-0092 detail: >- Fix the members listed in errors[] so the request matches the schema of the operation. errors: - location: query.cursor message: invalid catalog cursor instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 422 title: Unprocessable Entity type: https://errors.lerian.studio/v1/SF-0092 schema: $ref: '#/components/schemas/Detail' description: >- `SF-0092` A filter value, `limit` or `cursor` is invalid; `errors[]` names the query member. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- `SF-0015` The service failed for a reason the request did not cause: retry later. '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- `SF-0094` The service is starting, or the authorization service is temporarily unavailable: retry later. security: - BearerAuth: [] components: schemas: ContractPageBody: additionalProperties: false properties: items: description: >- Contract versions of this page in cursor order, without their payload schemas; read one with `getContract`. items: $ref: '#/components/schemas/ContractSummaryBody' type: - array - 'null' limit: description: Page size applied to this request, after the maximum of 100. format: int64 type: integer nextCursor: description: >- Opaque cursor of the next page: send it back as `cursor`. Omitted on the last page. type: string required: - items - limit type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- Identifier of this occurrence of the problem: the request's trace id (32 lowercase hex characters), to quote when asking for support. examples: - 0199c1f07a3e7b219d443c1f8e2a9b01 type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ContractSummaryBody: additionalProperties: false properties: createdAt: description: When this version was registered. RFC 3339, UTC. format: date-time type: string hash: description: >- Content hash verified at registration (the prefix sha256: plus 64 hex characters). type: string namespace: description: Namespace of the fact type. examples: - acme.checkout type: string producer: description: Producer service that owns the fact type. examples: - checkout-api type: string referenceTypes: description: >- Names of the reference types this version declares, in declaration order. items: type: string type: - array - 'null' schemaVersion: description: Semantic version of this contract (major.minor.patch). examples: - 1.0.0 type: string status: description: >- Lifecycle status: a `DEPRECATED` version refuses new facts and never returns to `ACTIVE`. Allowed values: `ACTIVE`, `DEPRECATED`. enum: - ACTIVE - DEPRECATED type: string team: description: >- Owning team or squad, as registered; informational, never an identity. examples: - checkout-squad type: string type: description: Fact type name. examples: - checkout.order_placed type: string required: - producer - namespace - type - schemaVersion - status - hash - team - createdAt - referenceTypes type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: >- JWT issued by the identity provider. A producer calls with a service credential issued for the tenant it sends facts for; a reader calls with a user token or a service credential. The tenant is always taken from the token, never from the request path, query or body. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.