The stored_file.* family (5 verbs). Every verb enters through the one front door: it is capability-checked, permission-checked, scope-checked and audited before it runs (see Security & permissions). Each entry below lists its capability, risk class (which fixes the minimum autonomy level), the minimum caller permission, its availability tier, whether it is idempotent, and any outbound egress.
Createstored_file.create
| Property | Value |
|---|---|
| Capability | stored_file.write |
| Risk class | Write - autonomy L1 |
| Min. permission | Member |
| Availability | On demand (MCP tier 2) |
| Idempotent | No |
| Egress | None - in-box (pure Postgres, no outbound call) |
Insert-only first-write at version=1; a unique-key collision NEVER overwrites - it returns {committed
, reason:‘concurrent_write’} (the no-CAS first-write race fix).{ key, filename, mimeType, fileSize, contentBase64?, checksum?, storageBackend?=DB, createdById? }.
Call POST /v/stored_file.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool stored_file.create.
Deletestored_file.delete
| Property | Value |
|---|---|
| Capability | stored_file.write |
| Risk class | Write - autonomy L1 |
| Min. permission | Member |
| Availability | On demand (MCP tier 2) |
| Idempotent | Yes |
| Egress | None - in-box (pure Postgres, no outbound call) |
Delete by key or keys:[...], workspace-fenced (idempotent).
Returns count. { key | keys }.
Call POST /v/stored_file.delete with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool stored_file.delete.
Getstored_file.get
| Property | Value |
|---|---|
| Capability | stored_file.read |
| Risk class | Read - autonomy L0 |
| Min. permission | Member |
| Availability | Core - always on (MCP tier 1) |
| Idempotent | No |
| Egress | None - in-box (pure Postgres, no outbound call) |
| Render schema | Yes - drives an inline chat artefact and a GUI panel |
a frontend StoredFile by its storage key (or /api/documents URL) and return the decrypted bytes as base64 plus metadata. This is the kernel seam that lets legacy step handlers (BUNDLE, ANNOTATE, PAYMENT) read files that live in the app’s storage backend (DB/S3/disk) without the kernel owning the storage implementation.
Call POST /v/stored_file.get with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool stored_file.get.
Get metadatastored_file.get_metadata
| Property | Value |
|---|---|
| Capability | stored_file.read |
| Risk class | Read - autonomy L0 |
| Min. permission | Member |
| Availability | Core - always on (MCP tier 1) |
| Idempotent | No |
| Egress | None - in-box (pure Postgres, no outbound call) |
| Render schema | Yes - drives an inline chat artefact and a GUI panel |
only the metadata of a frontend StoredFile by key.
Call POST /v/stored_file.get_metadata with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool stored_file.get_metadata.
Putstored_file.put
| Property | Value |
|---|---|
| Capability | stored_file.write |
| Risk class | Write - autonomy L1 |
| Min. permission | Member |
| Availability | On demand (MCP tier 2) |
| Idempotent | No |
| Egress | None - in-box (pure Postgres, no outbound call) |
CAS-or-upsert a stored file. When expectedVersion is present: a
single-row compare-and-swap UPDATE WHERE key+version+workspace (version+1); 0 rows -> {committed
{ key, filename, mimeType, fileSize, contentBase64?, checksum?, storageBackend?=DB, createdById?, expectedVersion? }.
Call POST /v/stored_file.put with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool stored_file.put.