Orkestia storage
Orkestia storage is a private place for your organization's files. An organization admin turns it on once. You do not create a bucket, and you do not give Orkestia a key to your cloud account.
A call uses one target. Pass storage_space_uuid and leave the storage connection and the bucket empty. Passing both is refused. Nothing picks a space for you.
Your own bucket still works. Cloud connections is that path. This page is the path that does not need one.
Turn it on
An organization admin runs storage.native.enable. Running it again returns the same space.
data.storage.native.status reports whether the space is on, its quota, and how many bytes are in use. The default quota is 5 GiB. Writes stop when the space is full. A short-lived upload link cannot cap the size of the file the client sends, so a later check can block further writes if a file went over the quota.
The result includes storage_space_uuid. Keep it. Where a form asks for storage, the space is listed as Orkestia storage after it is on. The form does not select it for you.
In the desktop app, Billing → Storage shows the bytes in use and the quota. That usage is measured. It is not a line on the invoice.
A folder for one app or one end user
An organization admin can give one app, or one end user, a private folder inside the space. The folder is called a virtual bucket. Files written to one bucket stay in that bucket.
| You want | Workflow |
|---|---|
| Create a bucket | storage.native.bucket.create with a name and either identity_app_uuid or end_user_uuid |
| See the buckets | data.storage.native.buckets |
| Retire a bucket | storage.native.bucket.delete with confirm set to true |
A name is lowercase letters, digits, and hyphens. Retiring a bucket refuses new writes. Files already in it stay until they are deleted or the space is purged.
The same controls are on Billing → Storage.
Store and read a file
These take storage_space_uuid alone:
| Workflow | What it does |
|---|---|
storage.object.put | Write a small file from the platform |
storage.upload.presigned-url | A short-lived link the client uses to upload |
storage.download.presigned-url | A short-lived link for one file |
storage.object.get | Read a small file back |
storage.object.head | Size and checksum, without the bytes |
storage.object.delete | Remove one file |
storage.pdf.assemble | Build a PDF into the space |
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.
Documents in an app
An end user who is signed in to your app uploads with data.appdata.document.request-upload and only storage_space_uuid.
An organization member's token cannot take that path. Document upload belongs to the person using the app.
Agents and chat
A file that already lives in the space can be attached to an agent session. The same file can be attached to a chat completion (ai.chat.complete, field attachment_uuids). The assistant receives a short-lived link for that file. It does not receive a credential.
Coding artifacts
On runner.group-creation or runner.group-update, set:
coding_artifact_storage_space_uuidto the spacecoding_artifact_retention_daysfrom 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 space quota still applies. Binding the group does not start a coding session by itself.
Turn it off
storage.native.disable stops new writes. Reads keep working. The default hold is 30 days.
storage.native.purge deletes the space and its files. It asks for confirmation, and it runs only after the space is disabled. Deleted files can be recovered by the platform for 7 days. After that they are gone.
Usage is measured and shown under Billing → Storage. It is not a line on the invoice.
Where it is used
Where to use it is the list: files, documents, agents, chat, a coding group, a media profile, and WhatsApp files on a number you already bound.
What stays where it is
Turning the space on does not move files you already keep.
| Still uses what you configured | Why |
|---|---|
| Messages and files already in a chat | They stay on that chat's own file storage. A new WhatsApp file can be copied into the space. See Where to use it |
| An app's site files, up to 4 MB each | They stay on the app's site |
| A media profile that already names a bucket | It keeps that bucket until you set the space on media.profile.setup |
| A setup that already stored a storage connection | It keeps that connection until you change that setup |
To use your own bucket for everything else, stay on Cloud connections.
Container images go to Orkestia Registry at registry.orkestia.dev.