Skip to content

Apply a fact batch

POST /v1/facts/batch

OpenAPI protocol version: 1.0.0.

Source operation metadata · Source value schemas

Apply deletes and inserts as one atomic fact batch. Deletes run before inserts. Missing arrays are empty. Counts report stored rows actually inserted or deleted; inserting an existing fact does not add a duplicate.

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

Request parameters

Section titled “Request parameters”
NameLocationRequiredDescription
Idempotency-KeyheaderNoOptional key for one logical mutation. Repeat the same key and payload to replay its retained result; a different payload conflicts. Receipts are retained for 60 seconds. Policy and fact mutations use separate key scopes. Do not assume a retry after retention expires is deduplicated.

Idempotency-Key schema

Section titled “Idempotency-Key schema”
string
Minimum length: 1 characterMaximum length: 128 characters
View JSON Schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128
}

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

Request body

Section titled “Request body”

Example body

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

Fields

Section titled “Fields”
insertsarrayoptional
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
deletesarrayoptional
Array items
object
Nested properties
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.

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
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "inserts": {
      "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
      }
    },
    "deletes": {
      "type": "array",
      "items": {
        "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
      }
    }
  },
  "additionalProperties": false
}

Responses

Section titled “Responses”

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

StatusMeaning
200Successful 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

Section titled “200 JSON body”
insertedintegerrequired

Number of new stored rows inserted; existing rows do not count.

Minimum value: 0
deletedintegerrequired

Number of stored rows deleted before inserts are applied.

Minimum value: 0
View JSON Schema
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "inserted",
    "deleted"
  ],
  "properties": {
    "inserted": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of new stored rows inserted; existing rows do not count."
    },
    "deleted": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of stored rows deleted before inserts are applied."
    }
  },
  "additionalProperties": false
}

Example response

Section titled “Example response”
{
  "inserted": 1,
  "deleted": 0
}