List facts by a searchable reference

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

package main

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

func main() {

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

	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', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "flowAggregationId": "01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33",
      "fact": {
        "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"
      },
      "flow": {
        "createdAt": "2026-10-19T14:32:11Z",
        "updatedAt": "2026-10-19T14:32:11Z"
      }
    },
    {
      "flowAggregationId": "01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33",
      "fact": {
        "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"
      },
      "flow": {
        "createdAt": "2026-10-19T14:32:11Z",
        "updatedAt": "2026-10-19T14:32:11Z"
      }
    }
  ],
  "limit": 50
}

{
  "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-0024",
  "detail": "List flows only by a reference type registered with searchable: true, or read the one flow of an exact reference with findFlowByReference.",
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "https://errors.lerian.studio/v1/SF-0024"
}

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

List facts by a searchable reference

Lists every fact that carries a searchable reference, each with the flow it belongs to now.

Rules

Only types registered with searchable: true (see getReferenceType).
referenceValue is always the clear value, also for a protected type. Every other query parameter except occurredFrom, occurredTo, limit, cursor and include is a scope key, matched by containment as in findFlowByReference.
occurredFrom (inclusive) and occurredTo (exclusive) are optional RFC 3339 bounds on the fact’s occurredAt; occurredFrom must be before occurredTo.
One item per matched fact, ordered by occurredAt, ties in a stable order; flowAggregationId is its current flow, so a later merge shows at read time. include=flow adds each flow’s createdAt and updatedAt.
Paged: pass nextCursor as cursor; it is omitted on the last page. limit is 1 to 100 (default 50).
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 one page; an empty page when nothing matches, never 404 or 409.
422 SF-0024 not searchable; SF-0006 an empty period, a malformed reference or cursor; SF-0092 a schema mismatch.
503 SF-0094 retry later.

GET

flows

List facts by a searchable reference

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

package main

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

func main() {

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

	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', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "flowAggregationId": "01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33",
      "fact": {
        "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"
      },
      "flow": {
        "createdAt": "2026-10-19T14:32:11Z",
        "updatedAt": "2026-10-19T14:32:11Z"
      }
    },
    {
      "flowAggregationId": "01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33",
      "fact": {
        "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"
      },
      "flow": {
        "createdAt": "2026-10-19T14:32:11Z",
        "updatedAt": "2026-10-19T14:32:11Z"
      }
    }
  ],
  "limit": 50
}

{
  "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-0024",
  "detail": "List flows only by a reference type registered with searchable: true, or read the one flow of an exact reference with findFlowByReference.",
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "https://errors.lerian.studio/v1/SF-0024"
}

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

Reference type to list by, dotted and lower-case; it must be registered as searchable.

Required string length: 1 - 128

Example:

"acme.order_id"

referenceValue

string

required

Reference value to list by: always the clear value, also for a protected type.

Required string length: 1 - 512

Example:

"ORD-2026-000123"

occurredFrom

string<date-time>

Inclusive lower bound on the fact's occurredAt, as an RFC 3339 timestamp.

occurredTo

string<date-time>

Exclusive upper bound on the fact's occurredAt, as an RFC 3339 timestamp; it must be after occurredFrom.

limit

integer<int64>

default:50

Items per page, from 1 to 100. Default 50.

Required range: 1 <= x <= 100

cursor

string

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

Maximum string length: 1024

include

enum<string>

Set it to flow to add each item's flow summary (createdAt, updatedAt). Allowed values: flow.

Available options:

flow

Example:

"flow"

Response

One page of matched facts, each with its current flow, empty when nothing matches; nextCursor is omitted on the last page.

items

object[] | null

required

One item per matched fact, ordered by occurredAt, ties in a stable server order.

Show child attributes

limit

integer<int64>

required

Page size applied, after the default and the maximum.

nextCursor

string

Opaque cursor of the next page: send it back as cursor. Omitted on the last page.

Overview

Reference Types

Contracts

Facts

Flows

Error handling

List facts by a searchable reference

Authorizations

Query Parameters

Response