# Add a bucket

> Page: https://docs.plotwork.dev/api/post-orgs-org-storage. Index of every page: https://docs.plotwork.dev/llms.txt

Adds a keyless bucket that trusts Plotwork’s issuer for this organisation.

`POST /orgs/{org}/storage`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Add a bucket. |
| What does it take? | A JSON body of type [`CreateStorageBody`](https://docs.plotwork.dev/api/schemas.md#createstoragebody). |
| What does it return? | Status 201 with a body of type [`StorageDestination`](https://docs.plotwork.dev/api/schemas.md#storagedestination). |
| What can go wrong? | `400` a field is not in the form the bucket needs (storage.invalid); `401` not signed in; `403` not the owner or an admin (orgs.forbidden), the plan does not include it (plan.storage_not_included), or the origin may not make changes; `404` no such organisation or destination, or the caller is not a member; `409` that kind is already set up (storage.exists); `429` too many requests; `503` sending to your storage is not available on this server (storage.unavailable). Every failure uses the one error envelope. |

## What it does

Adds a keyless bucket that trusts Plotwork’s issuer for this organisation. It sends nothing until it is turned on. One of each kind.

## Path parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `org` | `string` | yes | The organisation's id or its slug. |

## Request body

The body has the type [`CreateStorageBody`](https://docs.plotwork.dev/api/schemas.md#createstoragebody).

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"s3" \| "azure_blob" \| "gcs"` | yes | A bucket. Google Drive is added by signing in with Google. |
| `target` | `StorageS3Target \| StorageAzureBlobTarget \| StorageGcsTarget` | yes |  |
| `send` | `StorageSend` | no |  |
| `send.folders` | `array \| null` | yes | Library folders to send, each with the folders inside it; null for every folder that has no access rule. |
| `send.formats` | `("svg" \| "source")[]` | yes | svg sends the picture; source sends the .diagram text the picture carries, when it carries one. |
| `send.scheme` | `"published" \| "light" \| "dark"` | yes | A picture that follows the reader’s color scheme is sent as it is, or pinned to light or dark. |
| `send.mirrorDeletions` | `boolean` | yes | Remove a file when its diagram is deleted from the library or moved out of what is sent. |
| `send.skipConfidential` | `boolean` | yes | Leave out diagrams labelled Confidential. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 201 | The destination, in setup. | [`StorageDestination`](https://docs.plotwork.dev/api/schemas.md#storagedestination) |
| 400 | A field is not in the form the bucket needs (storage.invalid). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 403 | Not the owner or an admin (orgs.forbidden), the plan does not include it (plan.storage_not_included), or the origin may not make changes. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | No such organisation or destination, or the caller is not a member. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 409 | That kind is already set up (storage.exists). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | Sending to your storage is not available on this server (storage.unavailable). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 201 answer has the type [`StorageDestination`](https://docs.plotwork.dev/api/schemas.md#storagedestination).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | yes |  |
| `type` | `"google_drive" \| "s3" \| "azure_blob" \| "gcs"` | yes | google_drive, s3, azure_blob or gcs. |
| `state` | `"setup" \| "on" \| "paused"` | yes | setup while the steps are not done (nothing is sent), on, or paused. |
| `connected` | `boolean` | yes | False for Google Drive until a Google account has granted access; true for a bucket. |
| `target` | `StorageGoogleDriveTarget \| StorageS3Target \| StorageAzureBlobTarget \| StorageGcsTarget` | yes |  |
| `send` | `StorageSend` | yes |  |
| `send.folders` | `array \| null` | yes | Library folders to send, each with the folders inside it; null for every folder that has no access rule. |
| `send.formats` | `("svg" \| "source")[]` | yes | svg sends the picture; source sends the .diagram text the picture carries, when it carries one. |
| `send.scheme` | `"published" \| "light" \| "dark"` | yes | A picture that follows the reader’s color scheme is sent as it is, or pinned to light or dark. |
| `send.mirrorDeletions` | `boolean` | yes | Remove a file when its diagram is deleted from the library or moved out of what is sent. |
| `send.skipConfidential` | `boolean` | yes | Leave out diagrams labelled Confidential. |
| `subject` | `string \| null` | yes | The subject Plotwork’s issuer signs for this destination, which the bucket’s trust names. Null for Google Drive. |
| `createdAt` | `integer` | yes |  |
| `updatedAt` | `integer` | yes |  |
| `status` | `StorageStatus` | yes |  |
| `status.queued` | `integer` | yes |  |
| `status.delivered` | `integer` | yes |  |
| `status.dropped` | `integer` | yes |  |
| `status.droppedLast24h` | `integer` | yes |  |
| `status.files` | `integer` | yes | Diagrams the destination holds a copy of now. |
| `status.lastSuccessAt` | `integer \| null` | yes |  |
| `status.lastErrorAt` | `integer \| null` | yes |  |
| `status.lastError` | `string \| null` | yes | What failed last, in our words. Never what the destination answered. |
| `status.nextAttemptAt` | `integer \| null` | yes |  |
| `status.failingSince` | `integer \| null` | yes |  |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |