curl --request POST \
  --url https://api.example.com/v1/facts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  }
}
'

{
  "factId": "01a15493-ba10-7b21-9d44-3c1f8e2a9b01",
  "producer": "checkout-api",
  "flowAggregationId": "01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33",
  "duplicate": true,
  "ingestedAt": "2026-10-19T14:32:11Z"
}

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.

POST

facts

curl --request POST \
  --url https://api.example.com/v1/facts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  }
}
'

{
  "factId": "01a15493-ba10-7b21-9d44-3c1f8e2a9b01",
  "producer": "checkout-api",
  "flowAggregationId": "01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33",
  "duplicate": true,
  "ingestedAt": "2026-10-19T14:32:11Z"
}

Authorizations

Authorization

string

header

required

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.

Body

application/json

data

any

required

Payload validated against the contract's JSON Schema.

Example:

{
  "amount": "129.90",
  "currency": "BRL",
  "customerDocument": "12345678909"
}

envelopeVersion

integer<int64>

required

Envelope format version. Always 1.

Example:

1

factId

string

required

Identifier the producer assigns to this occurrence (UUID). Redelivering the same content with the same factId is an idempotent replay.

Example:

"01a15493-ba10-7b21-9d44-3c1f8e2a9b01"

namespace

string

required

Namespace the contract was registered under.

Example:

"acme.checkout"

occurredAt

string<date-time>

required

When the business event happened, as an RFC 3339 timestamp; it is stored and returned in UTC.

Example:

"2026-10-19T14:32:10Z"

producer

string

required

Producer that emits the fact, as declared in the contract.

Example:

"checkout-api"

schemaVersion

string

required

Contract version (semantic version) the payload follows. The version must be active.

Example:

"1.0.0"

subject

object

required

Business entity the fact is about.

Show child attributes

type

string

required

Fact type, as declared in the contract.

Example:

"checkout.order_placed"

references

object[] | null

Typed references that correlate this fact with facts of other producers into one flow. Omit it only when the contract declares no required reference.

Show child attributes

Response

Duplicate delivery: this producer and factId are already stored with the same content. Nothing changed; the body carries duplicate: true.

duplicate

boolean

required

True when this delivery repeated a stored fact with the same content: an idempotent replay that stored nothing new.

factId

string

required

Identifier the producer assigned to the fact.

flowAggregationId

string

required

Current id of the flow the fact belongs to, assigned by the server and opaque.

ingestedAt

string<date-time>

required

When System Facts first stored the fact; a replay returns the original time. RFC 3339, UTC.

producer

string

required

Producer that sent the fact.

Overview

Reference Types

Contracts

Facts

Flows

Error handling

Send a fact

Authorizations

Body

Response