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

# Product images and media

> Import images from a URL or upload files, attach them to products, set alt text, order the gallery and choose the main image through the WISEPIM API.

Product images live in the project's **media library**. A file is stored once, as an **asset**, and products show it by linking to it. This page explains that model, the two ways to get a file into the library, and how to control which images a product shows and in which order.

## How media is modelled

| Concept | What it is |
| - | - |
| **Asset** | One file in the media library: an image (JPEG, PNG, GIF, WebP, AVIF, TIFF, BMP) or a PDF. Asset ids are **UUIDs**, not integers. |
| **Product link** | An asset attached to a product, with a `position`. A product shows its assets by ascending `position`. One asset can be attached to many products, for example a size chart shared by every shirt. |
| **`main_image`** | The product's main image. It is the **first image** in the product's order. It carries the same value as that asset's `url`. |

An asset response describes the file and where it is used:

```json theme={null}
{
  "id": "4b1f6c2e-8d3a-4f0e-9a51-2c7d8e9f0a13",
  "filename": "tee-organic-navy-front.jpg",
  "mime_type": "image/jpeg",
  "file_size": 482113,
  "width": 2000,
  "height": 2000,
  "url": "/api/portal-assets/eyJhIjoiNGIxZjZjMmUifQ.Zk2pQ1",
  "thumbnail_url": "/api/portal-assets/eyJhIjoiNGIxZjZjMmUifQ.Zk2pQ1?rendition=thumbnail",
  "alt_text": { "en": "Organic cotton T-shirt in navy, front view", "nl": "T-shirt van biologisch katoen in navy, voorkant" },
  "source_url": "https://cdn.example-shop.com/img/tee-organic-navy-front.jpg",
  "products": [
    { "product_id": 8841, "position": 0, "is_main": true },
    { "product_id": 8842, "position": 2, "is_main": false }
  ],
  "products_truncated": false,
  "created_at": "2026-11-19T09:14:02Z",
  "updated_at": "2026-11-19T09:15:40Z"
}
```

* `url` is the durable path of the file, **relative to the WISEPIM app origin**. It looks like `/api/portal-assets/<token>`. Store it as returned. The token in the example is shortened.
* To download the file, prefix the path with `https://wisepim.com`. No API key is needed: the token in the path grants read access and redirects to a short-lived storage URL. Treat the path like a public link. `thumbnail_url` is the same token with `?rendition=thumbnail`.
* `source_url` is set when the asset was imported from a URL.
* `products` lists at most **100** products, ordered by position. `products_truncated` is `true` when the asset may be attached to more products than are listed.

