> ## 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. # Find the flow of a reference > Finds the one flow a reference belongs to, such as an order number, and pages through its facts. **Rules** - Send the reference as `referenceType` and `referenceValue`. Every other query parameter except `factsLimit` and `factsCursor` is a scope key, such as `storeId=store-sp-01` for `acme.order_id`. - Scope matches by containment: no scope matches every scope of that type and value, a partial scope narrows the search, the full declared scope matches at most one reference. Sending a fact needs exactly the declared scope keys. - `referenceValue` is always the clear value, also for a protected type. - The answer is always the current flow, so it never carries `merge`. - Facts are paged: pass `nextCursor` as `factsCursor`; it is omitted on the last page. `factsLimit` is 1 to 500 (default 100). - Protected values come back protected; `facts:reveal` returns encrypted ones in clear form and never refuses the request. See *Sensitivity and protected values*. Responses carry `Cache-Control: no-store`. **Responses** - `200` the current flow and one page of its facts. - `404` `SF-0010` no reference matches. - `409` `SF-0011` several flows match: pick one from `candidates[]` and read it with `getFlow`. - `422` `SF-0006` a malformed reference or cursor; `SF-0092` a schema mismatch. - `503` `SF-0094` retry later. ## OpenAPI ````yaml /en/openapi/v3-current/system-facts.yaml get /v1/flows/by-reference 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/flows/by-reference: get: tags: - Flows summary: Find the flow of a reference description: >- Finds the one flow a reference belongs to, such as an order number, and pages through its facts. **Rules** - Send the reference as `referenceType` and `referenceValue`. Every other query parameter except `factsLimit` and `factsCursor` is a scope key, such as `storeId=store-sp-01` for `acme.order_id`. - Scope matches by containment: no scope matches every scope of that type and value, a partial scope narrows the search, the full declared scope matches at most one reference. Sending a fact needs exactly the declared scope keys. - `referenceValue` is always the clear value, also for a protected type. - The answer is always the current flow, so it never carries `merge`. - Facts are paged: pass `nextCursor` as `factsCursor`; it is omitted on the last page. `factsLimit` is 1 to 500 (default 100). - Protected values come back protected; `facts:reveal` returns encrypted ones in clear form and never refuses the request. See *Sensitivity and protected values*. Responses carry `Cache-Control: no-store`. **Responses** - `200` the current flow and one page of its facts. - `404` `SF-0010` no reference matches. - `409` `SF-0011` several flows match: pick one from `candidates[]` and read it with `getFlow`. - `422` `SF-0006` a malformed reference or cursor; `SF-0092` a schema mismatch. - `503` `SF-0094` retry later. operationId: findFlowByReference parameters: - description: Registered reference type to look up, dotted and lower-case. explode: false in: query name: referenceType required: true schema: description: Registered reference type to look up, dotted and lower-case. examples: - acme.order_id maxLength: 128 minLength: 1 type: string - description: >- Reference value to look up: always the clear value, also for a protected type. explode: false in: query name: referenceValue required: true schema: description: >- Reference value to look up: always the clear value, also for a protected type. examples: - ORD-2026-000123 maxLength: 512 minLength: 1 type: string - description: Facts per page, from 1 to 500. Default 100. explode: false in: query name: factsLimit schema: default: 100 description: Facts per page, from 1 to 500. Default 100. format: int64 maximum: 500 minimum: 1 type: integer - description: >- Opaque `nextCursor` of the previous page; omit it to read the first page. explode: false in: query name: factsCursor schema: description: >- Opaque `nextCursor` of the previous page; omit it to read the first page. maxLength: 1024 type: string responses: '200': content: application/json: examples: byOrderId: description: >- Sent with `storeId=store-sp-01`, the scope key of `acme.order_id`. summary: Order ORD-2026-000123 of store store-sp-01 leads to its flow value: flowAggregationId: 01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33 createdAt: '2026-10-19T14:32:11Z' updatedAt: '2026-10-19T14:32:11Z' facts: items: - factId: 01a15493-ba10-7b21-9d44-3c1f8e2a9b01 producer: checkout-api namespace: acme.checkout type: checkout.order_placed schemaVersion: 1.0.0 occurredAt: '2026-10-19T14:32:10Z' subject: type: checkout.order id: ORD-2026-000123 references: - type: acme.order_id value: ORD-2026-000123 scope: storeId: store-sp-01 - type: acme.customer_document value: '***.456.789-**' scope: {} sensitivity: masked protected: true data: amount: '129.90' currency: BRL customerDocument: '***.456.789-**' protectedFields: - path: /customerDocument sensitivity: masked protected: true ingestedAt: '2026-10-19T14:32:11Z' - factId: 01a15496-59f0-7c32-8e55-4d2a9f3b0c12 producer: payments-api namespace: acme.payments type: payments.payment_confirmed schemaVersion: 1.0.0 occurredAt: '2026-10-19T14:35:02Z' subject: type: payments.payment id: PAY-7f3a2c91 references: - type: acme.payment_id value: PAY-7f3a2c91 scope: {} data: amount: '129.90' currency: BRL method: card ingestedAt: '2026-10-19T14:35:03Z' - factId: 01a1549a-e600-7d43-9f66-5e3b0a4c1d23 producer: payments-api namespace: acme.payments type: payments.payment_settled schemaVersion: 1.0.0 occurredAt: '2026-10-19T14:40:00Z' subject: type: payments.payment id: PAY-7f3a2c91 references: - type: acme.payment_id value: PAY-7f3a2c91 scope: {} - type: acme.order_id value: ORD-2026-000123 scope: storeId: store-sp-01 data: amount: '129.90' currency: BRL ingestedAt: '2026-10-19T14:40:01Z' limit: 100 schema: $ref: '#/components/schemas/FlowBody' description: >- The current flow of the reference and one page of its facts; it never carries `merge`. headers: Cache-Control: schema: description: >- Always `no-store`: a flow read can carry revealed clear values and must never be cached. type: string '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 `facts:read` permission. Lacking `facts:reveal` never refuses a read. '404': content: application/problem+json: examples: unknownReference: summary: No order with this number in the store value: code: SF-0010 detail: >- Verify the reference type, the value and every scope key of the query. instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 404 title: Not Found type: https://errors.lerian.studio/v1/SF-0010 schema: $ref: '#/components/schemas/Detail' description: >- `SF-0010` No reference matches this type, value and scope: check the type, the clear value and the scope keys. '409': content: application/problem+json: examples: ambiguousReference: description: >- Sent without `storeId`. Store store-rj-02 also numbered an order ORD-2026-000123, so the number alone matches the flow of each store; send `storeId` to pick one. summary: Without its store scope, the order number matches two flows value: candidates: - flowAggregationId: 01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33 factCount: 3 updatedAt: '2026-10-19T14:32:11Z' - flowAggregationId: 01a154b1-f840-7e77-b204-8b6c3f9a1e55 factCount: 1 updatedAt: '2026-10-19T15:05:12Z' code: SF-0011 detail: >- Pick a flow from candidates[] and read it by its flowAggregationId. instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 409 title: Conflict type: https://errors.lerian.studio/v1/SF-0011 schema: allOf: - $ref: '#/components/schemas/Detail' - properties: candidates: description: >- Flows the reference matches, one entry per flow: pick one and read it with `getFlow`. items: $ref: '#/components/schemas/CandidateBody' type: array required: - candidates type: object description: >- `SF-0011` The reference matches more than one flow, such as when the scope is partial. `candidates[]` lists each flow's `flowAggregationId`, `factCount` and `updatedAt`: pick one and read it with `getFlow`. '422': content: application/problem+json: examples: malformedCursor: summary: A factsCursor that is not the nextCursor of a previous page value: code: SF-0006 detail: >- Fix the members listed in errors[] and send the request again. instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 422 title: Unprocessable Entity type: https://errors.lerian.studio/v1/SF-0006 schema: $ref: '#/components/schemas/Detail' description: >- `SF-0006` The reference type, the value, a scope key or `factsCursor` is malformed. `SF-0092` A parameter does not match the request schema, such as a missing `referenceType` or a `factsLimit` out of range; `errors[]` names the 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: FlowBody: additionalProperties: false properties: createdAt: description: When the flow was first created. RFC 3339, UTC. format: date-time type: string facts: $ref: '#/components/schemas/FactPageBody' description: One page of the flow's facts. flowAggregationId: description: >- Current id of the flow, assigned by the server and opaque. Store it in place of any absorbed id. type: string merge: $ref: '#/components/schemas/FlowMergeBody' description: >- Present only when the requested id was absorbed by a merge; replace any stored id with `flowAggregationId`. updatedAt: description: >- When the flow record itself last changed; adding facts or merges does not change it, so today it equals `createdAt`. RFC 3339, UTC. format: date-time type: string required: - flowAggregationId - createdAt - updatedAt - facts 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 CandidateBody: additionalProperties: false properties: factCount: description: Number of facts the flow holds. format: int64 type: integer flowAggregationId: description: >- Id of one flow the reference matches, assigned by the server and opaque; read it with `getFlow`. type: string updatedAt: description: >- When the flow record itself was last modified; attaching facts or merging flows does not change it. RFC 3339, UTC. format: date-time type: string required: - flowAggregationId - factCount - updatedAt type: object FactPageBody: additionalProperties: false properties: items: description: >- Facts of this page, ordered by `occurredAt`, ties in a stable server order. items: $ref: '#/components/schemas/FactViewBody' type: - array - 'null' limit: description: Page size applied, after the default and the maximum. format: int64 type: integer nextCursor: description: >- Opaque cursor of the next page: send it back as `factsCursor`. Omitted on the last page. type: string required: - items - limit type: object FlowMergeBody: additionalProperties: false properties: absorbedId: description: The id you requested, which a merge absorbed into the current flow. type: string mergedAt: description: >- When the first merge that absorbed the requested id happened. RFC 3339, UTC. format: date-time type: string mergedBy: $ref: '#/components/schemas/FlowMergedByBody' description: The fact whose ingestion caused that merge. required: - absorbedId - mergedAt - mergedBy 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 FactViewBody: additionalProperties: false properties: data: description: >- Payload, validated against the contract's JSON Schema. Fields marked `x-sensitivity` are listed in `protectedFields` and hold their protected form unless revealed. factId: description: Identifier the producer assigned to this occurrence (UUID). type: string ingestedAt: description: When System Facts first stored the fact. RFC 3339, UTC. format: date-time type: string namespace: description: Namespace the fact's contract is registered under. type: string occurredAt: description: >- When the business event happened, as the producer reported it. RFC 3339, UTC. format: date-time type: string producer: description: Producer that sent the fact. type: string protectedFields: description: >- Payload fields the contract marks with `x-sensitivity`, sorted by `path`. Omitted when there are none. items: $ref: '#/components/schemas/ProtectedFieldBody' type: - array - 'null' references: description: >- Typed references the fact carries, in the order the producer sent them. items: $ref: '#/components/schemas/ReferenceBody' type: - array - 'null' schemaVersion: description: Contract version (semantic version) the payload follows. type: string subject: $ref: '#/components/schemas/SubjectBody' description: Business entity the fact is about. type: description: Fact type, as the contract declares it. type: string required: - factId - producer - namespace - type - schemaVersion - occurredAt - subject - references - data - ingestedAt type: object FlowMergedByBody: additionalProperties: false properties: factId: description: '`factId` of the fact whose ingestion merged the flows.' type: string producer: description: Producer of the fact whose ingestion merged the flows. type: string required: - producer - factId type: object ProtectedFieldBody: additionalProperties: false properties: path: description: JSON Pointer (RFC 6901) to the protected field inside `data`. type: string protected: description: >- True when the value at `path` is not the clear form. False only for an encrypted field revealed to a `facts:reveal` holder. type: boolean sensitivity: description: >- Protection class the contract gives this payload field through `x-sensitivity`. Allowed values: `masked`, `hashed`, `encrypted`. enum: - masked - hashed - encrypted type: string required: - path - sensitivity - protected type: object ReferenceBody: additionalProperties: false properties: protected: description: >- True when `value` is not the clear form. Omitted when it is: for `none`, and for an encrypted value revealed through `facts:reveal`. type: boolean scope: additionalProperties: type: string description: Scope keys the reference type declares, each with its value. type: object sensitivity: description: >- Protection class of the reference; omitted for `none`, whose value is always clear. Allowed values: `masked`, `hashed`, `encrypted`. enum: - masked - hashed - encrypted type: string type: description: Registered reference type, dotted and lower-case. type: string value: description: >- Reference value, case-preserving and never trimmed. A protected reference shows its protected form; an encrypted one is clear only for a `facts:reveal` holder. type: string required: - type - value - scope type: object SubjectBody: additionalProperties: false properties: id: description: >- Identifier of the subject in the producer's system, assigned by the producer. type: string type: description: Subject type, dotted and lower-case, as the contract declares it. type: string required: - type - id 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.