> ## 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. # Send a fact > Sends one fact, validated against its contract version, stored and attached to a flow atomically; answered once durably stored. **Rules** - Validation covers the envelope, then `data` and references. A reference carries exactly the scope keys its type declares, non-empty, never trimmed. - Idempotent by `producer` and `factId`: resending the same content answers `200`, `duplicate: true`. Facts are immutable: a change needs a new `factId`. - At most 256 KiB per envelope by default and five `exact` references. - Strict envelope: a duplicate, or a member the envelope, its subject or a reference does not declare (exact, case-sensitive), is refused; `data` follows the contract's schema. The tenant comes from the token. - Only the producer service the namespace is bound to may send facts under it; refusals are recorded for audit. In multi-tenant mode that is the producer's service credential for the tenant. - If an operator disabled fact emission for this tenant, keep the fact pending and retry. - `x-sensitivity` fields are stored protected, never echoed in errors. A reference whose type has `mask: document` must have 11 or 14 digits. **Responses** - `201` stored; `200` duplicate. - `403` `SF-0005`, `SF-0014`, `SF-0020`, `SF-0027`, `SF-0028`. - `409` `SF-0016`; `413` `SF-0012`. - `422` `SF-0001`, `SF-0006`, `SF-0007`, `SF-0008`, `SF-0019`, `SF-0026`. - `503` `SF-0094` correlation contention, with `Retry-After: 1`: resend the same envelope. ## OpenAPI ````yaml /pt/openapi/v3-current/system-facts.yaml post /v1/facts 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/facts: post: tags: - Facts summary: Send a fact description: >- Sends one fact, validated against its contract version, stored and attached to a flow atomically; answered once durably stored. **Rules** - Validation covers the envelope, then `data` and references. A reference carries exactly the scope keys its type declares, non-empty, never trimmed. - Idempotent by `producer` and `factId`: resending the same content answers `200`, `duplicate: true`. Facts are immutable: a change needs a new `factId`. - At most 256 KiB per envelope by default and five `exact` references. - Strict envelope: a duplicate, or a member the envelope, its subject or a reference does not declare (exact, case-sensitive), is refused; `data` follows the contract's schema. The tenant comes from the token. - Only the producer service the namespace is bound to may send facts under it; refusals are recorded for audit. In multi-tenant mode that is the producer's service credential for the tenant. - If an operator disabled fact emission for this tenant, keep the fact pending and retry. - `x-sensitivity` fields are stored protected, never echoed in errors. A reference whose type has `mask: document` must have 11 or 14 digits. **Responses** - `201` stored; `200` duplicate. - `403` `SF-0005`, `SF-0014`, `SF-0020`, `SF-0027`, `SF-0028`. - `409` `SF-0016`; `413` `SF-0012`. - `422` `SF-0001`, `SF-0006`, `SF-0007`, `SF-0008`, `SF-0019`, `SF-0026`. - `503` `SF-0094` correlation contention, with `Retry-After: 1`: resend the same envelope. operationId: ingestFact requestBody: content: application/json: examples: orderPlaced: summary: >- checkout-api reports order ORD-2026-000123 with the customer document value: envelopeVersion: 1 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: '12345678909' scope: {} data: amount: '129.90' currency: BRL customerDocument: '12345678909' paymentConfirmed: summary: >- payments-api confirms payment PAY-7f3a2c91, carrying only the payment id value: envelopeVersion: 1 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 paymentSettled: summary: >- The settlement carries the payment id and the order id, bridging the two flows value: envelopeVersion: 1 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 schema: $ref: '#/components/schemas/FactEnvelope' required: true responses: '200': content: application/json: examples: duplicateDelivery: summary: The same order envelope delivered again stores nothing new value: factId: 01a15493-ba10-7b21-9d44-3c1f8e2a9b01 producer: checkout-api flowAggregationId: 01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33 duplicate: true ingestedAt: '2026-10-19T14:32:11Z' schema: $ref: '#/components/schemas/FactIngestResultBody' description: >- Duplicate delivery: this `producer` and `factId` are already stored with the same content. Nothing changed; the body carries `duplicate: true`. '201': content: application/json: examples: stored: summary: The order is stored and opens its flow value: factId: 01a15493-ba10-7b21-9d44-3c1f8e2a9b01 producer: checkout-api flowAggregationId: 01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33 duplicate: false ingestedAt: '2026-10-19T14:32:11Z' schema: $ref: '#/components/schemas/FactIngestResultBody' description: The fact, its references and its flow assignment are durably stored. '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- `SF-0013` The request carries no valid bearer token, or no service identity to send facts as. '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- `SF-0005` The namespace is bound to another producer service; this is decided first, and the refusal is recorded for audit. `SF-0014` The token lacks `facts:read` or `facts:write`. `SF-0020` An operator has disabled fact emission for this tenant (recorded for audit): nothing is stored and the contracts stay registered; keep the fact pending and retry. `SF-0027` In multi-tenant mode, the credential is not the producer's service credential for the tenant. `SF-0028` That credential was created without naming its producer service. '409': content: application/problem+json: examples: contentConflict: summary: The order's factId sent again with a different amount value: code: SF-0016 detail: >- Facts are immutable: send a changed occurrence as a new fact with a new factId, and check the producer that reused the identifier. instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 409 title: Conflict type: https://errors.lerian.studio/v1/SF-0016 schema: $ref: '#/components/schemas/Detail' description: >- `SF-0016` This `producer` and `factId` are stored with different content. Facts are immutable: do not retry; send a changed occurrence under a new `factId`. '413': content: application/problem+json: examples: tooLarge: summary: An envelope above the size limit value: code: SF-0012 detail: >- Reduce the request body; for a fact, send a statement about an occurrence, not a document. instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 413 title: Request Entity Too Large type: https://errors.lerian.studio/v1/SF-0012 schema: $ref: '#/components/schemas/Detail' description: >- `SF-0012` The envelope exceeds the size limit (256 KiB unless the deployment sets another). Nothing is stored. '422': content: application/problem+json: examples: deprecatedVersion: description: >- Sent: a paymentConfirmed envelope with `occurredAt` 2026-10-19T16:10:00Z under `schemaVersion` 1.0.0, which payments-api deprecated at 2026-10-19T16:00:00Z, after the flow story; 1.1.0 is the active version. summary: >- A payment confirmation sent under 1.0.0 after payments-api deprecated it value: code: SF-0019 detail: >- Send the fact against an active version of the same fact type. instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 422 title: Unprocessable Entity type: https://errors.lerian.studio/v1/SF-0019 payloadViolation: description: >- The schema wants both as strings; the entry of the protected `customerDocument` never echoes the value. summary: The order's amount and customer document sent as numbers value: code: SF-0007 detail: >- Fix the payload fields listed in errors[] so they match the contract. errors: - location: body.data/amount message: got number, want string - location: body.data/customerDocument message: >- value of a protected field violates its schema (value redacted) instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 422 title: Unprocessable Entity type: https://errors.lerian.studio/v1/SF-0007 undeclaredReference: summary: >- The payment confirmation sent with the order id its contract does not declare value: code: SF-0008 detail: >- Send only the references and scope keys that the contract and its reference types declare. errors: - location: body.references[1].type message: >- reference type "acme.order_id" is not declared by the contract instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 422 title: Unprocessable Entity type: https://errors.lerian.studio/v1/SF-0008 schema: $ref: '#/components/schemas/Detail' description: >- `SF-0001` No contract version is registered for this producer, namespace, type and schema version, including a namespace no producer has claimed yet. `SF-0006` The body is not a valid envelope, or has a duplicated member or one the envelope, its subject or a reference does not declare (matched exactly, case-sensitively; `data` answers `SF-0007`): one `errors[]` entry per member, at most 50 listed, then one entry counting the rest; a member naming a tenant is also recorded for audit. `SF-0007` `data` does not satisfy the contract's schema, including a value that does not match its `x-mask` format; a protected value is redacted. `SF-0008` A reference is not declared by the contract; a scope key is missing, empty or undeclared (at `body.references[i].scope.`); the fact has more than five `exact` references; or a `mask: document` reference does not have 11 or 14 digits (at its `value`, redacted). `SF-0019` The contract version is deprecated: send under an active version. `SF-0026` The stored schema of this contract version has malformed `x-sensitivity` or `x-mask` annotations, so nothing is stored: register a corrected version. '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: examples: correlationBusy: description: >- The response carries `Retry-After: 1`: wait one second and resend the same envelope. Nothing was stored. summary: >- The order id stayed busy with concurrent writes; answered with Retry-After: 1 value: code: SF-0094 detail: >- Retry later with the same request, honoring Retry-After when the response carries it. instance: 0199c1f07a3e7b219d443c1f8e2a9b01 status: 503 title: Service Unavailable type: https://errors.lerian.studio/v1/SF-0094 schema: $ref: '#/components/schemas/Detail' description: >- `SF-0094` With `Retry-After`: the fact's correlation keys stayed busy with concurrent writes for the whole ingest budget (4 seconds), so nothing is stored; wait and resend the same envelope. Without the header: the service is starting, or the authorization service is temporarily unavailable: retry later. headers: Retry-After: description: >- Seconds to wait before resending the same envelope (correlation contention); absent when the service is starting or unavailable schema: type: integer security: - BearerAuth: [] components: schemas: FactEnvelope: additionalProperties: false properties: data: description: Payload validated against the contract's JSON Schema. examples: - amount: '129.90' currency: BRL customerDocument: '12345678909' envelopeVersion: description: Envelope format version. Always 1. examples: - 1 format: int64 type: integer factId: description: >- Identifier the producer assigns to this occurrence (UUID). Redelivering the same content with the same factId is an idempotent replay. examples: - 01a15493-ba10-7b21-9d44-3c1f8e2a9b01 type: string namespace: description: Namespace the contract was registered under. examples: - acme.checkout type: string occurredAt: description: >- When the business event happened, as an RFC 3339 timestamp; it is stored and returned in UTC. examples: - '2026-10-19T14:32:10Z' format: date-time type: string producer: description: Producer that emits the fact, as declared in the contract. examples: - checkout-api type: string references: description: >- Typed references that correlate this fact with facts of other producers into one flow. Omit it only when the contract declares no required reference. items: $ref: '#/components/schemas/FactEnvelopeReferenceBody' type: - array - 'null' schemaVersion: description: >- Contract version (semantic version) the payload follows. The version must be active. examples: - 1.0.0 type: string subject: $ref: '#/components/schemas/FactEnvelopeSubjectBody' description: Business entity the fact is about. type: description: Fact type, as declared in the contract. examples: - checkout.order_placed type: string required: - envelopeVersion - factId - producer - namespace - type - schemaVersion - occurredAt - subject - data type: object FactIngestResultBody: additionalProperties: false properties: duplicate: description: >- True when this delivery repeated a stored fact with the same content: an idempotent replay that stored nothing new. type: boolean factId: description: Identifier the producer assigned to the fact. type: string flowAggregationId: description: >- Current id of the flow the fact belongs to, assigned by the server and opaque. type: string ingestedAt: description: >- When System Facts first stored the fact; a replay returns the original time. RFC 3339, UTC. format: date-time type: string producer: description: Producer that sent the fact. type: string required: - factId - producer - flowAggregationId - duplicate - ingestedAt 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 FactEnvelopeReferenceBody: additionalProperties: false properties: scope: additionalProperties: type: string description: >- Scope keys the reference type declares, each with a non-empty value. Omit it when the type declares none. examples: - storeId: store-sp-01 type: object type: description: Registered reference type. examples: - acme.order_id type: string value: description: Reference value. Values are opaque and never trimmed. examples: - ORD-2026-000123 type: string required: - type - value type: object FactEnvelopeSubjectBody: additionalProperties: false properties: id: description: Identifier of the subject in the producer's system. examples: - ORD-2026-000123 type: string type: description: Subject type, as declared in the contract. examples: - checkout.order type: string required: - type - id 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.