> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcade.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Uploads

> Upload your own artwork or a reference image.

You can upload two kinds of image:

* **Artwork** becomes a pattern. Make products from it or refine it, like a generated pattern.
* **A reference** guides a generation or an edit. Pass it to `patterns/create` or `patterns/refine/edit`.

Both use the same three steps. Only the endpoint names differ.

| | Artwork | Reference |
| - | - | - |
| 1. Get an upload URL | `patterns/createUpload` | `references/createUpload` |
| 2. Send the file | `PUT` to `uploadUrl` | `PUT` to `uploadUrl` |
| 3. Save the upload | `patterns/upload` | `references/create` |
| You get | A `patternId` | A `referenceId` |

Files can be JPEG, PNG, WebP or GIF, up to 10 MiB.

**1. Get an upload URL**

Call `patterns/createUpload` with the file's media type and size in bytes.

```bash cURL theme={null}
curl --fail-with-body https://platform.arcade.ai/v1/patterns/createUpload \
  -H "Authorization: Bearer $ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: your-app/1.0 (you@example.com)" \
  -d '{
    "requestId": "lemon-artwork-upload-1",
    "mediaType": "image/png",
    "byteLength": 482113
  }'
```

```json theme={null}
{
  "uploadId": "7f3c2a91-4b6e-4d0a-9c58-2e1f6a7b3d04.png",
  "uploadUrl": "https://...",
  "requiredHeaders": { "Content-Type": "image/png" },
  "expiresAt": "2026-11-04T18:36:07.000Z"
}
```

**2. Send the file**

`PUT` the file to `uploadUrl` before `expiresAt`. Send every header in `requiredHeaders`, exactly as returned.

```bash cURL theme={null}
curl --fail-with-body -X PUT "<uploadUrl>" \
  -H "Content-Type: image/png" \
  --data-binary @lemon.png
```

Don't send your API key with this request. The URL is already signed.

**3. Save the upload**

Call `patterns/upload` with the `uploadId` and a new `requestId`.

```bash cURL theme={null}
curl --fail-with-body https://platform.arcade.ai/v1/patterns/upload \
  -H "Authorization: Bearer $ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: your-app/1.0 (you@example.com)" \
  -d '{
    "requestId": "lemon-artwork-save-1",
    "uploadId": "7f3c2a91-4b6e-4d0a-9c58-2e1f6a7b3d04.png"
  }'
```

The response is the pattern itself, not a job. Among other fields, it includes:

```json theme={null}
{
  "patternId": "cmujm2c8k000apc10w2yd6n4f",
  "imageUrl": "https://...",
  "width": 2048,
  "height": 2048
}
```

Use the `patternId` in [`products/create`](https://docs.arcade.ai/quickstart) or in a refine.

## Use a reference

Upload a reference with `references/createUpload` and `references/create`, then pass its `referenceId`:

* In `referenceIds` on `patterns/create`, to guide a new pattern.
* As `referenceId` on `patterns/refine/edit`, to guide an edit.

## Retries

Saving the same `uploadId` again returns the same pattern or reference. It never makes a duplicate. See [Idempotency](https://docs.arcade.ai/idempotency.md#uploads).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.