> [!NOTE]
>
> `main_image` is **read-only** on product writes. Sending it to [`POST /products`](https://docs.wisepim.com/en/api-reference/products/create), [`PATCH /products/{product_id}`](https://docs.wisepim.com/en/api-reference/products/update) or [`POST /products/batch`](https://docs.wisepim.com/en/api-reference/products/batch) is a `422`, because the field is not part of the writable schema. Change the main image with the media routes on this page. Every product whose images change gets a new `version` and `updated_at`, so an incremental sync with `updated_since` picks it up.

## Endpoints and scopes

Media uses three scopes. Reading needs `assets:read`. Everything that adds files or changes a product's images needs `assets:write`. Only removing a file from the library needs `assets:delete`. See the [scope catalog](https://docs.wisepim.com/en/api-reference/authentication.md#scopes).

| Endpoint | Scope | Purpose |
| - | - | - |
| [`GET /assets`](https://docs.wisepim.com/en/api-reference/assets/list) | `assets:read` | List the library, or one product's images with `?product_id=` |
| [`GET /assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/get) | `assets:read` | Read one asset |
| [`GET /asset-imports`](https://docs.wisepim.com/en/api-reference/assets/list-imports) | `assets:read` | List URL imports, filter by `product_id` or `status` |
| [`GET /asset-imports/{import_id}`](https://docs.wisepim.com/en/api-reference/assets/get-import) | `assets:read` | Read the state of one URL import |
| [`POST /assets`](https://docs.wisepim.com/en/api-reference/assets/import-from-url) | `assets:write` | Import an image from a URL and attach it to a product (`202`) |
| [`POST /assets/upload`](https://docs.wisepim.com/en/api-reference/assets/upload) | `assets:write` | Upload a file as multipart form data, optionally attaching it |
| [`PATCH /assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/update) | `assets:write` | Set or clear alt text |
| [`POST /products/{product_id}/assets`](https://docs.wisepim.com/en/api-reference/assets/attach) | `assets:write` | Attach an existing asset to a product |
| [`PATCH /products/{product_id}/assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/move) | `assets:write` | Move one image to another position |
| [`PUT /products/{product_id}/asset-order`](https://docs.wisepim.com/en/api-reference/assets/reorder) | `assets:write` | Set the full order of a product's images |
| [`PUT /products/{product_id}/main-asset`](https://docs.wisepim.com/en/api-reference/assets/set-main) | `assets:write` | Choose the main image |
| [`DELETE /products/{product_id}/assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/detach) | `assets:write` | Detach an asset from one product |
| [`DELETE /assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/delete) | `assets:delete` | Delete the file from the library and from every product |

> [!TIP]
>
> Give a sync integration `assets:write` but not `assets:delete`. It can then attach, reorder and detach images, but it cannot remove a file that other products, or people working in the app, still use.

## Import an image from a URL

Use this when your images are already reachable on a public web address, such as a CDN or your current storefront. WISEPIM downloads the file in the background, so the request returns quickly and you poll for the result.

**1. Register the import**

Name the product with `product_id` or `sku`. Send exactly one of them.

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/assets \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: img-TEE-ORG-NAVY-M-front" \
  -H "Content-Type: application/json" \
  -d '{"sku": "TEE-ORG-NAVY-M", "url": "https://cdn.example-shop.com/img/tee-organic-navy-front.jpg", "position": 0}'
```

The response is `202 Accepted` with an **import receipt**, not an asset. Nothing has been downloaded yet.

```json theme={null}
{
  "id": 51207,
  "url": "https://cdn.example-shop.com/img/tee-organic-navy-front.jpg",
  "status": "pending",
  "product_id": 8841,
  "position": 0,
  "is_main": false,
  "asset_id": null,
  "error": null,
  "created_at": "2026-11-19T09:14:02Z",
  "settled_at": null
}
```

**2. Poll until it settles**

Call [`GET /asset-imports/{import_id}`](https://docs.wisepim.com/en/api-reference/assets/get-import) until `status` is `linked` or `failed`. The status moves through `pending`, `processing`, then `linked` or `failed`.

```bash theme={null}
curl https://wisepim.com/api/public/v1/asset-imports/51207 \
  -H "Authorization: Bearer $WISEPIM_API_KEY"
```

When `status` is `linked`, `asset_id` holds the new asset's UUID and the image is attached to the product. When it is `failed`, `error` explains why, for example an HTTP error from your server or an unsupported content type.

**3. Add alt text**

The import does not accept alt text. Sending `alt_text`, or any other field the route does not list, is a `422` validation error with a per-field `detail`; it is not ignored. Once the import is `linked`, set alt text on the asset with [`PATCH /assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/update). See [Alt text](#alt-text).

### Rules for the download

The download runs behind the same safety guard as every WISEPIM image import:

* Only `http` and `https` addresses on **public** hosts. Private, local and internal addresses are refused, and the check runs again on every redirect.
* A URL that is not a public `http(s)` address, or that contains credentials, is refused up front with `422 invalid_url`. URLs are limited to 2,000 characters.
* Only image content is accepted. HTML pages, PDFs and other types fail the import.
* At most **25 MB** per file.
* WISEPIM asks for the file **uncompressed**. If your server answers with a `Content-Encoding` other than `identity` (for example `gzip`), the import fails. Serve images without transfer compression.

### Placement and repeats

* `position` places the image among the product's images. When you omit it, the image goes after the product's current images, counting imports that are still pending.
* `is_main: true` puts the image first, so it becomes the `main_image` once it lands. It takes precedence over `position`, and the product's other images move one place back.
* A URL is stored **once per project**. Importing the same URL again does not create a second copy of the file. If an import of that URL for that product is still pending, the latest request decides its position.
* URL imports are not jobs. They do not appear under [`GET /jobs`](https://docs.wisepim.com/en/api-reference/jobs/get). [`GET /asset-imports`](https://docs.wisepim.com/en/api-reference/assets/list-imports) lists them, including imports started by connectors and the web app.

```python Python theme={null}
import os
import time
import requests

API = "https://wisepim.com/api/public/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['WISEPIM_API_KEY']}"}

def import_image(sku, url, position):
    receipt = requests.post(
        f"{API}/assets",
        headers={**HEADERS, "Idempotency-Key": f"img-{sku}-{position}"},
        json={"sku": sku, "url": url, "position": position},
        timeout=30,
    )
    receipt.raise_for_status()
    import_id = receipt.json()["id"]

    delay = 1
    while True:
        res = requests.get(f"{API}/asset-imports/{import_id}", headers=HEADERS, timeout=30)
        if res.status_code == 429:
            time.sleep(int(res.headers.get("Retry-After", delay)))
            continue
        res.raise_for_status()
        state = res.json()
        if state["status"] == "linked":
            return state["asset_id"]
        if state["status"] == "failed":
            raise RuntimeError(f"{sku}: {state['error']}")
        time.sleep(delay)
        delay = min(delay * 2, 30)
```

```javascript Node.js theme={null}
const API = "https://wisepim.com/api/public/v1";
const headers = { Authorization: `Bearer ${process.env.WISEPIM_API_KEY}` };

async function importImage(sku, url, position) {
  const res = await fetch(`${API}/assets`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": `img-${sku}-${position}` },
    body: JSON.stringify({ sku, url, position }),
  });
  if (res.status !== 202) throw new Error(`${sku}: ${res.status} ${await res.text()}`);
  const { id } = await res.json();

  let delay = 1000;
  for (;;) {
    const poll = await fetch(`${API}/asset-imports/${id}`, { headers });
    if (poll.status === 429) {
      const wait = Number(poll.headers.get("Retry-After") ?? delay / 1000) * 1000;
      await new Promise((r) => setTimeout(r, wait));
      continue;
    }
    if (!poll.ok) throw new Error(`${sku}: ${poll.status} ${await poll.text()}`);
    const state = await poll.json();
    if (state.status === "linked") return state.asset_id;
    if (state.status === "failed") throw new Error(`${sku}: ${state.error}`);
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 2, 30000);
  }
}
```

## Upload a file

Use an upload when the file is not on a public address, for example an export from a private DAM or a file on your own server. [`POST /assets/upload`](https://docs.wisepim.com/en/api-reference/assets/upload) takes `multipart/form-data` and stores the file in the same request.

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/assets/upload \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: upload-TEE-ORG-NAVY-M-back" \
  -F "file=@tee-organic-navy-back.jpg" \
  -F "sku=TEE-ORG-NAVY-M" \
  -F "position=1" \
  -F "alt_text=Organic cotton T-shirt in navy, back view"
```

| Field | Required | Meaning |
| - | - | - |
| `file` | Yes | The file. JPEG, PNG, GIF, WebP, AVIF, TIFF, BMP or PDF. |
| `product_id` or `sku` | No | Attach the file to this product. Send at most one. |
| `position` | No | Place among the product's images, 0 to 1,000,000. Appended when omitted. Needs a product. |
| `is_main` | No | Also make the file the product's main image. Images only. Needs a product. |
| `alt_text` | No | One alt text for every language, at most 500 characters. Use [`PATCH /assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/update) for per-locale text. |

* The **file's content** decides its type, not its name or the declared `Content-Type`. A renamed text file is refused with `422 unsupported_file_type`. An empty file is `422 empty_file`.
* The whole request body is limited to **10 MiB**. A larger request is refused with `413 payload_too_large` before anything is stored. For bigger images, use a URL import (25 MB).
* The same bytes are stored **once per project**. Uploading a file that is already in the library returns the existing asset with `200` instead of `201`, so a retried upload never creates a duplicate. If you named a product, the file is still attached to it.
* With an `Idempotency-Key`, the upload is identified by the file's content hash, its file name and the form fields. A retry of the same upload with the same key replays the original response. The same key with a different file or different fields is `409 idempotency_conflict`.
* The response is the asset. When you named a product, that product's entry is listed first in `products`.

## Alt text

Alt text describes an image for screen readers and search engines, and exports read it from the asset. Set it with [`PATCH /assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/update), either as one text for every language:

```bash theme={null}
curl -X PATCH https://wisepim.com/api/public/v1/assets/4b1f6c2e-8d3a-4f0e-9a51-2c7d8e9f0a13 \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: alt-4b1f6c2e-v1" \
  -H "Content-Type: application/json" \
  -d '{"alt_text": "Organic cotton T-shirt in navy, front view"}'
```

or as a map of locale to text:

```json theme={null}
{ "alt_text": { "en": "Organic cotton T-shirt in navy, front view", "nl-NL": "T-shirt van biologisch katoen in navy, voorkant", "de": "T-Shirt aus Bio-Baumwolle in Navy, Vorderansicht" } }
```

* Each text is at most 500 characters, and a map holds at most 100 locales. Locale keys look like `en`, `nl-NL` or `pt_BR`.
* Send `null` or an empty value to clear the alt text. Empty entries in a map are dropped.
* A map replaces the whole previous value. To change one language, send the full map.
* Channels receive the text for their locale, falling back to the same language.
* Alt text belongs to the asset, so it applies on every product that shows the asset. Each of those products gets a new `version`.

## Manage a product's images

These routes change which assets a product shows and in which order. Each one, except detach, returns the product's images in order together with its `main_image`:

```json theme={null}
{
  "product_id": 8841,
  "main_image": "/api/portal-assets/eyJhIjoiNGIxZjZjMmUifQ.Zk2pQ1",
  "assets": [
    { "asset_id": "4b1f6c2e-8d3a-4f0e-9a51-2c7d8e9f0a13", "position": 0, "is_main": true },
    { "asset_id": "9e7a0d55-31c4-4b6f-8f20-6a1b3c5d7e90", "position": 1, "is_main": false },
    { "asset_id": "c2d8f1a4-5b6e-4c7d-9e0f-1a2b3c4d5e6f", "position": 2, "is_main": false }
  ]
}
```

### Attach an existing asset

[`POST /products/{product_id}/assets`](https://docs.wisepim.com/en/api-reference/assets/attach) attaches an asset that is already in the library. It goes after the product's current images unless you send `position`. `is_main: true` also makes it the main image.

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/products/8842/assets \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: attach-8842-sizechart" \
  -H "Content-Type: application/json" \
  -d '{"asset_id": "c2d8f1a4-5b6e-4c7d-9e0f-1a2b3c4d5e6f"}'
```

The response is `201` when the asset was attached, or `200` when it was already attached. A product's first image becomes its `main_image`.

### Move one image

[`PATCH /products/{product_id}/assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/move) changes one image's `position`. Two images on the same position keep the order they were attached in.

```bash theme={null}
curl -X PATCH https://wisepim.com/api/public/v1/products/8841/assets/c2d8f1a4-5b6e-4c7d-9e0f-1a2b3c4d5e6f \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: move-8841-c2d8f1a4-to-1" \
  -H "Content-Type: application/json" \
  -d '{"position": 1}'
```

### Set the full order

[`PUT /products/{product_id}/asset-order`](https://docs.wisepim.com/en/api-reference/assets/reorder) is the clearest way to make a product match an external order. Positions become 0, 1, 2 and so on, and the first asset becomes the `main_image`.

```bash theme={null}
curl -X PUT https://wisepim.com/api/public/v1/products/8841/asset-order \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: order-8841-2026-11-19" \
  -H "Content-Type: application/json" \
  -d '{"asset_ids": ["9e7a0d55-31c4-4b6f-8f20-6a1b3c5d7e90", "4b1f6c2e-8d3a-4f0e-9a51-2c7d8e9f0a13", "c2d8f1a4-5b6e-4c7d-9e0f-1a2b3c4d5e6f"]}'
```

`asset_ids` must name **every** asset attached to the product **exactly once**, with at least 1 and at most 1,000 entries. A list that does not match is `422 invalid_order`, and the error lists `missing_asset_ids` and `unknown_asset_ids` so you can see what differs. Each of those lists shows at most 200 ids, so on a large product the difference may be partial. An empty list fails schema validation before that check, so a product with no images cannot be reordered. This route only orders; it does not attach or detach.

### Choose the main image

[`PUT /products/{product_id}/main-asset`](https://docs.wisepim.com/en/api-reference/assets/set-main) makes one image the main image. It moves to the front of the product's images.

```bash theme={null}
curl -X PUT https://wisepim.com/api/public/v1/products/8843/main-asset \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: main-8843-4b1f6c2e" \
  -H "Content-Type: application/json" \
  -d '{"asset_id": "4b1f6c2e-8d3a-4f0e-9a51-2c7d8e9f0a13"}'
```

The asset does not have to be attached to the product yet, so a variant can take one of its parent's photos in one call. Only images qualify: a PDF is `422 not_an_image`.

### Detach an image

[`DELETE /products/{product_id}/assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/detach) removes the asset from this product only. It returns `204` with no body. The asset stays in the library and on other products. The product's next image becomes its `main_image`, or it has none when no image is left. Detaching needs `assets:write`.

```bash theme={null}
curl -X DELETE https://wisepim.com/api/public/v1/products/8841/assets/c2d8f1a4-5b6e-4c7d-9e0f-1a2b3c4d5e6f \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: detach-8841-c2d8f1a4"
```

An asset that is not attached to the product is `404 not_found`.

### Positions

`position` is an integer from **0 to 1,000,000**. Lower comes first. A value outside that range is a `422` (`invalid_position` on an upload, a schema validation error on the JSON routes). Positions do not have to be consecutive; use the reorder route when you want them renumbered.

## Delete an asset

[`DELETE /assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/delete) removes the file from the media library **and from every product** it is attached to. Each of those products falls back to its next image as `main_image`, gets a new `version`, and channels stop receiving the image. It returns `204` and needs `assets:delete`.

```bash theme={null}
curl -X DELETE https://wisepim.com/api/public/v1/assets/c2d8f1a4-5b6e-4c7d-9e0f-1a2b3c4d5e6f \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: delete-asset-c2d8f1a4"
```

> [!WARNING]
>
> Delete is library-wide. To remove an image from one product, [detach](https://docs.wisepim.com/en/api-reference/assets/detach.md) it instead. Check `products` and `products_truncated` on the asset before you delete it.

## Read a product's gallery

Filter the library by product to get every image of that product:

```bash theme={null}
curl "https://wisepim.com/api/public/v1/assets?product_id=8841&limit=200" \
  -H "Authorization: Bearer $WISEPIM_API_KEY"
```

* The list is keyset-paged like every other list (`limit` up to 200, then `next_cursor`), ordered by asset id. It is **not** ordered by position.
* For each asset, the requested product's entry is always listed **first** in `products`, even when the asset is shared by more than 100 products. Read `products[0].position` and `products[0].is_main` and sort by position to rebuild the gallery.
* An unknown `product_id` returns an empty list, not a `404`.
* The product's own `main_image` is on [`GET /products/{product_id}`](https://docs.wisepim.com/en/api-reference/products/get).
* Images added before the media library existed can show on a product, and in its `main_image`, without being listed by `GET /assets`. You cannot reorder or detach them through these routes. Re-import them to manage them here.

## Recipe: migrate a product's images from your old PIM

This recipe moves the image gallery of each product, keeps the old order, and sets per-locale alt text. It is safe to run again after a failure.

**1. Create a key with the right scopes**

The migration needs `products:read` to resolve SKUs to product ids, `assets:read` to poll and verify, and `assets:write` to import and order. It does not need `assets:delete`.

**2. Resolve SKUs to product ids**

The import routes accept a `sku`, but reading a gallery and setting its order take a numeric `product_id`. Call [`GET /products?skus=TEE-ORG-NAVY-M,TEE-ORG-NAVY-L`](https://docs.wisepim.com/en/api-reference/products/list) (up to 200 SKUs per call) and keep each product's `id`. Each import receipt also carries the `product_id`.

**3. Check what the product already has**

Call [`GET /assets?product_id=`](https://docs.wisepim.com/en/api-reference/assets/list). If the product already shows images, decide whether to keep them. New imports without a `position` go after them. Images added before the media library existed are not listed here, even though the product may show them; compare with `main_image` on [`GET /products/{product_id}`](https://docs.wisepim.com/en/api-reference/products/get).

**4. Register one import per image, in the old order**

For each image, call [`POST /assets`](https://docs.wisepim.com/en/api-reference/assets/import-from-url) with the product's `sku`, the image URL and `position` set to its index in the old PIM (0 for the old main image). Use an `Idempotency-Key` derived from SKU and index, such as `img-TEE-ORG-NAVY-M-0`, so a rerun replays instead of registering twice.

If an image is behind a login on the old system, download it yourself and send it to [`POST /assets/upload`](https://docs.wisepim.com/en/api-reference/assets/upload) with the same `sku` and `position`.

**5. Wait for the imports to settle**

Poll [`GET /asset-imports?product_id=8841`](https://docs.wisepim.com/en/api-reference/assets/list-imports), or each receipt's [`GET /asset-imports/{import_id}`](https://docs.wisepim.com/en/api-reference/assets/get-import), with a backoff. Collect `asset_id` from every `linked` import and record every `failed` one with its `error`.

**6. Set alt text**

For each `asset_id`, call [`PATCH /assets/{asset_id}`](https://docs.wisepim.com/en/api-reference/assets/update) with the old PIM's alt text as a locale map.

**7. Verify and fix the order**

Read [`GET /assets?product_id=`](https://docs.wisepim.com/en/api-reference/assets/list) and sort by the product's `position`. If the order is not what you expect, for example because some images were already attached, send the complete order with [`PUT /products/{product_id}/asset-order`](https://docs.wisepim.com/en/api-reference/assets/reorder). The first asset in that list becomes the `main_image`.

**8. Retry the failures**

Fix the cause shown in `error` (a 404 on the old CDN, an HTML login page, a compressed response) and register those URLs again with new idempotency keys.

> [!TIP]
>
> Share one file across products by importing or uploading it once and then attaching the returned `asset_id` to the other products with [`POST /products/{product_id}/assets`](https://docs.wisepim.com/en/api-reference/assets/attach). Importing the same URL for each product also works, because a URL is stored once per project.

## Gotchas

* **Asset ids are UUIDs**, but URL import ids (`/asset-imports/{import_id}`) are integers.
* **A URL import returns a receipt, not an asset.** `asset_id` is only set once the import is `linked`.
* **`is_main` on a URL import shifts the product's other images** back by one, including imports that are still pending.
* **Retries replay the stored response.** A retry with the same `Idempotency-Key` returns the original response even if the product has changed or the URL's DNS has changed since.
* **Product writes cannot set images.** `main_image` and file or image attribute values are not writable on product writes. Use the media routes.
* **Older images can be invisible to these routes.** Images added before the media library existed may show on a product without being listed by `GET /assets`, so you cannot reorder or detach them here. Re-import them to manage them.
* **Request bodies are closed.** A field the route does not list, such as `alt_text` on `POST /assets` or `is_main` on the move route, is a `422`, not ignored.

## Common errors

| Status and code | Cause | What to do |
| - | - | - |
| `403 insufficient_scope` | The key lacks `assets:read`, `assets:write` or `assets:delete`. | Create a key with the scope the route needs. |
| `404 not_found` | Unknown or foreign product or asset id in the path, an unknown import id, or moving or detaching an asset that is not attached to the product. | Check the id belongs to this project. Foreign ids are always `404`, never `403`. |
| `413 payload_too_large` | The request body is over 10 MiB, multipart overhead included. This limit applies to every Public API write; the error's `max_bytes` gives it. | Make the file smaller, or import it from a URL (up to 25 MB). |
| `422` with `detail` | Schema validation failed: an unknown field, a `position` out of range on a JSON route, `asset_ids` that are not UUIDs, or an empty or over-long `asset_ids` list. | Read `detail` for the field and fix the request. |
| `422 invalid_url` | The URL is not a public `http(s)` address, contains credentials, or is not a valid web address. | Use a public address that WISEPIM can reach without logging in. |
| `422 invalid_reference` | The body names a product or asset outside this project, sends both or neither of `product_id` and `sku` on a URL import, or sends `position` or `is_main` on an upload without a product. | Send exactly one valid product reference and an asset from this project. |
| `422 invalid_order` | `asset_ids` does not name every attached asset exactly once. | Read `missing_asset_ids` and `unknown_asset_ids`, then send the full list. |
| `422 not_an_image` | A PDF was chosen as the main image. | Pick an image asset. |
| `422 invalid_position` | An upload `position` outside 0 to 1,000,000. | Send a position in range. |
| `422 invalid_alt_text` | Upload alt text over 500 characters. | Shorten it. |
| `422 unsupported_file_type`, `422 empty_file` | The uploaded content is not a supported image or PDF, or is empty. | Send a JPEG, PNG, GIF, WebP, AVIF, TIFF, BMP or PDF. |
| `422 invalid_filter` | `GET /asset-imports` with a `status` other than `pending`, `processing`, `linked` or `failed`. | Use one of the listed statuses. |
| `422 invalid_cursor`, `422 invalid_limit` | A malformed `cursor`, or a `limit` below 1, on `GET /assets` or `GET /asset-imports`. | Pass `next_cursor` back unchanged and a `limit` from 1 to 200. |
| `422 asset_operation_rejected` | The media operation refused the change. | Read `error` for the reason and correct the request. |
| `409 idempotency_conflict` | An `Idempotency-Key` was reused for a different request. | Use a new key for each logical write. |
| `429 rate_limited` | The key went over its per-minute rate limit. | Wait for `Retry-After` seconds, then retry. |
| `500 native_operation_failed` | The underlying media operation failed on the server. | Retry with the same `Idempotency-Key`. |
| `503 storage_unavailable` | The file could not be stored. | Retry the upload with the same `Idempotency-Key`. |

A URL import that fails after the `202` does not return an error status. Its receipt has `status: "failed"` and an `error` text.

## Related

> [card] [Products and variants](https://docs.wisepim.com/en/api-reference/products-and-variants.md)
>
> Create products and variants before attaching their images.

> [card] [Imports and exports](https://docs.wisepim.com/en/api-reference/imports-and-exports.md)
>
> Move whole catalogs as files, including image columns.

> [card] [Webhooks](https://docs.wisepim.com/en/api-reference/webhooks.md)
>
> Get notified when products change instead of polling.

> [card] [Authentication and scopes](https://docs.wisepim.com/en/api-reference/authentication.md)
>
> Which scopes exist and how to create a key that carries them.


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