Media API

REST API endpoints for managing the store's media library.

The media library is the store's catalog of uploaded images, video, and documents. Add files by uploading them directly or by pointing at remote URLs (re-hosted on the store CDN), then attach them to products, variants, or collections.

List Media

GET /api/v1/media

Returns a paginated list of the store's media, newest first. Filter by kind and search filename or alt text with query.

Query Parameters

curl -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/media?kind=image&limit=24"

Response

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "url": "https://cdn.example.com/images/store/live/hero-a1b2.jpg",
      "pathname": "images/store/live/hero-a1b2.jpg",
      "filename": "hero.jpg",
      "kind": "image",
      "mimeType": "image/jpeg",
      "width": 1600,
      "height": 900,
      "sizeBytes": 248213,
      "source": "upload",
      "alt": "Storefront hero banner",
      "createdAt": "2024-06-15T10:30:00.000Z",
      "updatedAt": "2024-06-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "limit": 24,
    "offset": 0
  }
}

Create Media

POST /api/v1/media

Adds media to the library in one of two modes, chosen by the request Content-Type.

File upload (multipart/form-data) – upload file(s) under the file field; repeat the field for multiple files. Maximum 10 files, 25 MB each.

Remote URLs (application/json) – pass { "urls": [...] } (up to 10) to download public files and re-host them on the store CDN. Accepted: images (max 25 MB), videos such as MP4, WebM and MOV (max 100 MB) and PDFs (max 100 MB). Use this to move a file you can link to but not upload, for example one served from your storefront's own site.

The file type comes from the response Content-Type. When the server sends a generic one (application/octet-stream), the type is detected from the file itself. Other types (HTML, archives, audio) are refused. Only public http(s) addresses are fetched; private and internal hosts are blocked.

Both modes catalog the result and return the created rows under media.

JPEG, PNG, WebP and AVIF images whose longest side exceeds 2048 px are scaled down to fit 2048 px, in their own format. The stored file, its sizeBytes and its recorded width and height describe the scaled copy. Smaller images, animations and other file types are stored unchanged.

Request Body (JSON mode)

# File upload
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -F "file=@hero.jpg" \
  -F "file=@thumbnail.png" \
  https://your-store.yns.store/api/v1/media

# Remote URLs
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/photo.jpg", "https://example.com/size-guide.pdf"]}' \
  https://your-store.yns.store/api/v1/media

Response (201)

{
  "media": [
    {
      "id": "0191abc0-1234-7def-8000-000000000002",
      "url": "https://cdn.example.com/images/store/live/photo-c3d4.jpg",
      "pathname": "images/store/live/photo-c3d4.jpg",
      "filename": "photo.jpg",
      "kind": "image",
      "mimeType": "image/jpeg",
      "width": 1200,
      "height": 800,
      "sizeBytes": 184022,
      "source": "external",
      "alt": null,
      "createdAt": "2024-06-15T10:31:00.000Z",
      "updatedAt": "2024-06-15T10:31:00.000Z"
    }
  ]
}

URL Import Errors (400)

URLs are processed in order and the request stops at the first one that fails. The response names the reason and lists the files already added, so you can retry from the failed URL:

{
  "error": "File at https://example.com/promo.mp4 exceeds maximum size of 100 MB",
  "media": [
    {
      "id": "0191abc0-1234-7def-8000-000000000003",
      "url": "https://cdn.example.com/images/store/live/size-guide-e5f6.pdf",
      "kind": "document",
      "mimeType": "application/pdf"
    }
  ]
}

Get Media

GET /api/v1/media/:id

Returns a single media item by ID. Returns 404 if it does not exist in this store.

curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/media/0191abc0-1234-7def-8000-000000000001

Update Media

PATCH /api/v1/media/:id

Updates editable metadata. Send at least one field – an empty body returns 400.

Request Body

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"alt": "Storefront hero banner"}' \
  https://your-store.yns.store/api/v1/media/0191abc0-1234-7def-8000-000000000001

Response (200)

Returns the updated media item.

Delete Media

DELETE /api/v1/media/:id

Removes the media row and best-effort deletes the underlying blob. If the asset is still attached to one or more products, variants, or collections, the request returns 409 with the list of usedBy entities. Pass ?force=true to delete anyway – the URL is stripped from every entity that references it.

Query Parameters

curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/media/0191abc0-1234-7def-8000-000000000001?force=true"

Response (204)

Empty body on success.

In Use (409)

{
  "error": "Media is attached to one or more items. Detach it first or pass ?force=true.",
  "usedBy": [
    {
      "entityType": "product",
      "entityId": "0191abc0-0000-7000-8000-000000000100",
      "role": "gallery"
    }
  ]
}