> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tapace.lk/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 before you [create a template](/api-reference/templates/create), then reference the returned `id` in the template's `definition.images`. Assets are shared by test and live.

<ParamField header="Idempotency-Key" type="string" required>
  A unique value for this request.
</ParamField>

<ParamField body="slot" type="string" required>
  Where the image goes on the pass: `icon`, `logo`, `strip`, `thumbnail`, `background`, `footer` or `hero`.
</ParamField>

<ParamField body="data" type="string" required>
  The image file, base64-encoded. Up to 5 MiB, and from 16 to 4000 pixels on each side.
</ParamField>

<ParamField body="contentType" type="string">
  The file's MIME type, such as `image/png`. TapAce checks the file itself, so this is optional.
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique ID, starting with `asset_`.
</ResponseField>

<ResponseField name="slot" type="string">
  The slot the image was uploaded for.
</ResponseField>

<ResponseField name="contentType" type="string">
  The stored image's MIME type.
</ResponseField>

<ResponseField name="byteSize" type="integer">
  The stored image's size in bytes.
</ResponseField>

<ResponseField name="width" type="integer">
  Width in pixels.
</ResponseField>

<ResponseField name="height" type="integer">
  Height in pixels.
</ResponseField>

### 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. |

<RequestExample>
  ```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)\" }"
  ```
</RequestExample>

<ResponseExample>
  ```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"
  }
  ```
</ResponseExample>


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