# Files with your AI agent

> Your agent creates buckets, uploads files and reads or removes them, with the project's own storage.

## What your agent can do

- Create a bucket (stored in Paris, EU) or reuse one.
- Upload a file: reserve it, send its bytes to a one-time address, then confirm.
- List, read and delete files, and read how much the project stores.
- Share a file with a signed link that expires (REST API).

## Ask your agent

Paste a request like these in your AI once it is connected. It calls the tools in this order.

| You ask | Your agent calls |
|---|---|
| “Store logo.png in a bucket named assets.” | `list_buckets` → `create_bucket` → `start_upload` → `commit_upload` |
| “List the files in assets with their sizes.” | `list_buckets` → `list_objects` |
| “Delete old-report.pdf.” | `list_objects` → `delete_object` |
| “How much storage do we use?” | `get_storage_usage` |

## Tools and routes

Every tool is a call to the REST route next to it, with the same permissions, limits and idempotency. `tools/list` shows only the tools your connection can call.

| Tool | What it does | Scope | Same through the REST API |
|---|---|---|---|
| `list_buckets` | List the storage buckets of this project. | `storage:read` | `GET /v1/storage/buckets` |
| `create_bucket` | Create a storage bucket. | `storage:write` | `POST /v1/storage/buckets` |
| `get_bucket` | Read a storage bucket. | `storage:read` | `GET /v1/storage/buckets/{bucket_id}` |
| `list_objects` | List the files of a bucket. | `storage:read` | `GET /v1/storage/buckets/{bucket_id}/objects` |
| `get_object` | Read a file's metadata. | `storage:read` | `GET /v1/storage/objects/{object_id}` |
| `start_upload` | Reserve a file and get a one-time upload address (PUT the bytes there). | `storage:write` | `POST /v1/storage/buckets/{bucket_id}/uploads` |
| `commit_upload` | Confirm an upload once the bytes are sent. | `storage:write` | `POST /v1/storage/uploads/{upload_id}/commit` |
| `delete_object` | Delete a file from its bucket. | `storage:write` | `DELETE /v1/storage/objects/{object_id}` |
| `get_storage_usage` | Stored bytes and file count of this project. | `storage:read` | `GET /v1/storage/usage` |

Also through the REST API:

- `POST /v1/storage/objects/{object_id}/links`

## Limits, free tier and pricing

Read from the platform code each time this page is served.

| Limit | Value |
|---|---|
| Buckets per project | **10** |
| One upload in a single request | **256 MiB** |
| One object (multipart upload) | **50 GiB** |
| Object key | **1 KiB** |
| Part size of a multipart upload (the last one is smaller) | **64 MiB** |
| Parts per multipart upload | **10,000** |
| Shortest signed link | **1 min** |
| Longest signed link | **7 days** |
| Previous versions kept (default) | **30 days** |
| One upload through the transfer relay | **256 MiB** |

Usage prices, in US dollars, read from the price grid served by the platform each time this page is served. Paid from the prepaid balance.

| Item | Price | Unit |
|---|---|---|
| `go_mois` | 0.033 USD | per GB a month |

Your agent reads the current prices with `get_pricing` and the spending limits with `get_limits`.

## Good to know

- The bytes are not sent through MCP: the agent sends them with an HTTP PUT to the one-time address that `start_upload` returns, then calls `commit_upload`.
- Deleting a file cannot be undone: the agent asks you first.
- Storage is paid from the prepaid balance; an upload the balance does not cover is refused.

## Next

- [Full service documentation](/cloud/docs/services/storage)
- [Connect your AI](/cloud/docs/ai-assistants)
- [All capabilities](/cloud/docs/agents)
- [API reference](/cloud/docs/api)
