Find the flow of a reference

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

package main

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

func main() {

	url := "https://api.example.com/v1/flows/by-reference"

	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/by-reference', 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",
  "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
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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

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

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

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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.

GET

flows

by-reference

Find the flow of a reference

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

package main

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

func main() {

	url := "https://api.example.com/v1/flows/by-reference"

	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/by-reference', 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",
  "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
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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

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

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

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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.

Query Parameters

referenceType

string

required

Registered reference type to look up, dotted and lower-case.

Required string length: 1 - 128

Example:

"acme.order_id"

referenceValue

string

required

Reference value to look up: always the clear value, also for a protected type.

Required string length: 1 - 512

Example:

"ORD-2026-000123"

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 of the reference and one page of its facts; it never carries 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

Find the flow of a reference

Authorizations

Query Parameters

Response