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

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 consulta

referenceType

string

requerido

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

Required string length: 1 - 128

Ejemplo:

"acme.order_id"

referenceValue

string

requerido

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

Required string length: 1 - 512

Ejemplo:

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

predeterminado:50

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

Rango requerido: 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.

Opciones disponibles:

flow

Ejemplo:

"flow"

Respuesta

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

items

object[] | null

requerido

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

Show child attributes

limit

integer<int64>

requerido

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.

Resumen

Tipos de referencia

Contratos

Hechos

Flujos

Manejo de errores

List facts by a searchable reference

Autorizaciones

Parámetros de consulta

Respuesta