Insert a fact

OpenAPI protocol version: 1.0.0.

Source operation metadata · Source value schemas

Insert one stored fact. Inserting an existing fact succeeds without adding a duplicate. The response has no body.

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

Request parameters

Name	Location	Required	Description
Idempotency-Key	header	No	Optional 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

string

Minimum length: 1 characterMaximum length: 128 characters

View JSON Schema

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128
}

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

Request body

Example body

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

Fields

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.

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

Responses

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

Status	Meaning
204	Mutation applied; no response body

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.