# Bun Protocol — API reference (authoritative operation list)

<!-- GENERATED FILE — do not edit by hand. Source: scripts/generate_agent_docs.py -->

> This page is the **only** authoritative list of what Bun Protocol serves.
> An operation absent from this page does not exist. Every operation is
> `stability: BETA` — none is stable or GA.
>
> Generated from the in-memory operation registry
> (`app.protocol.registry.list_operations`) via `pkgutil` discovery over
> `app.protocol.operations`. Run `python scripts/generate_agent_docs.py` to refresh;
> `--check` fails if this file no longer matches the registry, so it cannot
> drift the way `sdk/llms.txt` did at 19 of 55.

## How to call one

Every operation is dispatched by `operation_id` through the protocol endpoint;
the descriptor for each carries its own `input_schema` and `output_schema`,
`idempotency` policy, `timeout`, `availability` and `provider_effects`. Read the
descriptor rather than assuming a shape. Fetch the served descriptors from a
running server's OpenAPI document — its `info.title` must read **"Bun Protocol"**.
Bun runs on port **8001** in the local sandbox; port 8000 on this machine belongs
to an unrelated application.

Operations that declare `availability: fail_closed` return `denied` when
authorisation, tenant derivation or entitlement cannot be established. That is
the correct behaviour, not an error to work around.

## Columns

- **auth** — `requires_auth`. `no` does not mean unauthenticated callers get
  privileged data; it means the operation establishes or checks its own subject.
- **tenant** — `requires_tenant`. `yes` means tenant context must be derivable, and
  the underlying tables are protected by FORCE row-level security in PostgreSQL.
- **permissions** — `required_permissions` from the descriptor.
- **metering unit / billable** — see `metering-costs.md`.

## Operations


**55 operations across 16 families.** Counts are rendered from the registry, not typed.


### bun.audit

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.audit.query` | yes | yes | audit:read | `operation` | no |
| `bun.audit.record` | no | no | none | `operation` | no |


### bun.context

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.context.describe` | yes | yes | context:read | `operation` | no |
| `bun.context.missing` | yes | yes | context:read | `operation` | no |
| `bun.context.operations` | yes | yes | context:read | `operation` | no |
| `bun.context.stack` | yes | yes | context:read | `operation` | no |


### bun.credential

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.credential.describe` | yes | no | none | `operation` | no |
| `bun.credential.issue` | yes | no | none | `operation` | no |
| `bun.credential.revoke` | yes | no | none | `operation` | no |
| `bun.credential.rotate` | no | no | none | `operation` | no |
| `bun.credential.validate` | no | no | none | `operation` | no |


### bun.data

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.data.bulk` | yes | yes | data:write | `data_write` | yes |
| `bun.data.create` | yes | yes | data:write | `data_write` | yes |
| `bun.data.delete` | yes | yes | data:write | `data_write` | no |
| `bun.data.get` | yes | yes | data:read | `data_read` | yes |
| `bun.data.list` | yes | yes | data:read | `data_read` | yes |
| `bun.data.query` | yes | yes | data:read | `data_read` | yes |
| `bun.data.read` | yes | yes | data:read | `data_read` | yes |
| `bun.data.update` | yes | yes | data:write | `data_write` | yes |


### bun.deploy

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.deploy.apply` | yes | no | deploy:write | `deploy_apply` | yes |
| `bun.deploy.describe` | yes | no | deploy:read | `operation` | no |
| `bun.deploy.plan` | yes | no | deploy:write | `deploy_plan` | yes |
| `bun.deploy.rollback` | yes | no | deploy:write | `deploy_rollback` | yes |
| `bun.deploy.status` | yes | no | deploy:read | `operation` | no |


### bun.file

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.file.access` | yes | yes | file:read | `file_access` | yes |
| `bun.file.delete` | yes | yes | file:write | `file_delete` | no |
| `bun.file.sign` | yes | yes | file:read | `operation` | no |
| `bun.file.upload` | yes | yes | file:write | `file_upload` | yes |


### bun.identity

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.identity.current` | no | no | none | `operation` | no |
| `bun.identity.login` | no | no | none | `operation` | no |
| `bun.identity.register` | no | no | none | `operation` | no |


### bun.membership

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.membership.accept` | yes | no | none | `operation` | no |
| `bun.membership.invite` | yes | yes | membership:invite | `operation` | no |
| `bun.membership.revoke` | yes | yes | membership:revoke | `operation` | no |


### bun.message

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.message.redact` | yes | yes | message:send | `operation` | no |
| `bun.message.send` | yes | yes | message:send | `message_send` | yes |
| `bun.message.status` | yes | yes | message:send | `operation` | no |


### bun.permission

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.permission.check` | yes | no | none | `operation` | no |


### bun.provider

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.provider.connect` | yes | yes | provider:connect | `operation` | no |
| `bun.provider.disconnect` | yes | yes | provider:disconnect | `operation` | no |
| `bun.provider.health` | yes | no | none | `operation` | no |
| `bun.provider.list_categories` | yes | no | none | `operation` | no |
| `bun.provider.list_providers` | yes | no | none | `operation` | no |
| `bun.provider.switch` | yes | yes | provider:connect | `operation` | no |


### bun.session

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.session.revoke` | yes | no | none | `operation` | no |
| `bun.session.validate` | no | no | none | `operation` | no |


### bun.subscription

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.subscription.require_active` | yes | no | none | `operation` | no |


### bun.system

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.system.describe_context` | no | no | none | `operation` | no |
| `bun.system.ping` | no | no | none | `operation` | no |


### bun.tenant

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.tenant.create` | yes | no | none | `operation` | no |
| `bun.tenant.current` | yes | no | none | `operation` | no |


### bun.webhook

| operation | auth | tenant | permissions | metering unit | billable |
|---|---|---|---|---|---|
| `bun.webhook.deduplicate` | no | no | none | `operation` | no |
| `bun.webhook.order_check` | no | no | none | `operation` | no |
| `bun.webhook.receive` | no | no | none | `operation` | no |
| `bun.webhook.verify` | no | no | none | `operation` | no |