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
  }
}

Autorizaciones

Authorization

string

header

requerido

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.

Parámetros de ruta

flowAggregationId

string<uuid>

requerido

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

Ejemplo:

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

Parámetros de consulta

factsLimit

integer<int64>

predeterminado:100

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

Rango requerido: 1 <= x <= 500

factsCursor

string

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

Maximum string length: 1024

Respuesta

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>

requerido

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

facts

object

requerido

One page of the flow's facts.

Show child attributes

flowAggregationId

string

requerido

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

updatedAt

string<date-time>

requerido

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

Resumen

Tipos de referencia

Contratos

Hechos

Flujos

Manejo de errores

Read a flow

Autorizaciones

Parámetros de ruta

Parámetros de consulta

Respuesta