# Let your app's users upload images

Turn on uploads for your app's users in the console, set the largest file and a per-user total, and see what the SDK and the upload routes do with them.

Your app's signed-in users can upload a workspace image or a profile picture
through the SDK. Their files are yours: stored for your organization, counted
against its storage, public so they can be shown, and kept until you delete
them in Assets. This guide sets what Acme Analytics' users may upload.

> **Note:**
  A console role that can change organization settings, and `@buildbase/sdk`{' '}
  0.0.84 or
  later in your app. An older SDK has no upload control: its workspace image is
  an emoji or a URL.

## 1. Open Billing

[Open Billing in the console](https://console.buildbase.app/dashboard/admin/setting/organization/billing)

Choose **Settings**, then **Billing** under **Organization**. The **Storage**
card says how much your organization holds; its last part is **End-user
uploads**.

![The Storage card on the Billing page, its title highlighted as step 1: what your organization holds, then End-user uploads with its switch](/images/assets/end-user-uploads/billing.webp)

## 2. Turn uploads on

Under **End-user uploads**, turn on "Let your app's users upload files through
the SDK." The sentence above the switch says what is allowed now. Uploads are on
until you turn them off.

![End-user uploads on the Storage card, with the switch Let your app's users upload files through the SDK highlighted as step 2](/images/assets/end-user-uploads/toggle.webp)

## 3. Set the limits

Set **Largest file (MB)**, up to 5 MB, and **Per user in all (MB)**, or leave
it blank for no limit per user. Press **Save**. The sentence then reads, for
example, "Your app's users can upload files up to 2 MB each, 20 MB per user in
all."

![End-user uploads with Largest file (MB) highlighted as step 3, Per user in all (MB) and the Save button](/images/assets/end-user-uploads/limits.webp)

## 4. Optional: stop at your allowance

On a plan that bills storage overage, the Storage card also has "Stop uploads
at X instead of billing overage." With it on, every upload stops at your plan's
allowance, your users' included, instead of being billed
([turning overage off](/assets/overview#turning-overage-off)).

![The Storage card on a paid plan, with the switch Stop uploads at the plan's allowance instead of billing overage highlighted as step 4](/images/assets/end-user-uploads/overage.webp)

## 5. Your users upload

The SDK's own workspace settings offer an image upload under **General**, and
the profile screen a picture upload, whenever uploads are on. In **General**,
under **Icon**, your user picks **Upload Image**, then **Choose an image**; the
line beneath says the largest file you allow.

![The SDK's workspace settings, General: Icon with Upload Image chosen, the Choose an image button highlighted as step 5, and PNG, JPG, GIF, WebP or SVG, up to 2 MB beneath it](/images/assets/end-user-uploads/sdk-general.webp)

![The same on a phone: Choose Emoji, Upload Image and Custom Image URL stacked, with Choose an image highlighted as step 5](/images/assets/end-user-uploads/sdk-general-phone.webp)

For your own screen, `useUpload` does the whole upload:

```tsx
import { useUpload } from '@buildbase/sdk/react';

function WorkspaceImage({ onUploaded }: { onUploaded: (url: string) => void }) {
  const { upload, loading, error, enabled, maxLabel } =
    useUpload('workspace-image');
  if (!enabled) return null;
  return (
    <label>
      Workspace image (up to {maxLabel})
      <input
        type="file"
        accept="image/*"
        disabled={loading}
        onChange={async (e) => {
          const file = e.target.files?.[0];
          if (file) onUploaded((await upload(file)).url);
        }}
      />
      {error && <p role="alert">{error}</p>}
    </label>
  );
}
```

`enabled` and `maxBytes` come from the settings above, so hide or limit the
control with them rather than waiting for a refusal. The hook's fields are in
the [API reference](/reference/api-reference#uploads).

## Check it works

Upload a workspace image from your app, then open **Content**, then **Assets**:
the file is there, public, with the user as its creator, and the storage meter
is higher by its size.

## Things to watch out for

- **Files your users upload are yours.** They count against your storage and stay until you delete them in Assets.
- **The largest file is 100 KB to 5 MB**, and a per-user total is at least 100 KB, or no limit.
- **Turning uploads off hides the control in the SDK.** Files already uploaded stay.
- **On a self-hosted install, Billing is not in the console's menu.** Set the policy with `PATCH /api/storage/settings`, below.

## Setting it over the API

Set the same three values with `PATCH /api/storage/settings`:

```bash
curl -X PATCH https://api.console.buildbase.app/api/storage/settings \
  -H "Authorization: Bearer $BUILDBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"endUserUploads":{"enabled":true,"maxFileBytes":1048576,"perUserBytes":null}}'
```

| Field          | Contents                                                                            | Default |
| -------------- | ----------------------------------------------------------------------------------- | ------- |
| `enabled`      | Whether your app's users may upload at all                                          | `true`  |
| `maxFileBytes` | The largest one file may be, from 102,400 (100 KB) to 5,242,880 (5 MB)              | 5 MB    |
| `perUserBytes` | The most one user may hold in all, at least 100 KB, or `null` for no per-user limit | `null`  |

Send any of the three; the others keep their values. It takes the permission to
change organization settings, and answers the usage response with the new
`endUserUploads`. The SDK reads the policy from your public settings, which
`GET /api/v1/public/:orgId/settings` answers as `uploads: { enabled,
maxFileBytes }`. `enabled` there is also `false` when the server has no direct
uploads, so the SDK offers an upload only when one can succeed.

## The requests

`useUpload` does all of this; the routes matter when you build your own. Each
runs with the signed-in user's session, like every SDK call.

| Method | Path                                  | Body or answer                                                                                                                         |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `POST` | `/api/v1/public/uploads`              | `{ purpose, name, size, contentType }`, answered like an asset intent: `uploadId`, `url`, `method`, `headers`, `expiresAt`, `maxBytes` |
| `PUT`  | the signed `url`                      | The file, with exactly the `headers` returned                                                                                          |
| `POST` | `/api/v1/public/uploads/:id/complete` | `{ id, name, size, mimeType, url, width, height }` - `url` is the file's public URL                                                    |

`purpose` is `workspace-image` or `profile-image`, and the intent takes no
other field. Only the user who started an upload can complete it; anyone else
gets `404`.

| Status | Code                                       | When                                                                                                                                 |
| ------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `INVALID_UPLOAD`                           | A `purpose` other than the two above, a missing size, a type that is not an image, or a file that is not what it was declared as     |
| `403`  | `UPLOADS_DISABLED`                         | You turned end-user uploads off                                                                                                      |
| `403`  | `USER_UPLOAD_LIMIT`                        | The file would take the user past `perUserBytes`; the body carries `heldBytes` and `limitBytes`                                      |
| `413`  | `UPLOAD_TOO_LARGE`                         | The file is over `maxFileBytes`, or an SVG over 1 MB; on complete, what arrived is larger than declared. The body carries `maxBytes` |
| `429`  |                                            | Too many uploads from one address, or for your organization today                                                                    |
| `503`  | `UPLOADS_UNAVAILABLE`                      | Your organization cannot take the file: storage full, or a plan limit                                                                |
| `501`  | `UPLOADS_UNAVAILABLE`                      | The server has no direct uploads configured                                                                                          |
| `409`  | `UPLOAD_NOT_RECEIVED`, `UPLOAD_FINALIZING` | On complete: the PUT has not arrived, or the file is still being checked. Try again in a moment                                      |

The `503` is deliberately neutral: your user cannot act on your plan, and your
storage meter already says why. The `402` your team gets when storage is full
([when an upload does not fit](/assets/overview#when-an-upload-does-not-fit))
is never sent to them.

## Saving the result

The upload answers a URL; store it where the image belongs:

- **A workspace image**: send it as `image` when creating or updating the
  workspace (`PUT /api/v1/public/workspaces/:id` with `name` and `image`).
- **A profile picture**: `PATCH /api/v1/public/profile` with `{ "image": url }`.
  An empty string removes the picture.

Both fields take any image URL up to 2048 characters, not only an uploaded one.

## Next Steps

- [Assets overview](/assets/overview) - storage, billing and every upload refusal.
- [Upload and share images in the console](/assets/manage-assets) - the Assets screen.
- [Error codes](/reference/error-codes#uploads-and-storage) - every upload refusal in one table.
