Read a flow

curl --request GET \
  --url https://api.example.com/v1/flows/{flowAggregationId} \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/flows/{flowAggregationId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/flows/{flowAggregationId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "flowAggregationId": "01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33",
  "createdAt": "2026-10-19T14:32:11Z",
  "updatedAt": "2026-10-19T14:32:11Z",
  "merge": {
    "absorbedId": "01a15496-5dd8-7d66-a1f3-7a5b2e8f0d44",
    "mergedAt": "2026-10-19T14:40:01Z",
    "mergedBy": {
      "producer": "payments-api",
      "factId": "01a1549a-e600-7d43-9f66-5e3b0a4c1d23"
    }
  },
  "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
  }
}

Read a flow

Reads one flow, by an id you stored or received, and pages through its facts.

Rules

The id may be the flow’s own or one a merge absorbed; flowAggregationId in the response is always the current flow: replace any stored id with it.
For an absorbed id, merge carries absorbedId (the requested id), mergedAt and mergedBy (the bridging fact’s producer and factId), naming the first one that absorbed the requested id; a current id carries no merge.
When a fact bridges flows, the flow with more facts survives, ties go to the oldest, and every other id keeps resolving here.
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-0009 no flow, current or absorbed, has this id.
422 SF-0092 not a UUID; SF-0006 a malformed cursor.
503 SF-0094 retry later.

GET

flows

{flowAggregationId}

Read a flow

curl --request GET \
  --url https://api.example.com/v1/flows/{flowAggregationId} \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/flows/{flowAggregationId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/flows/{flowAggregationId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "flowAggregationId": "01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33",
  "createdAt": "2026-10-19T14:32:11Z",
  "updatedAt": "2026-10-19T14:32:11Z",
  "merge": {
    "absorbedId": "01a15496-5dd8-7d66-a1f3-7a5b2e8f0d44",
    "mergedAt": "2026-10-19T14:40:01Z",
    "mergedBy": {
      "producer": "payments-api",
      "factId": "01a1549a-e600-7d43-9f66-5e3b0a4c1d23"
    }
  },
  "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
  }
}

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.

Path Parameters

flowAggregationId

string<uuid>

required

Id of the flow: its current id, or one a merge absorbed (the answer then carries the merge object).

Example:

"01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33"

Query Parameters

factsLimit

integer<int64>

default:100

Facts per page, from 1 to 500. Default 100.

Required range: 1 <= x <= 500

factsCursor

string

Opaque nextCursor of the previous page; omit it to read the first page.

Maximum string length: 1024

Response

The current flow and one page of its facts. merge is present only when the requested id was absorbed by a merge.

createdAt

string<date-time>

required

When the flow was first created. RFC 3339, UTC.

facts

object

required

One page of the flow's facts.

Show child attributes

flowAggregationId

string

required

Current id of the flow, assigned by the server and opaque. Store it in place of any absorbed id.

updatedAt

string<date-time>

required

When the flow record itself last changed; adding facts or merges does not change it, so today it equals createdAt. RFC 3339, UTC.

merge

object

Present only when the requested id was absorbed by a merge; replace any stored id with flowAggregationId.

Show child attributes

Overview

Reference Types

Contracts

Facts

Flows

Error handling

Read a flow

Authorizations

Path Parameters

Query Parameters

Response