Skip to content

List and filter stored facts

GET /v1/facts

OpenAPI protocol version: 1.0.0.

Source operation metadata · Source value schemas

List stored facts, including policy-declared facts, rather than derived query answers. Query parameters must be unique and recognized. terms is a JSON-encoded array. A textual query cannot be combined with predicate or terms. Follow nextCursor with the same filters; omit it for the first page. Pagination is not a snapshot across mutations.

Paths are relative to your instance URL. JSON request bodies require Content-Type: application/json.

Request parameters

Section titled “Request parameters”
NameLocationRequiredDescription
predicatequeryNoMatch this predicate name. Omit to list all predicates.
termsqueryNoJSON array of ordered term filters. Null or an empty wildcard matches any value; a wildcard type restricts matching values.
queryqueryNoOne textual predicate filter. Cannot be combined with predicate or terms.
limitqueryNoMaximum page size. Omitted or zero selects 100; values above 1000 are capped at 1000.
cursorqueryNoOpaque nextCursor from the preceding page with the same filters.

predicate schema

Section titled “predicate schema”
string
View JSON Schema
{
  "type": "string"
}

terms schema

Section titled “terms schema”
array
Maximum items: 3
Array items
union

Null and an empty wildcard match any value. A wildcard type restricts matches; repeated wildcard names require typed equality.

A value must match one or more of these shapes.

A concrete value in a fact or query. Use a number for safe integers or an int64 object with a decimal string for signed 64-bit integers.

A value must match one or more of these shapes.

string
View JSON Schema
{
  "type": "array",
  "items": {
    "anyOf": [
      {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "JSON integer within -9007199254740991 to 9007199254740991. Larger magnitudes require an int64 object."
          },
          {
            "type": "boolean"
          },
          {
            "type": "object",
            "required": [
              "type",
              "id"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "Entity type used by the policy."
              },
              "id": {
                "type": "string",
                "description": "Entity identifier within its type."
              }
            },
            "title": "Identity",
            "additionalProperties": false,
            "description": "An entity identity. Both type and id are strings."
          },
          {
            "type": "object",
            "required": [
              "type",
              "value"
            ],
            "properties": {
              "type": {
                "type": "string",
                "const": "int64",
                "description": "Identifies a signed 64-bit integer value."
              },
              "value": {
                "type": "string",
                "description": "Signed 64-bit integer as a canonical decimal string.",
                "pattern": "^(0|-[1-9][0-9]*|[1-9][0-9]*)$",
                "maxLength": 20
              }
            },
            "title": "Int64",
            "additionalProperties": false,
            "description": "Signed 64-bit integer encoded as a decimal string, from -9223372036854775808 to 9223372036854775807. The runtime rejects values outside this range. Responses use JSON numbers for safe integers and int64 objects otherwise."
          }
        ],
        "description": "A concrete value in a fact or query. Use a number for safe integers or an int64 object with a decimal string for signed 64-bit integers."
      },
      {
        "type": "null"
      },
      {
        "type": "object",
        "required": [
          "wildcard"
        ],
        "properties": {
          "wildcard": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Binding name. Repeated names require typed equality.",
                "pattern": "^[a-z][A-Za-z0-9_]*$"
              },
              "type": {
                "type": "string",
                "description": "Restricts matches to this value type.",
                "minLength": 1
              }
            },
            "additionalProperties": false
          }
        },
        "title": "Wildcard",
        "additionalProperties": false
      }
    ],
    "description": "Null and an empty wildcard match any value. A wildcard type restricts matches; repeated wildcard names require typed equality."
  },
  "maxItems": 3
}

query schema

Section titled “query schema”
string
Minimum length: 1 character
View JSON Schema
{
  "type": "string",
  "minLength": 1
}

limit schema

Section titled “limit schema”
integer
Minimum value: 0Maximum value: 4294967295
View JSON Schema
{
  "type": "integer",
  "minimum": 0,
  "maximum": 4294967295
}

cursor schema

