---
title: "Upload files"
method: POST
path: "/uploads"
tags: ["Uploads"]
---

# Upload files

`POST /uploads`

## Request

- Base URL: `https://www.rainbrand.com/api/v1`
- URL: `https://www.rainbrand.com/api/v1/uploads`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://www.rainbrand.com/api/auth/oauth2/authorize`
    - Token URL: `https://www.rainbrand.com/api/auth/oauth2/token`

Make local files available to Rainbrand requests, such as Acme Inc.'s brand guide or an Atlas Pro product photo.

This endpoint reserves storage and returns an `uploadUrl` for each file. Send each file's raw bytes with `PUT` to its `uploadUrl`, using the returned `headers`.

Once the upload is complete, use `uploadId` to:

- Supply file sources when you [add a brand](/api-reference/brands/create-a-brand) or [prepare a Brand Edit](/api-reference/brands/create-a-brand-edit).
- [Save media in a Brand Library](/api-reference/library/add-to-a-brand-library) for reuse.
- [Upload a custom brand font](/api-reference/brands/upload-a-brand-font).
- [Request a Review](/api-reference/reviews/request-a-review) of an image or provide supporting images.

For [generation requests](/api-reference/generations/start-a-generation), pass the returned `url` where the model's input schema expects a file URL. Set `contentType` on this upload request to match the file. The `uploadUrl` is only for sending the bytes.

Uploads are temporary and expire at `expiresAt`. Uploading alone does not add the file to a brand or its Library.

## Request body

- object
  - `workspaceId` string: Team ID from GET /workspaces. Omit for your personal account.
  - `files` object[], required: Local files to stage (1–30, at most 100 MiB each and 256 MiB combined)
    - `filename` string, required: Original filename used when the upload is consumed
    - `byteLength` integer, required: Exact file size in bytes
    - `contentType` string: The file's MIME type, such as image/png. Set it before passing the upload's url to a model, so the file is served with that type. Supported types are kept: PNG, JPEG, WebP, AVIF, GIF, SVG, MP4, WebM, MOV, MP3, WAV, OGG, FLAC, AAC, M4A, and PDF. Others, or none, are stored as application/octet-stream.

## Response `201`

OK

- object
  - `data` object, required
    - `uploads` object[], required
      - `uploadId` string, uuid, required
      - `filename` string, required
      - `byteLength` integer, required
      - `uploadUrl` string, uri, required
      - `url` string, uri, required: Temporary link to the uploaded file, valid until expiresAt once the PUT completes. Pass it where a model input expects a file URL in POST /generations, after reserving the upload with its contentType. Use uploadId everywhere else.
      - `method` 'PUT', required
      - `headers` object, required
        - `content-type` string, required: The requested contentType when it is kept, otherwise application/octet-stream.
        - `cache-control` 'max-age=3600', required
        - `x-upsert` 'false', required
      - `expiresAt` string, date-time, required

## Other responses

- `400`: 400
- `401`: 401
- `403`: 403
- `404`: 404
- `429`: 429
- `500`: 500

---

[API](https://skmtc.dev/rainbrand/apis/rainbrand-api.md) - [All operations](https://skmtc.dev/rainbrand/apis/rainbrand-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rainbrand/apis/rainbrand-api/revisions/012b8e9da4df?raw)