Skip to main content
POST /v1/tenants/{tenant_id}/data/write The Write Data endpoint stores relationship tuples and/or attributes in Permify’s authorization data store. These records form the graph that the permission engine traverses when evaluating access checks. You can write tuples (e.g. organization:1#admin@user:3), attributes (e.g. document:1$is_private|boolean:true), or both in a single request. The response includes a snap_token representing the state of the database after the write. Pass this token in subsequent read or check requests to guarantee you read your own writes.
Use this endpoint for both relationship data and attribute data. Both tuples and attributes arrays are optional; include whichever you need.

​
Path Parameters

​
tenant_id
string
required
The tenant identifier. Use t1 for single-tenant deployments. Must match ^([a-zA-Z0-9_\-@\.:+]{1,128}|\*)$.

​
Request Body

​
metadata
object
required
​
tuples
array
Relationship tuples to write.
​
attributes
array
Attribute data to write.

​
Response

​
snap_token
string
A token representing the database state after the write. Pass this to subsequent check or read requests via metadata.snap_token to ensure consistency.

​
Examples

​
Write a relationship tuple

curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/data/write' \
--header 'Content-Type: application/json' \
--data-raw '{
    "metadata": {
        "schema_version": ""
    },
    "tuples": [
        {
            "entity": {
                "type": "organization",
                "id": "1"
            },
            "relation": "admin",
            "subject": {
                "type": "user",
                "id": "3",
                "relation": ""
            }
        }
    ]
}'
Request body 
{
  "metadata": { "schema_version": "" },
  "tuples": [
    {
      "entity": { "type": "organization", "id": "1" },
      "relation": "admin",
      "subject": { "type": "user", "id": "3", "relation": "" }
    }
  ]
}
Response 
{
  "snap_token": "FxHhb4CrLBc="
}

​
Write a tuple and an attribute together

{
  "metadata": { "schema_version": "" },
  "tuples": [
    {
      "entity": { "type": "document", "id": "1" },
      "relation": "editor",
      "subject": { "type": "user", "id": "1" }
    }
  ],
  "attributes": [
    {
      "entity": { "type": "document", "id": "1" },
      "attribute": "is_private",
      "value": {
        "@type": "type.googleapis.com/base.v1.BooleanValue",
        "data": true
      }
    }
  ]
}

​
Error Codes

HTTP StatusDescription
400Bad request — invalid entity types, relation names, or attribute values
401Unauthorized
404Tenant not found
429Rate limit exceeded
500Internal server error

Build docs developers (and LLMs) love

Get started for freeTalk to us