Skip to main content
POST /v1/tenants/{tenant_id}/data/run-bundle The Run Bundle endpoint executes a named bundle that was previously defined with Write Bundle. You provide the bundle name and a map of argument values; Permify substitutes the template variables and atomically executes all the relationship and attribute write/delete operations defined in the bundle.
Bundles let you encapsulate complex data write patterns into named, reusable operations. Instead of making multiple individual write calls when an application event occurs (e.g. a user joins an organization), you define the bundle once and trigger it with a single Run Bundle call.

​
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

​
name
string
required
The name of the bundle to execute, as registered via Write Bundle.
​
arguments
map[string, string]
required
Key-value pairs that are substituted for template variables ({{variable}}) in the bundle’s operations. The keys must match the arguments list declared in the bundle definition.

​
Response

​
snap_token
string
A snap token representing the database state after all bundle operations were applied. Pass this token in subsequent read or check requests to ensure you see the newly written data. See Snap Tokens.

​
Example

Given a bundle named organization_created defined with arguments creatorID and organizationID, execute it when a new organization is created in your application: 
curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/data/run-bundle' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "organization_created",
    "arguments": {
        "creatorID": "564",
        "organizationID": "789"
    }
}'

​
Response

{
  "snap_token": "FxHhb4CrLBc="
}

​
Workflow

1

Define the bundle

Use Write Bundle to create a named bundle with template variables:
{
  "bundles": [{
    "name": "organization_created",
    "arguments": ["creatorID", "organizationID"],
    "operations": [{
      "relationships_write": [
        "organization:{{.organizationID}}#admin@user:{{.creatorID}}",
        "organization:{{.organizationID}}#member@user:{{.creatorID}}"
      ]
    }]
  }]
}
2

Trigger on application events

Call Run Bundle from your application whenever the corresponding event occurs — for example, in the event handler for organization.created:
{
  "name": "organization_created",
  "arguments": {
    "creatorID": "user-id-from-event",
    "organizationID": "org-id-from-event"
  }
}
3

Use the snap token

Pass the returned snap_token to subsequent permission checks to ensure the newly written data is visible:
{
  "metadata": { "snap_token": "FxHhb4CrLBc=" },
  "entity": { "type": "organization", "id": "789" },
  "permission": "delete",
  "subject": { "type": "user", "id": "564" }
}
See Bundles for a complete guide on defining and using bundles, including the full template variable syntax and supported operation types.

Build docs developers (and LLMs) love

Get started for freeTalk to us