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

# Upload an asset

> Uploads an image to use in a template.

Upload images, then reference the returned `id` in the template's `definition` when you [update a template](https://tapace.lk/docs/api-reference/templates/update.md). Assets are shared by test and live.

**Idempotency-Key** `string` *required*

A unique value for this request.

**slot** `string` *required*

Where the image goes on the pass. Which slots a template can use depends on its type.

| Slot | Use |
| - | - |
| `icon` | The small icon Apple Wallet shows in notifications and on the Lock Screen. Every template needs one. |
| `logo` | The logo at the top of the Apple Wallet pass. |
| `strip` | The image behind the main fields of an event ticket, or a points card's strip. |
| `thumbnail` | A small image beside the fields. |
| `background` | An event ticket's blurred background on Apple Wallet. |
| `footer` | Accepted, but no template type shows it yet. |
| `artwork` | The poster artwork on iOS 27 and later. |
| `primary_logo` | The logo on the iOS 27 poster. It's resized to fit 252 × 72 pixels. |
| `hero` | The banner image on Google Wallet. |
| `google_logo` | The logo on Google Wallet, which crops it into a circle, so use a square of at least 660 × 660 pixels with a full-bleed background. |
| `google_wide_logo` | A wide logo for the top of the Google Wallet pass, such as 1280 × 400 pixels. Google still shows `google_logo` in the pass list and details. |
| `stamp` | A stamp card's stamp, in place of a built-in stamp icon. |
| `stamp_empty` | How a stamp card's unearned stamps look. |
| `stamp_background` | The image behind a stamp card's stamps. |

See [Stamp cards](https://tapace.lk/docs/guides/stamp-cards.md) for the stamp images.

**data** `string` *required*

The image file, base64-encoded. Up to 5 MiB, and from 16 to 4000 pixels on each side.

**contentType** `string`

The file's MIME type, such as `image/png`. TapAce checks the file itself, so this is optional.

### Response

**id** `string`

Unique ID, starting with `asset_`.

**slot** `string`

The slot the image was uploaded for.

**contentType** `string`

The stored image's MIME type.

**byteSize** `integer`

The stored image's size in bytes.

**width** `integer`

Width in pixels.

**height** `integer`

Height in pixels.

### Errors

| Status | When |
| - | - |
| `400` | The slot is unknown, the file is empty or not a valid image, or its size in pixels is out of range. |
| `413` | The file is larger than 5 MiB. |

```bash cURL theme={null}
curl https://api.tapace.lk/v1/assets \
  -H "Authorization: Bearer $TAPACE_API_KEY" \
  -H "Idempotency-Key: 1c7f3a9e-5b2d-4e8a-a4c6-8d2f1b9e3a70" \
  -H "Content-Type: application/json" \
  -d "{ \"slot\": \"icon\", \"data\": \"$(base64 -w0 icon.png)\" }"
```

```json 201 theme={null}
{
  "object": "asset",
  "id": "asset_Xr9Lm2Qv7Tn4Kp8Zs1Wd",
  "slot": "icon",
  "contentType": "image/png",
  "byteSize": 4821,
  "width": 87,
  "height": 87,
  "createdAt": "2026-10-13T08:55:00.000Z"
}
```


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