How media is modelled
An asset response describes the file and where it is used:
urlis 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_urlis the same token with?rendition=thumbnail. source_urlis set when the asset was imported from a URL.productslists at most 100 products, ordered by position.products_truncatedistruewhen the asset may be attached to more products than are listed.
main_image is read-only on product writes. Sending it to POST /products, PATCH /products/{product_id} or POST /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 needsassets: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.
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 The response is
product_id or sku. Send exactly one of them.202 Accepted with an import receipt, not an asset. Nothing has been downloaded yet.2
Poll until it settles
Call When
GET /asset-imports/{import_id} until status is linked or failed. The status moves through pending, processing, then linked or failed.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}. See Alt text.Rules for the download
The download runs behind the same safety guard as every WISEPIM image import:- Only
httpandhttpsaddresses 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 with422 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-Encodingother thanidentity(for examplegzip), the import fails. Serve images without transfer compression.
Placement and repeats
positionplaces 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: trueputs the image first, so it becomes themain_imageonce it lands. It takes precedence overposition, 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.GET /asset-importslists them, including imports started by connectors and the web app.
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 takes multipart/form-data and stores the file in the same request.
- The file’s content decides its type, not its name or the declared
Content-Type. A renamed text file is refused with422 unsupported_file_type. An empty file is422 empty_file. - The whole request body is limited to 10 MiB. A larger request is refused with
413 payload_too_largebefore 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
200instead of201, 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 is409 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 withPATCH /assets/{asset_id}, either as one text for every language:
- Each text is at most 500 characters, and a map holds at most 100 locales. Locale keys look like
en,nl-NLorpt_BR. - Send
nullor 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 itsmain_image:
Attach an existing asset
POST /products/{product_id}/assets 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.
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} changes one image’s position. Two images on the same position keep the order they were attached in.
Set the full order
PUT /products/{product_id}/asset-order 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.
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 makes one image the main image. It moves to the front of the product’s images.
422 not_an_image.
Detach an image
DELETE /products/{product_id}/assets/{asset_id} 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.
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} 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.
Read a product’s gallery
Filter the library by product to get every image of that product:- The list is keyset-paged like every other list (
limitup to 200, thennext_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. Readproducts[0].positionandproducts[0].is_mainand sort by position to rebuild the gallery. - An unknown
product_idreturns an empty list, not a404. - The product’s own
main_imageis onGET /products/{product_id}. - Images added before the media library existed can show on a product, and in its
main_image, without being listed byGET /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 (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=. 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}.4
Register one import per image, in the old order
For each image, call
POST /assets 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 with the same sku and position.5
Wait for the imports to settle
Poll
GET /asset-imports?product_id=8841, or each receipt’s GET /asset-imports/{import_id}, 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} with the old PIM’s alt text as a locale map.7
Verify and fix the order
Read
GET /assets?product_id= 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. 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.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_idis only set once the import islinked. is_mainon 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-Keyreturns the original response even if the product has changed or the URL’s DNS has changed since. - Product writes cannot set images.
main_imageand 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_textonPOST /assetsoris_mainon the move route, is a422, not ignored.
Common errors
A URL import that fails after the
202 does not return an error status. Its receipt has status: "failed" and an error text.
Related
Products and variants
Create products and variants before attaching their images.
Imports and exports
Move whole catalogs as files, including image columns.
Webhooks
Get notified when products change instead of polling.
Authentication and scopes
Which scopes exist and how to create a key that carries them.

