Photo downloads
Photos added by URL are downloaded in the background; a download shows its status and the reason of a failure.
Photo downloads
Objects
MediaImport
idintegerrequiredID of the record, unique among records of its kind in the store.
app_idintegerrequiredID of the app that asked for the download.
product_idintegerrequiredID of the product the photo goes to.
urlstringrequiredAddress the photo is downloaded from.
positioninteger or nullrequiredPlace in the gallery, starting from zero; null — at the end.
is_primarybooleanrequiredThe photo becomes the main one.
statusstringrequiredpending — waiting or downloading; succeeded — the photo is in the gallery (media_id); failed — the photo was not added (error).
- Values:
pendingsucceededfailed
media_idinteger or nullrequiredThe photo in the gallery, the id in media of the product; set when status is succeeded.
errorobject or nullrequiredWhy the photo was not added; set when status is failed.
Fields · 3
codestringrequiredinvalid_url — not an http or https address; blocked_address — the address leads to a private network; unreachable — the server did not respond; too_large — the file is larger than allowed; access_denied, not_found, rate_limited, http_error — the server responded with an error (source_status); not_an_image — the file is not an image; image_dimensions_exceeded — the image has too many pixels; media_quota_exceeded — the media storage of the store is full; product_deleted — the product was archived before the photo arrived; processing_failed — the image could not be processed.
- Values:
invalid_urlblocked_addressunreachabletoo_largeaccess_deniednot_foundrate_limitedhttp_errornot_an_imageimage_dimensions_exceededmedia_quota_exceededproduct_deletedprocessing_failed
messagestringrequiredThe reason in words, in the language of the request.
source_statusinteger or nullrequiredHTTP status the server of the photo responded with, for access_denied, not_found, rate_limited and http_error; otherwise null.
attemptsintegerrequiredHow many times the download was taken up: network and source failures are retried.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
finished_atstring (date-time) or nullrequiredWhen the download finished; null while pending.
Endpoints
List photo downloads by URL changed since a given time: pending, downloaded or failed
get/media-imports
Scope: catalog:write
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
product_idintegerOnly records of this product.
- Minimum:
- 1
statusstringOnly downloads in this status.
- Values:
pendingsucceededfailed
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/media-imports" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"app_id": 0,
"product_id": 0,
"url": "string",
"position": 0,
"is_primary": true,
"status": "pending",
"media_id": 0,
"error": {
"code": "invalid_url",
"message": "string",
"source_status": 0
},
"attempts": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"finished_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Get a photo download by URL
get/media-imports/{import}
Scope: catalog:write
Parameters
Path
importintegerrequiredID of the photo download.
Responses
200Success
application/json
Returns MediaImport
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/media-imports/{import}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"app_id": 0,
"product_id": 0,
"url": "string",
"position": 0,
"is_primary": true,
"status": "pending",
"media_id": 0,
"error": {
"code": "invalid_url",
"message": "string",
"source_status": 0
},
"attempts": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z",
"finished_at": "2026-01-15T12:00:00Z"
}