Where to use it
Turn the space on first. Orkestia storage is that step: an organization admin runs storage.native.enable, then keeps storage_space_uuid.
Every call below takes that id and leaves the storage connection and the bucket empty. Passing both is refused. A form that asks for storage lists Orkestia storage first and selects it when the organization has a space.
A folder for one app or one end user
An organization admin creates a virtual bucket with storage.native.bucket.create. Pass a name and exactly one of identity_app_uuid or end_user_uuid. data.storage.native.buckets lists them. storage.native.bucket.delete with confirm set to true retires one: new writes stop, and files already stored stay.
Billing → Storage in the desktop app creates, lists, and retires these buckets, and shows the bytes in use. That usage is not a line on the invoice.
On the file itself
Say which file and which space. The assistant runs one of these with only storage_space_uuid.
| You want | Workflow |
|---|---|
| A small file stored from the platform | storage.object.put |
| A short-lived link the client uses to upload | storage.upload.presigned-url |
| A short-lived link for one file | storage.download.presigned-url |
| A small file read back | storage.object.get |
| The size and checksum, without the bytes | storage.object.head |
| One file removed | storage.object.delete |
| A PDF built into the space | storage.pdf.assemble |
A download link is for one file and it expires. A later status read shows that a link was issued. It does not repeat the link.
In your app
An end user who is signed in to your app uploads a document with data.appdata.document.request-upload and only storage_space_uuid.
An organization member's own token cannot take that path. Document upload belongs to the person using the app.
With an agent or a chat
A file that already lives in the space can be an attachment.
| You want | What you pass |
|---|---|
| An agent reads the file | The file's id on the session |
| A chat looks at an image that is already there | ai.chat.complete with attachment_uuids |
The assistant receives a short-lived link for that file. It does not receive a credential.
On a coding group
On runner.group-creation or runner.group-update, set coding_artifact_storage_space_uuid to the space and coding_artifact_retention_days from 7 to 90. Leave the coding storage connection empty.
The group's files live in the space. Files older than the retention are removed. The 5 GiB quota still applies. Binding the group does not start a coding session.
On a media profile
media.profile.setup accepts the space alone: set storage_space_uuid and leave the connection and the bucket empty.
Setup runs the image check and stores the proof image in the space. The profile is ready when that check succeeds. It still needs an AI provider config whose model can generate images. Set up the studio is the same check when the profile uses a bucket you connected.
On WhatsApp
This does not connect a number. A number you already bound can copy new photos, documents, video, and voice notes into the space.
On buzz.channel.whatsapp.configure, set media_storage to {"storage_space_uuid": "<space>"}. The chat message stays in the chat. Files already in the chat stay there. WhatsApp is the rest of that setup, including how a number is bound.
What does not use it
- Files already in a bucket you connected. They stay there.
- Messages and files already in a chat. They stay on that chat.
- An app's site files, up to 4 MB each. They stay on the site.
- A media profile that already names a bucket. It keeps that bucket until you set the space on setup.
- A setup that already saved a storage connection. It keeps that connection until you change it.