Evaluate a predicate

OpenAPI protocol version: 1.0.0.

Source operation metadata · Source value schemas

Evaluate stored or derived answers for the predicate pattern. Result columns correspond to wildcard positions in request order, including repeated names. A matching fully bound query returns [[]]; a query with no answers returns []. Requires a loaded policy.

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

Deployment request headers

Header	Behavior
Authorization	Bearer API key for Cloud instances and Node servers configured with API keys. Node servers without API keys do not require this header.
Verdict-Read-Mode	Read 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-Revision	Opaque 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-Id	Cloud 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-Ms	For 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.

Request body

Example body

{
  "predicate": "role",
  "terms": [
    {
      "type": "User",
      "id": "alice"
    },
    null
  ]
}

Fields

predicatestringrequired

Minimum length: 1 character

termsarrayrequired

Minimum items: 1Maximum 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.

Option 1Option 2Wildcard

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.

Option 1Option 2Option 3IdentityInt64

string

integer

JSON integer within -9007199254740991 to 9007199254740991. Larger magnitudes require an int64 object.

Minimum value: -9007199254740991Maximum value: 9007199254740991

boolean

An entity identity. Both type and id are strings.

typestringrequired

Entity type used by the policy.

idstringrequired

Entity identifier within its type.

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.

type"int64"required

Identifies a signed 64-bit integer value.

valuestringrequired

Signed 64-bit integer as a canonical decimal string.

Maximum length: 20 charactersPattern: "^(0|-[1-9][0-9]*|[1-9][0-9]*)$"

null

wildcardobjectrequired

Nested properties

namestringoptional

Binding name. Repeated names require typed equality.

Pattern: "^[a-z][A-Za-z0-9_]*$"

typestringoptional

Restricts matches to this value type.

Minimum length: 1 character

View JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "predicate",
    "terms"
  ],
  "properties": {
    "predicate": {
      "type": "string",
      "minLength": 1
    },
    "terms": {
      "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."
      },
      "minItems": 1,
      "maxItems": 3
    }
  },
  "additionalProperties": false
}

Responses

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

Status	Meaning
200	Successful response

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

resultsarrayrequired

Each row contains values bound to wildcard positions in request order. A successful fully bound query has one empty row.

Array items

array

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.

Option 1Option 2Option 3IdentityInt64

string

integer

JSON integer within -9007199254740991 to 9007199254740991. Larger magnitudes require an int64 object.

Minimum value: -9007199254740991Maximum value: 9007199254740991

boolean

An entity identity. Both type and id are strings.

typestringrequired

Entity type used by the policy.

idstringrequired

Entity identifier within its type.

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.

type"int64"required

Identifies a signed 64-bit integer value.

valuestringrequired

Signed 64-bit integer as a canonical decimal string.

Maximum length: 20 charactersPattern: "^(0|-[1-9][0-9]*|[1-9][0-9]*)$"

View JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "results"
  ],
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "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."
        }
      },
      "description": "Each row contains values bound to wildcard positions in request order. A successful fully bound query has one empty row."
    }
  },
  "additionalProperties": false
}

Example response

{
  "results": [
    [
      "reader"
    ]
  ]
}