Section titled “cursor schema”
string
View JSON Schema
{
  "type": "string"
}

Deployment request headers

Section titled “Deployment request headers”
HeaderBehavior
AuthorizationBearer API key for Cloud instances and Node servers configured with API keys. Node servers without API keys do not require this header.
Verdict-Read-ModeRead mode: local (default) or authoritative. Cloud selects the writer for authoritative reads. Replicated Node servers require the writer for authoritative reads. Standalone Node servers do not interpret this header.
Verdict-Min-RevisionOpaque observed revision token for a minimum-revision read. Use a token from the same instance. Supported by Cloud and replicated Node deployments; standalone Node servers do not interpret it.
Verdict-Session-IdCloud replica-selection affinity identifier, 1 to 128 ASCII letters, digits, underscores, or hyphens. This is not an authentication credential. Node servers do not interpret it.
Connect-Timeout-MsFor replicated Node reads, a positive numeric timeout in milliseconds caps the revision wait at 5000 ms; the default is 5000 ms. This is not a universal REST request deadline.

Responses

Section titled “Responses”

See common status codes and error bodies. Success responses and operation-specific exceptions are listed here.

StatusMeaning
200Successful response
409Closed runtime or deployment consistency conflict

Successful response header Verdict-Revision: Observed revision token on successful Cloud and replicated Node responses. Absent on standalone Node servers. Preserve the token unchanged for a minimum-revision read.

200 JSON body

Section titled “200 JSON body”
factsarrayrequired
Array items
object
Nested properties
predicatestringrequired
Minimum length: 1 character
termsarrayrequired
Minimum items: 1Maximum items: 3
Array items
union

A concrete value in a fact or query. Use a number for safe integers or an int64 object with a decimal string for signed 64-bit integers.

A value must match one or more of these shapes.

string
nextCursorstringoptional

Opaque continuation token. Absent when there is no further page. Reuse with the same filters.

View JSON Schema
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "facts"
  ],
  "properties": {
    "facts": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "predicate",
          "terms"
        ],
        "properties": {
          "predicate": {
            "type": "string",
            "minLength": 1
          },
          "terms": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991,
                  "description": "JSON integer within -9007199254740991 to 9007199254740991. Larger magnitudes require an int64 object."
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "object",
                  "required": [
                    "type",
                    "id"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "Entity type used by the policy."
                    },
                    "id": {
                      "type": "string",
                      "description": "Entity identifier within its type."
                    }
                  },
                  "title": "Identity",
                  "additionalProperties": false,
                  "description": "An entity identity. Both type and id are strings."
                },
                {
                  "type": "object",
                  "required": [
                    "type",
                    "value"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "int64",
                      "description": "Identifies a signed 64-bit integer value."
                    },
                    "value": {
                      "type": "string",
                      "description": "Signed 64-bit integer as a canonical decimal string.",
                      "pattern": "^(0|-[1-9][0-9]*|[1-9][0-9]*)$",
                      "maxLength": 20
                    }
                  },
                  "title": "Int64",
                  "additionalProperties": false,
                  "description": "Signed 64-bit integer encoded as a decimal string, from -9223372036854775808 to 9223372036854775807. The runtime rejects values outside this range. Responses use JSON numbers for safe integers and int64 objects otherwise."
                }
              ],
              "description": "A concrete value in a fact or query. Use a number for safe integers or an int64 object with a decimal string for signed 64-bit integers."
            },
            "minItems": 1,
            "maxItems": 3
          }
        },
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "type": "string",
      "description": "Opaque continuation token. Absent when there is no further page. Reuse with the same filters."
    }
  },
  "additionalProperties": false
}

Example response

Section titled “Example response”
{
  "facts": [
    {
      "predicate": "role",
      "terms": [
        {
          "type": "User",
          "id": "alice"
        },
        "reader"
      ]
    }
  ]
}

409 JSON body

Section titled “409 JSON body”
errorstringrequired
messagestringrequired
View JSON Schema
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": false
}