> ## 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. # Read a reference type > Reads one registered reference type: its scope keys, correlation, sensitivity, mask and whether it is searchable. Producers call it to check a type before declaring it in a contract. **Rules** - The name is the whole identity. - An unregistered name answers `404`, including a name that could never be registered: the read never tells whether a name is well-formed. **Responses** - `200` the reference type. - `404` `SF-0091` no reference type under this name. - `503` `SF-0094` retry later. ## OpenAPI ````yaml /pt/openapi/v3-current/system-facts.yaml get /v1/reference-types/{type} 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/reference-types/{type}: get: tags: - Reference Types summary: Read a reference type description: >- Reads one registered reference type: its scope keys, correlation, sensitivity, mask and whether it is searchable. Producers call it to check a type before declaring it in a contract. **Rules** - The name is the whole identity. - An unregistered name answers `404`, including a name that could never be registered: the read never tells whether a name is well-formed. **Responses** - `200` the reference type. - `404` `SF-0091` no reference type under this name. - `503` `SF-0094` retry later. operationId: getReferenceType parameters: - description: Name of the reference type to read. in: path name: type required: true schema: description: Name of the reference type to read. examples: - acme.order_id type: string responses: '200': content: application/json: examples: orderId: summary: The order id reference type of the Acme checkout value: type: acme.order_id scope: - storeId sensitivity: none correlation: exact searchable: true description: >- Order number assigned by the checkout service, unique within a store ownerIdentity: acme/platform-deployer createdAt: '2026-10-19T12:00:00Z' schema: $ref: '#/components/schemas/ReferenceTypeBody' description: >- The reference type as registered: its scope keys, correlation, sensitivity, mask and whether it is searchable. '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.' '404': content: application/problem+json: examples: unknownType: summary: No reference type is registered under the name value: code: SF-0091 detail: >- Verify the path and the resource name; a reference type exists only after its owner registers it. instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 404 title: Not Found type: https://errors.lerian.studio/v1/SF-0091 schema: $ref: '#/components/schemas/Detail' description: >- `SF-0091` No reference type is registered under this name, including a name that could never be registered. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Not answered by this operation: a malformed name answers `404` `SF-0091`. '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: ReferenceTypeBody: additionalProperties: false properties: correlation: description: >- Whether references of this type link facts into flows. Allowed values: `exact`, `none`. enum: - exact - none type: string createdAt: description: When the type was registered. RFC 3339, UTC. format: date-time type: string description: description: What the reference identifies, as registered. type: string mask: description: >- Display format of the type; omitted when it has none. Allowed values: `document`. enum: - document type: string ownerIdentity: description: >- Verified identity that registered the type, in the form owner/sub; recorded for audit only. examples: - acme/platform-deployer type: string scope: description: Scope keys that complete the reference identity, sorted. items: type: string type: - array - 'null' searchable: description: Whether `listFlowsByReference` can list facts by this type. type: boolean sensitivity: description: >- Protection of values at rest and on reads; see Sensitivity and protected values. Allowed values: `none`, `masked`, `hashed`, `encrypted`. enum: - none - masked - hashed - encrypted type: string type: description: Reference type name. examples: - acme.order_id type: string required: - type - scope - sensitivity - correlation - searchable - description - ownerIdentity - createdAt 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 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.