Files
Requires scope merchant-media-read.
Lists original images uploaded by this app installation, newest first, with cursor pagination (limit + starting_after). Each image has the same id, url and variants shape as product images. Only this installation’s uploads are visible.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/files?limit=10" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": 88214, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "alt": "Smokehouse party pack in a foil tray", "thumbnail_url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "w": 1200, "h": 1200 } }, "mime_type": "image/jpeg", "size": 0, "width": 1200, "height": 1200, "created_at": null } ], "has_more": true, "next_cursor": "eyJpZCI6ODgyMTQsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}Requires scope merchant-media-create.
Uploads one JPEG, PNG or WebP image as multipart/form-data using the file field. The image is added to the store media library and belongs to this app installation. Reuse its id with media_id on products/{product}/images. A same-byte retry without an Idempotency-Key returns the existing image.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
multipart/form-data
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/files" \ -H "X-Client-Key: {{merchantKey}}" \ -F file="(binary image)"{ "data": { "id": 88214, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "alt": "Smokehouse party pack in a foil tray", "thumbnail_url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "w": 1200, "h": 1200 } }, "mime_type": "image/jpeg", "size": 0, "width": 1200, "height": 1200, "created_at": null }}Requires scope merchant-media-update.
Sets or clears the alt text of one image this app installation uploaded; alt must be sent (null or blank clears it, 250 characters at most). The new text shows wherever the store uses the image, products included. {file} is the image id; an image the merchant uploaded, another installation uploaded or that does not exist answers 404. Only alt text can be changed: to replace the picture, upload a new image.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the image, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
PATCH files/{file}: the alt text of one file the calling installation
uploaded. alt must be sent so an omitted field never clears it by
accident; null or blank clears it on purpose. 250 matches the cap the
dashboard file manager and the caption derivation use.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/files/88214" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "alt": "Smokehouse party pack in a foil tray" }'{ "status": "success", "message": "File updated.", "data": { "id": 88214, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "alt": "Smokehouse party pack in a foil tray", "thumbnail_url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "w": 1200, "h": 1200 } }, "mime_type": "image/jpeg", "size": 0, "width": 1200, "height": 1200, "created_at": null }}Requires scope merchant-media-delete.
Permanently deletes one image this app installation uploaded, with its generated sizes, and frees its place in the installation’s file and storage limits. An image that is still used in the store is never deleted: the answer is a 409 conflict listing the places that use it (the same list as files/{file}/references), and nothing changes. Remove the image from those places, then delete it again. An app can delete only its own uploads; an image the merchant uploaded, another installation uploaded or that does not exist answers 404, and a repeated delete of a deleted image answers 404. Importing an image from a web address is not available.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the image, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/files/88214" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "File deleted.", "data": { "id": 88214, "deleted": true }}Requires scope merchant-media-read.
Lists where one image this app installation uploaded is still used in the store: products (as the primary image, a gallery image, the video or poster, or a variant image), the store logo or banner, and metafield values that point at it. Each place has a type, via, and for a product its id and slug, for a metafield its namespace.key as slug. count is the total; at most 50 places are listed. Images placed on a storefront page or in a theme setting by address rather than by id are not tracked here. {file} is the image id; an image that is not this installation’s answers 404.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the image, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/files/88214/references" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "File references.", "data": { "id": 88214, "count": 2, "references": [ { "type": "product", "id": 20417, "slug": "smokehouse-party-pack", "via": "primary" }, { "type": "store", "id": null, "slug": null, "via": "logo" } ] }}