Queek docs
Merchant endpoint reference

Files

GET
/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
X-Client-Key<token>

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

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

Header Parameters

X-Client-Key*string

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.

X-Request-Id?string

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"}
POST
/files

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
X-Client-Key<token>

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

X-Client-Key*string

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.

X-Request-Id?string

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.

Idempotency-Key?string

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  }}
PATCH
/files/{file}

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
X-Client-Key<token>

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

file*string

Identifier of the image, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

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.

X-Request-Id?string

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.

Idempotency-Key?string

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  }}
DELETE
/files/{file}

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
X-Client-Key<token>

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

file*string

Identifier of the image, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

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.

X-Request-Id?string

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.

Idempotency-Key?string

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  }}
GET
/files/{file}/references

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
X-Client-Key<token>

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

file*string

Identifier of the image, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

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.

X-Request-Id?string

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"      }    ]  }}