Files

Get file limits

GET read_files or read_site_assets

Read supported formats and request limits.

Returns the current format, size, image pixel-count, text-length and batch limits. Upload batches use max_files_per_upload; lookups use bulk_lookup_max; deletions use bulk_delete_max. Configure list and picker pagination from their respective page-size values. Sample values are illustrative; fetch this endpoint for the current limits. Size limits ending in _mb use 1,048,576 bytes per unit. model_viewer_url identifies the hosted 3D viewer.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl 'https://api-store.tringify.com/api/2025-01/files/limits' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/files/limits", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/files/limits",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "max_image_size_mb": 10,
    "max_video_size_mb": 100,
    "max_doc_size_mb": 50,
    "max_3d_size_mb": 100,
    "max_image_megapixels": 20,
    "allowed_image_types": [
      "image/jpeg",
      "image/png",
      "image/gif",
      "image/webp"
    ],
    "allowed_video_types": [
      "video/mp4"
    ],
    "allowed_doc_types": [
      "application/pdf"
    ],
    "allowed_3d_types": [
      "model/gltf-binary",
      "model/vnd.usdz+zip"
    ],
    "allowed_image_extensions": [
      "jpg",
      "jpeg",
      "png",
      "gif",
      "webp"
    ],
    "allowed_video_extensions": [
      "mp4"
    ],
    "allowed_doc_extensions": [
      "pdf"
    ],
    "allowed_3d_extensions": [
      "glb",
      "usdz"
    ],
    "list_page_size": 50,
    "list_max_limit": 200,
    "search_max_length": 200,
    "page_size_options": [
      20,
      50,
      100,
      200
    ],
    "picker_page_size_options": [
      20,
      50,
      100,
      200
    ],
    "model_viewer_url": "https://assets.tringify.com/model-viewer",
    "filename_max_length": 255,
    "alt_text_max_length": 500,
    "file_types": [
      "upload",
      "site_asset"
    ],
    "media_types": [
      "image",
      "video",
      "document",
      "3d"
    ],
    "max_files_per_upload": 100,
    "bulk_lookup_max": 200,
    "bulk_delete_max": 200
  }
}

Get storage usage

GET read_files or read_site_assets

Read the store's used storage, file count and allowances.

Media and Site Assets share this allowance. used_bytes reports counted file storage and excludes space reserved for uploads still in progress. quota_bytes - used_bytes is therefore not guaranteed upload capacity. Creating upload intents checks committed and reserved usage together. The _gb fields use 1,073,741,824 bytes per unit. used_files counts Media and Site Assets files together, one per file whatever its size; file_limit is the plan's maximum. Uploads still in progress also hold a file slot, so file_limit - used_files is not guaranteed upload capacity either. An upload that would pass the file limit fails with STORAGE_FILE_LIMIT_REACHED.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl 'https://api-store.tringify.com/api/2025-01/files/quota' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/files/quota", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/files/quota",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "used_bytes": 524288000,
    "quota_bytes": 5368709120,
    "used_gb": 0.48828125,
    "quota_gb": 5,
    "used_files": 1240,
    "file_limit": 100000
  }
}

List files

GET read_files or read_site_assets (depends on file type)

List files in one library.

Defaults to Media (type=upload); use type=site_asset for Site Assets. Results are ordered by upload time, newest first, with an ID tie-breaker. media filters the media type and search matches original_filename case-insensitively. Pass returned cursors unchanged and keep the same library, media filter and search. Reset the cursor when changing those filters. total is counted when the cursor walk begins and is carried through later pages; it is not a live count or a snapshot of the library. An omitted limit uses list_page_size; an invalid or oversized limit is rejected.

Query parameters

Name	Type	Description
`type`	`string`	File namespace. Omit or use `upload` for Media-library files; use `site_asset` for storefront assets. Example: `upload`
`media`	`string`	Filter by media type: `image`, `video`, `document`, or `3d`.
`search`	`string`	Free-text filename match (case-insensitive substring).
`sort`	`string`	Order: `newest` (default), `oldest`, `name_asc`, `name_desc`, `size_desc` (largest first), or `size_asc`. Example: `newest`
`cursor`	`string`	Opaque cursor returned by the previous response. Keep the same namespace, media filter, search, and sort while using it.
`limit`	`integer`	Page size, 1-200 (default 50). Example: `20`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORAGE_INVALID_FILE_TYPE
type must be upload or site_asset.
400 STORAGE_MEDIA_TYPE_INVALID
media must be image, video, document, or 3d.
400 STORAGE_INVALID_REQUEST
The cursor or filters are invalid, search is too long, or limit is outside 1 through list_max_limit.

curl 'https://api-store.tringify.com/api/2025-01/files?limit=20&sort=newest&type=upload' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/files?limit=20&sort=newest&type=upload", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/files?limit=20&sort=newest&type=upload",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "files": [
      {
        "id": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
        "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
        "type": "upload",
        "media_type": "image",
        "filename": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg",
        "original_filename": "outdoor-photo.jpg",
        "alt_text": "Red hiking backpack on a rock",
        "size_bytes": 482133,
        "mime_type": "image/jpeg",
        "url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
        "cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg",
        "display_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
        "preview_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
        "download_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
        "width": 2400,
        "height": 1600,
        "has_original": false,
        "revision": 1,
        "preview_status": "none",
        "preview_revision": 0,
        "created_at": "2026-06-09T12:00:00Z",
        "cache_version": "1"
      },
      {
        "id": "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10",
        "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
        "type": "upload",
        "media_type": "video",
        "filename": "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4",
        "original_filename": "product-spin.mp4",
        "alt_text": "Product rotating on a turntable",
        "size_bytes": 4821330,
        "mime_type": "video/mp4",
        "url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4",
        "cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4",
        "display_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4?v=1",
        "preview_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4?v=1",
        "download_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4?v=1",
        "width": 1920,
        "height": 1080,
        "has_original": false,
        "revision": 1,
        "preview_status": "pending",
        "preview_revision": 0,
        "preview_requested_at": "2026-06-09T12:00:01Z",
        "created_at": "2026-06-09T12:00:00Z",
        "cache_version": "1"
      }
    ],
    "limit": 20,
    "total": 42,
    "has_next": true,
    "has_previous": false,
    "next_cursor": "eyJ2IjoxLCJyZXNvdXJjZSI6ImZpbGU6dXBsb2FkIn0"
  }
}

Create upload intents

POST write_files or write_site_assets (depends on file type)

Reserve storage and obtain signed upload requests.

Creates one intent for each item, in request order. Upload each original file body with HTTPS PUT to its returned url, including every returned signed header unchanged. Do not send the Store API bearer token to that URL. The declared byte size must match the uploaded body. A new create request creates new intents; keep their IDs to recover interrupted uploads. After validation, video and 3D preview work starts automatically for Store API uploads. Preview completion is separate from the original becoming ready.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`file_type`	`string`	Defaults to `upload` for Media. Use `site_asset` for Site Assets. The selected library determines the write scope. Example: `upload`
`items` required	`array<object>`	Files to reserve. Each item requires `original_filename`, `mime_type`, and exact `size_bytes`; `alt_text` is optional. Example: `[{"original_filename":"outdoor-photo.jpg","mime_type":"image/jpeg","size_bytes":482133,"alt_text":"Red hiking backpack on a rock"}]`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORAGE_INVALID_REQUEST
The request body or one of its file declarations is invalid.
400 STORAGE_INVALID_FILE_TYPE
file_type must be upload or site_asset.
400 STORAGE_MAX_FILES_PER_UPLOAD
The batch exceeds the maximum files per upload.
400 STORAGE_FILE_TYPE_NOT_ALLOWED
A filename or declared MIME type is not in the allowed formats returned by files.limits.
400 STORAGE_FILE_TOO_LARGE
A file exceeds its media-type size cap. See files.limits for the per-type cap.
400 STORAGE_ALT_TEXT_TOO_LONG
An item's alt_text exceeds the maximum returned by files.limits.
400 STORAGE_QUOTA_EXCEEDED
The store's storage quota would be exceeded. Free up space or upload fewer files.
400 STORAGE_FILE_LIMIT_REACHED
The batch would pass the plan's media file limit. Delete files or upload fewer; see files.quota for used_files and file_limit.

curl -X POST 'https://api-store.tringify.com/api/2025-01/files/upload-intents' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "file_type": "upload",
  "items": [
    {
      "alt_text": "Red hiking backpack on a rock",
      "mime_type": "image/jpeg",
      "original_filename": "outdoor-photo.jpg",
      "size_bytes": 482133
    }
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/files/upload-intents", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "file_type": "upload",
    "items": [
      {
        "alt_text": "Red hiking backpack on a rock",
        "mime_type": "image/jpeg",
        "original_filename": "outdoor-photo.jpg",
        "size_bytes": 482133
      }
    ]
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/files/upload-intents",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "file_type": "upload",
        "items": [{
            "alt_text": "Red hiking backpack on a rock",
            "mime_type": "image/jpeg",
            "original_filename": "outdoor-photo.jpg",
            "size_bytes": 482133,
        }],
    },
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "intents": [
      {
        "intent_id": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
        "filename": "outdoor-photo.jpg",
        "status": "pending",
        "url": "https://upload.example.com/signed-request",
        "headers": {
          "Content-Type": "image/jpeg"
        },
        "expires_in": 300
      }
    ]
  }
}

Finalize uploads

POST write_files or write_site_assets (depends on file type)

Check uploaded files and begin validation.

Call after each signed PUT attempt has finished, including an attempt whose response was lost. Send at most max_files_per_upload intent IDs. The library and creating identity must match: app uploads belong to the app installation, and other uploads to their creating user. Finalize returns per-intent results; processing means validation is still running and only ready makes the file available. A missing uploaded body can be rejected. HTTP 200 does not mean every file was accepted: inspect each intent's status and optional error.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`file_type`	`string`	Use the library selected at creation. Omission defaults to `upload`; Site Assets intents require `site_asset`. Example: `upload`
`intent_ids` required	`array<string>`	Intent ids returned by the create call. Example: `["8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201"]`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORAGE_INVALID_REQUEST
The request body or intent list is invalid.
400 STORAGE_INVALID_FILE_TYPE
file_type must match the intent namespace.
404 STORAGE_FILE_NOT_FOUND
An intent is unavailable in this store or belongs to a different creating identity.

curl -X POST 'https://api-store.tringify.com/api/2025-01/files/upload-intents/finalize' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "file_type": "upload",
  "intent_ids": [
    "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201"
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/files/upload-intents/finalize", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "file_type": "upload",
    "intent_ids": [
      "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201"
    ]
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/files/upload-intents/finalize",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "file_type": "upload",
        "intent_ids": ["8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201"],
    },
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "intents": [
      {
        "intent_id": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
        "filename": "outdoor-photo.jpg",
        "status": "processing"
      }
    ]
  }
}

Get upload status

POST write_files or write_site_assets (depends on file type)

Read the result of each upload intent.

Send at most max_files_per_upload intent IDs with the same library and creating identity. Each result is pending, processing, ready, rejected or expired. A ready result contains file. A rejected or expired result contains error, including its code and message, within the successful response envelope. Validation codes can include STORAGE_CONTENT_TYPE_MISMATCH, STORAGE_IMAGE_MEGAPIXELS_TOO_BIG and STORAGE_MALWARE_REJECTED. Inspect every result and stop polling terminal intents. Retain IDs while recovering an interrupted upload.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`file_type`	`string`	Use the library selected at creation. Omission defaults to `upload`; Site Assets intents require `site_asset`. Example: `upload`
`intent_ids` required	`array<string>`	Intent ids to inspect. Example: `["8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201"]`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORAGE_INVALID_REQUEST
The request body or intent list is invalid.
400 STORAGE_INVALID_FILE_TYPE
file_type must match the intent namespace.
404 STORAGE_FILE_NOT_FOUND
An intent is unavailable in this store or belongs to a different creating identity.

curl -X POST 'https://api-store.tringify.com/api/2025-01/files/upload-intents/status' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "file_type": "upload",
  "intent_ids": [
    "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201"
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/files/upload-intents/status", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "file_type": "upload",
    "intent_ids": [
      "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201"
    ]
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/files/upload-intents/status",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "file_type": "upload",
        "intent_ids": ["8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201"],
    },
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "intents": [
      {
        "intent_id": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
        "filename": "outdoor-photo.jpg",
        "status": "ready",
        "file": {
          "id": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
          "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
          "type": "upload",
          "media_type": "image",
          "filename": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg",
          "original_filename": "outdoor-photo.jpg",
          "size_bytes": 482133,
          "mime_type": "image/jpeg",
          "width": 2400,
          "height": 1600,
          "url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
          "cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg",
          "display_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
          "preview_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
          "download_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
          "has_original": false,
          "revision": 1,
          "preview_status": "none",
          "preview_revision": 0,
          "created_at": "2026-06-09T12:00:00Z",
          "cache_version": "1"
        }
      }
    ]
  }
}

Get multiple files

POST read_files and/or read_site_assets (depends on selected file types)

Read metadata for a set of file IDs.

Every requested ID must belong to the store and be readable under the token's library scopes. An unavailable or unreadable file fails the lookup; this endpoint does not return a partial authorized subset or per-file errors. Match results by id rather than depending on their order. Reading both libraries requires both read scopes.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`file_ids` required	`array<string>`	File IDs to look up, up to `bulk_lookup_max` from `GET /files/limits`. Every ID must belong to this store and be readable by the token. Example: `["8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201", "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10"]`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORAGE_INVALID_REQUEST
The request body is malformed.
400 STORAGE_FILE_IDS_REQUIRED
The body must include a non-empty file_ids array.
400 STORAGE_BULK_LOOKUP_MAX_EXCEEDED
The batch exceeds the maximum files per lookup.
404 STORAGE_FILE_NOT_FOUND
One or more selected files are unavailable in this store or outside the permitted libraries.

curl -X POST 'https://api-store.tringify.com/api/2025-01/files/bulk-info' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "file_ids": [
    "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
    "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10"
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/files/bulk-info", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "file_ids": [
      "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
      "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10"
    ]
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/files/bulk-info",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "file_ids": ["8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201", "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10"],
    },
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "files": [
      {
        "alt_text": "Red hiking backpack on a rock",
        "cache_version": "1",
        "cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg",
        "created_at": "2026-06-09T12:00:00Z",
        "display_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
        "download_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
        "filename": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg",
        "has_original": false,
        "height": 1600,
        "id": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
        "media_type": "image",
        "mime_type": "image/jpeg",
        "original_filename": "outdoor-photo.jpg",
        "preview_revision": 0,
        "preview_status": "none",
        "preview_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
        "revision": 1,
        "size_bytes": 482133,
        "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
        "type": "upload",
        "url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
        "width": 2400
      },
      {
        "alt_text": "Product rotating on a turntable",
        "cache_version": "1",
        "cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4",
        "created_at": "2026-06-09T12:00:00Z",
        "display_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4?v=1",
        "download_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4?v=1",
        "filename": "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4",
        "has_original": false,
        "height": 1080,
        "id": "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10",
        "media_type": "video",
        "mime_type": "video/mp4",
        "original_filename": "product-spin.mp4",
        "preview_requested_at": "2026-06-09T12:00:01Z",
        "preview_revision": 0,
        "preview_status": "pending",
        "preview_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4?v=1",
        "revision": 1,
        "size_bytes": 4821330,
        "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
        "type": "upload",
        "url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4",
        "width": 1920
      }
    ]
  },
  "success": true
}

Get a file

GET read_files or read_site_assets (depends on file type)

Read one file and its delivery URLs.

Returns file metadata, preview state and delivery URLs. original_filename is the editable display name; filename is the file name assigned when the file was created. Use display_url for the current source, download_url for download and thumbnail_display_url for a generated thumbnail when present. preview_url falls back to the source URL when no current thumbnail is available, so it is not always an image. An ordinary image can have preview_status=none and still display normally. revision identifies the source revision; preview_revision identifies the source used by the thumbnail. has_original indicates a retained earlier source, not whether the current original exists. Optional fields are omitted when absent. Delivery URLs are opaque: use them as returned.

Path parameters

Name	Type	Description
`id` required	`uuid`	File id. Example: `8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
404 STORAGE_FILE_NOT_FOUND
The file is unavailable in this store or is outside the permitted library.

curl 'https://api-store.tringify.com/api/2025-01/files/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/files/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/files/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "id": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
    "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
    "type": "upload",
    "media_type": "image",
    "filename": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg",
    "original_filename": "outdoor-photo.jpg",
    "alt_text": "Red hiking backpack on a rock",
    "size_bytes": 482133,
    "mime_type": "image/jpeg",
    "url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
    "cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg",
    "display_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
    "preview_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
    "download_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
    "width": 2400,
    "height": 1600,
    "has_original": false,
    "revision": 1,
    "preview_status": "none",
    "preview_revision": 0,
    "created_at": "2026-06-09T12:00:00Z",
    "cache_version": "1"
  }
}

Request a preview

POST write_files or write_site_assets (depends on file type)

Request the thumbnail for a video or 3D model.

Starts preview generation for the current source revision, or requests it again after failure. Repeating a request for an already pending or available current preview does not create another job. The response describes the current file state; it does not guarantee that preview generation has finished. Read the file to observe preview_status, and use thumbnail_display_url when present. A failed preview leaves the validated original available.

Path parameters

Name	Type	Description
`id` required	`uuid`	Video or 3D file id. Example: `9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORAGE_MEDIA_TYPE_INVALID
The file is not an MP4 video, GLB model, or USDZ model.
404 STORAGE_FILE_NOT_FOUND
The file is unavailable in this store or is outside the permitted library.

curl -X POST 'https://api-store.tringify.com/api/2025-01/files/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10/preview' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/files/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10/preview", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/files/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10/preview",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "id": "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10",
    "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
    "type": "upload",
    "media_type": "video",
    "filename": "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4",
    "original_filename": "product-spin.mp4",
    "alt_text": "Product rotating on a turntable",
    "size_bytes": 4821330,
    "mime_type": "video/mp4",
    "url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4",
    "cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4",
    "display_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4?v=1",
    "preview_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4?v=1",
    "download_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10.mp4?v=1",
    "width": 1920,
    "height": 1080,
    "has_original": false,
    "revision": 1,
    "preview_status": "pending",
    "preview_revision": 0,
    "preview_requested_at": "2026-06-09T12:00:01Z",
    "created_at": "2026-06-09T12:00:00Z",
    "cache_version": "1"
  }
}

Update file metadata

PUT write_files or write_site_assets (depends on file type)

Change the display filename or alt text.

Updates only supplied fields; omitted fields are unchanged. original_filename and alt_text are trimmed and validated against the limits response. Use an empty alt_text to clear it; a blank filename is rejected. This endpoint does not replace file contents, change the library, convert the format or change existing file references. Renaming leaves delivery URLs unchanged. The consuming theme or content determines how alt text is rendered.

Path parameters

Name	Type	Description
`id` required	`uuid`	File id. Example: `8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`original_filename`	`string`	New filename. Empty string is rejected. Example: `outdoor-photo.jpg`
`alt_text`	`string`	A text alternative for the image. Use an empty string to clear it. Example: `Red hiking backpack on a rock`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORAGE_INVALID_REQUEST
The request body is malformed.
400 STORAGE_FILENAME_REQUIRED
original_filename was provided as an empty string.
400 STORAGE_FILENAME_TOO_LONG
original_filename exceeds the max length.
400 STORAGE_ALT_TEXT_TOO_LONG
alt_text exceeds the max length.
404 STORAGE_FILE_NOT_FOUND
The file is unavailable in this store or is outside the permitted library.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/files/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "alt_text": "Red hiking backpack on a rock",
  "original_filename": "outdoor-photo.jpg"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/files/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "alt_text": "Red hiking backpack on a rock",
    "original_filename": "outdoor-photo.jpg"
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/files/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "alt_text": "Red hiking backpack on a rock",
        "original_filename": "outdoor-photo.jpg",
    },
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "id": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
    "store_id": "74e634ea-84ec-43b8-b66b-986214c2c5a3",
    "type": "upload",
    "media_type": "image",
    "filename": "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg",
    "original_filename": "outdoor-photo.jpg",
    "alt_text": "Red hiking backpack on a rock",
    "size_bytes": 482133,
    "mime_type": "image/jpeg",
    "url": "https://store.example.com/uploads/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
    "cdn_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg",
    "display_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
    "preview_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
    "download_url": "https://assets.tringify.com/74e634ea-84ec-43b8-b66b-986214c2c5a3/upload/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201.jpg?v=1",
    "width": 2400,
    "height": 1600,
    "has_original": false,
    "revision": 1,
    "preview_status": "none",
    "preview_revision": 0,
    "created_at": "2026-06-09T12:00:00Z",
    "cache_version": "1"
  }
}

Delete a file

DELETE write_files or write_site_assets (depends on file type)

Delete a file and clear its removable references.

A file with no tracked uses is deleted without an impact-confirmation round trip. Optional catalog images, product gallery entries, blog featured images and author avatars, supported file metafields and Online Store image settings can be detached after CONFIRMATION_REQUIRED. Repeat the same request with confirmed: true and the returned token. An attribute-option image blocks deletion; replace it or remove the option first. Manually pasted URLs in HTML and external content are not tracked or rewritten. Deletion commits the library removal, reference cleanup and quota change together; removal of delivered file objects follows asynchronously.

Path parameters

Name	Type	Description
`id` required	`uuid`	File id. Example: `8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`confirmed`	`boolean`	On a confirmation retry, set this to true and send the returned confirmation_token. Omit it on the first request.
`confirmation_token`	`string`	Token from the CONFIRMATION_REQUIRED response. Omit it on the first request and resend the exact same id selection when using it.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORAGE_INVALID_REQUEST
The request body is malformed.
400 STORAGE_INVALID_CONFIRMATION
confirmation_token is missing, expired, or mismatched.
400 STORAGE_FILE_DELETE_BLOCKED
The file is required by another resource and cannot be deleted. Remove that blocking reference first.
404 STORAGE_FILE_NOT_FOUND
The file is unavailable in this store or is outside the permitted library.
409 CONFIRMATION_REQUIRED
Returned when removable references exist. Re-send with confirmed: true and the response's confirmation_token to detach those references and delete the file.

curl -X DELETE 'https://api-store.tringify.com/api/2025-01/files/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/files/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201", {
  method: "DELETE",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.delete(
    "https://api-store.tringify.com/api/2025-01/files/8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "success": true
  }
}

Delete multiple files

POST write_files and/or write_site_assets (depends on selected file types)

Delete a selected set of files.

Every file must exist, belong to the store and be writable by the token. Both write scopes are needed for a selection spanning both libraries. If removable references exist, CONFIRMATION_REQUIRED returns their impact without deleting the selection. After approval, resend the same IDs with confirmed: true and the returned confirmation_token. Changing the selection requires a new unconfirmed request. A required attribute-option image blocks the entire selection. File-record deletion and removable-reference cleanup commit together; delivered file cleanup follows asynchronously. After a lost response, read the library before making another deletion request.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`file_ids` required	`array<string>`	File IDs to delete, up to `bulk_delete_max` from `GET /files/limits`. Send the same selection when confirming deletion. Example: `["8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201", "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10"]`
`confirmed`	`boolean`	On a confirmation retry, set this to `true` to detach removable references and delete the files. Required references still block deletion. Example: `false`
`confirmation_token`	`string`	Token returned by the first call when confirmation is required.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORAGE_INVALID_REQUEST
The request body is malformed.
400 STORAGE_FILE_IDS_REQUIRED
The body must include a non-empty file_ids array.
400 STORAGE_BULK_DELETE_MAX_EXCEEDED
The batch exceeds the maximum files per delete.
400 STORAGE_INVALID_CONFIRMATION
confirmation_token is missing, expired, or mismatched.
400 STORAGE_FILE_DELETE_BLOCKED
At least one file is required by another resource and cannot be deleted. Remove the blocking reference first.
404 STORAGE_FILE_NOT_FOUND
One or more selected files are unavailable in this store or outside the permitted libraries.
409 CONFIRMATION_REQUIRED
Returned when removable references require approval. After approval, resend the same file IDs with confirmed: true and the returned confirmation_token.

curl -X POST 'https://api-store.tringify.com/api/2025-01/files/bulk-delete' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "confirmed": false,
  "file_ids": [
    "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
    "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10"
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/files/bulk-delete", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "confirmed": false,
    "file_ids": [
      "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
      "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10"
    ]
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/files/bulk-delete",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "confirmed": False,
        "file_ids": ["8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201", "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10"],
    },
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "deleted_ids": [
      "8f2a1c2b-9d4e-4f74-a6cf-1d58f6f7c201",
      "9a3b2d4e-8c5f-4a61-b7d2-2e69b8778d10"
    ],
    "failed": []
  }
}

File created

EVENT files/create App scope: read_files Staff permission: files:read

Payload fields

Field	Type	Description
`file.id`	`string`	Always present The stable file id.
`file.type`	`string`	Always present The file namespace: upload or site_asset.
`file.media_type`	`string`	Always present The detected media class: image, video, document, or 3d.
`file.filename`	`string`	Always present The file name assigned when the file was created; use original_filename for its editable display name.
`file.original_filename`	`string`	Always present The merchant-facing filename.
`file.size_bytes`	`integer`	Always present The validated source size in bytes.
`file.mime_type`	`string`	Always present The MIME type detected from the source bytes.
`file.width`	`integer`	Selectable in the Payload builder The source width in pixels when applicable.
`file.height`	`integer`	Selectable in the Payload builder The source height in pixels when applicable.
`file.alt_text`	`string`	Selectable in the Payload builder The file's accessibility description.
`file.revision`	`integer`	Always present The current source revision.
`file.preview_status`	`string`	Always present Preview lifecycle state: none, pending, ready, or failed.
`file.preview_error_code`	`string`	Selectable in the Payload builder `STORAGE_PREVIEW_FAILED` when preview_status is failed; absent otherwise.
`file.preview_revision`	`integer`	Always present The source revision represented by the current preview; zero means no preview.
`file.preview_requested_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when preview work was most recently requested.
`file.preview_completed_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when the current preview became ready.
`file.created_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when the file became ready.
`file.updated_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when file metadata or preview state last changed.

Payload shape

Sample payload

{
  "file": {
    "alt_text": "Trail shoe in black",
    "created_at": "2026-06-09T12:00:00+05:30",
    "filename": "8f2a1c2b-9d4e-4a56-b789-0123456789ab.glb",
    "height": null,
    "id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "media_type": "3d",
    "mime_type": "model/gltf-binary",
    "original_filename": "trail-shoe.glb",
    "preview_completed_at": null,
    "preview_error_code": null,
    "preview_requested_at": null,
    "preview_revision": 0,
    "preview_status": "none",
    "revision": 1,
    "size_bytes": 8421934,
    "type": "upload",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "width": null
  }
}

File updated

EVENT files/update App scope: read_files Staff permission: files:read

Payload fields

Field	Type	Description
`file.id`	`string`	Always present The stable file id.
`file.type`	`string`	Always present The file namespace: upload or site_asset.
`file.media_type`	`string`	Always present The detected media class: image, video, document, or 3d.
`file.filename`	`string`	Always present The file name assigned when the file was created; use original_filename for its editable display name.
`file.original_filename`	`string`	Always present The merchant-facing filename.
`file.size_bytes`	`integer`	Always present The validated source size in bytes.
`file.mime_type`	`string`	Always present The MIME type detected from the source bytes.
`file.width`	`integer`	Selectable in the Payload builder The source width in pixels when applicable.
`file.height`	`integer`	Selectable in the Payload builder The source height in pixels when applicable.
`file.alt_text`	`string`	Selectable in the Payload builder The file's accessibility description.
`file.revision`	`integer`	Always present The current source revision.
`file.preview_status`	`string`	Always present Preview lifecycle state: none, pending, ready, or failed.
`file.preview_error_code`	`string`	Selectable in the Payload builder `STORAGE_PREVIEW_FAILED` when preview_status is failed; absent otherwise.
`file.preview_revision`	`integer`	Always present The source revision represented by the current preview; zero means no preview.
`file.preview_requested_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when preview work was most recently requested.
`file.preview_completed_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when the current preview became ready.
`file.created_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when the file became ready.
`file.updated_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when file metadata or preview state last changed.
`changed_fields`	`array`	Always present The file fields changed by this event.

Payload shape

Sample payload

{
  "changed_fields": [
    "preview_status",
    "preview_revision",
    "preview_completed_at"
  ],
  "file": {
    "alt_text": "Trail shoe in black",
    "created_at": "2026-06-09T12:00:00+05:30",
    "filename": "8f2a1c2b-9d4e-4a56-b789-0123456789ab.glb",
    "height": null,
    "id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "media_type": "3d",
    "mime_type": "model/gltf-binary",
    "original_filename": "trail-shoe.glb",
    "preview_completed_at": "2026-06-09T12:01:10+05:30",
    "preview_error_code": null,
    "preview_requested_at": "2026-06-09T12:00:02+05:30",
    "preview_revision": 1,
    "preview_status": "ready",
    "revision": 1,
    "size_bytes": 8421934,
    "type": "upload",
    "updated_at": "2026-06-09T12:01:10+05:30",
    "width": null
  }
}

File deleted

EVENT files/delete App scope: read_files Staff permission: files:read

Payload fields

Field	Type	Description
`file.id`	`string`	Always present The stable file id.
`file.type`	`string`	Always present The file namespace: upload or site_asset.
`file.media_type`	`string`	Always present The detected media class: image, video, document, or 3d.
`file.filename`	`string`	Always present The file name assigned when the file was created; use original_filename for its editable display name.
`file.original_filename`	`string`	Always present The merchant-facing filename.
`file.size_bytes`	`integer`	Always present The validated source size in bytes.
`file.mime_type`	`string`	Always present The MIME type detected from the source bytes.
`file.width`	`integer`	Selectable in the Payload builder The source width in pixels when applicable.
`file.height`	`integer`	Selectable in the Payload builder The source height in pixels when applicable.
`file.alt_text`	`string`	Selectable in the Payload builder The file's accessibility description.
`file.revision`	`integer`	Always present The current source revision.
`file.preview_status`	`string`	Always present Preview lifecycle state: none, pending, ready, or failed.
`file.preview_error_code`	`string`	Selectable in the Payload builder `STORAGE_PREVIEW_FAILED` when preview_status is failed; absent otherwise.
`file.preview_revision`	`integer`	Always present The source revision represented by the current preview; zero means no preview.
`file.preview_requested_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when preview work was most recently requested.
`file.preview_completed_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when the current preview became ready.
`file.created_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when the file became ready.
`file.updated_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when file metadata or preview state last changed.
`deleted_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when the file was deleted.

Payload shape

Sample payload

{
  "deleted_at": "2026-06-10T09:30:00+05:30",
  "file": {
    "alt_text": "Trail shoe in black",
    "created_at": "2026-06-09T12:00:00+05:30",
    "filename": "8f2a1c2b-9d4e-4a56-b789-0123456789ab.glb",
    "height": null,
    "id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "media_type": "3d",
    "mime_type": "model/gltf-binary",
    "original_filename": "trail-shoe.glb",
    "preview_completed_at": "2026-06-09T12:01:10+05:30",
    "preview_error_code": null,
    "preview_requested_at": "2026-06-09T12:00:02+05:30",
    "preview_revision": 1,
    "preview_status": "ready",
    "revision": 1,
    "size_bytes": 8421934,
    "type": "upload",
    "updated_at": "2026-06-09T12:01:10+05:30",
    "width": null
  }
}

Site asset created

EVENT site_assets/create App scope: read_site_assets Staff permission: online_store.site_assets:read

Payload fields

Field	Type	Description
`file.id`	`string`	Always present The stable file id.
`file.type`	`string`	Always present The file namespace: upload or site_asset.
`file.media_type`	`string`	Always present The detected media class: image, video, document, or 3d.
`file.filename`	`string`	Always present The file name assigned when the file was created; use original_filename for its editable display name.
`file.original_filename`	`string`	Always present The merchant-facing filename.
`file.size_bytes`	`integer`	Always present The validated source size in bytes.
`file.mime_type`	`string`	Always present The MIME type detected from the source bytes.
`file.width`	`integer`	Selectable in the Payload builder The source width in pixels when applicable.
`file.height`	`integer`	Selectable in the Payload builder The source height in pixels when applicable.
`file.alt_text`	`string`	Selectable in the Payload builder The file's accessibility description.
`file.revision`	`integer`	Always present The current source revision.
`file.preview_status`	`string`	Always present Preview lifecycle state: none, pending, ready, or failed.
`file.preview_error_code`	`string`	Selectable in the Payload builder `STORAGE_PREVIEW_FAILED` when preview_status is failed; absent otherwise.
`file.preview_revision`	`integer`	Always present The source revision represented by the current preview; zero means no preview.
`file.preview_requested_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when preview work was most recently requested.
`file.preview_completed_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when the current preview became ready.
`file.created_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when the file became ready.
`file.updated_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when file metadata or preview state last changed.

Payload shape

Sample payload

{
  "file": {
    "alt_text": "Trail shoe in black",
    "created_at": "2026-06-09T12:00:00+05:30",
    "filename": "8f2a1c2b-9d4e-4a56-b789-0123456789ab.glb",
    "height": null,
    "id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "media_type": "3d",
    "mime_type": "model/gltf-binary",
    "original_filename": "trail-shoe.glb",
    "preview_completed_at": null,
    "preview_error_code": null,
    "preview_requested_at": null,
    "preview_revision": 0,
    "preview_status": "none",
    "revision": 1,
    "size_bytes": 8421934,
    "type": "site_asset",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "width": null
  }
}

Site asset updated

EVENT site_assets/update App scope: read_site_assets Staff permission: online_store.site_assets:read

Payload fields

Field	Type	Description
`file.id`	`string`	Always present The stable file id.
`file.type`	`string`	Always present The file namespace: upload or site_asset.
`file.media_type`	`string`	Always present The detected media class: image, video, document, or 3d.
`file.filename`	`string`	Always present The file name assigned when the file was created; use original_filename for its editable display name.
`file.original_filename`	`string`	Always present The merchant-facing filename.
`file.size_bytes`	`integer`	Always present The validated source size in bytes.
`file.mime_type`	`string`	Always present The MIME type detected from the source bytes.
`file.width`	`integer`	Selectable in the Payload builder The source width in pixels when applicable.
`file.height`	`integer`	Selectable in the Payload builder The source height in pixels when applicable.
`file.alt_text`	`string`	Selectable in the Payload builder The file's accessibility description.
`file.revision`	`integer`	Always present The current source revision.
`file.preview_status`	`string`	Always present Preview lifecycle state: none, pending, ready, or failed.
`file.preview_error_code`	`string`	Selectable in the Payload builder `STORAGE_PREVIEW_FAILED` when preview_status is failed; absent otherwise.
`file.preview_revision`	`integer`	Always present The source revision represented by the current preview; zero means no preview.
`file.preview_requested_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when preview work was most recently requested.
`file.preview_completed_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when the current preview became ready.
`file.created_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when the file became ready.
`file.updated_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when file metadata or preview state last changed.
`changed_fields`	`array`	Always present The file fields changed by this event.

Payload shape

Sample payload

{
  "changed_fields": [
    "preview_status",
    "preview_revision",
    "preview_completed_at"
  ],
  "file": {
    "alt_text": "Trail shoe in black",
    "created_at": "2026-06-09T12:00:00+05:30",
    "filename": "8f2a1c2b-9d4e-4a56-b789-0123456789ab.glb",
    "height": null,
    "id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "media_type": "3d",
    "mime_type": "model/gltf-binary",
    "original_filename": "trail-shoe.glb",
    "preview_completed_at": "2026-06-09T12:01:10+05:30",
    "preview_error_code": null,
    "preview_requested_at": "2026-06-09T12:00:02+05:30",
    "preview_revision": 1,
    "preview_status": "ready",
    "revision": 1,
    "size_bytes": 8421934,
    "type": "site_asset",
    "updated_at": "2026-06-09T12:01:10+05:30",
    "width": null
  }
}

Site asset deleted

EVENT site_assets/delete App scope: read_site_assets Staff permission: online_store.site_assets:read

Payload fields

Field	Type	Description
`file.id`	`string`	Always present The stable file id.
`file.type`	`string`	Always present The file namespace: upload or site_asset.
`file.media_type`	`string`	Always present The detected media class: image, video, document, or 3d.
`file.filename`	`string`	Always present The file name assigned when the file was created; use original_filename for its editable display name.
`file.original_filename`	`string`	Always present The merchant-facing filename.
`file.size_bytes`	`integer`	Always present The validated source size in bytes.
`file.mime_type`	`string`	Always present The MIME type detected from the source bytes.
`file.width`	`integer`	Selectable in the Payload builder The source width in pixels when applicable.
`file.height`	`integer`	Selectable in the Payload builder The source height in pixels when applicable.
`file.alt_text`	`string`	Selectable in the Payload builder The file's accessibility description.
`file.revision`	`integer`	Always present The current source revision.
`file.preview_status`	`string`	Always present Preview lifecycle state: none, pending, ready, or failed.
`file.preview_error_code`	`string`	Selectable in the Payload builder `STORAGE_PREVIEW_FAILED` when preview_status is failed; absent otherwise.
`file.preview_revision`	`integer`	Always present The source revision represented by the current preview; zero means no preview.
`file.preview_requested_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when preview work was most recently requested.
`file.preview_completed_at`	`string`	Selectable in the Payload builder Time in the store's time zone, with its offset (RFC 3339), when the current preview became ready.
`file.created_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when the file became ready.
`file.updated_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when file metadata or preview state last changed.
`deleted_at`	`string`	Always present Time in the store's time zone, with its offset (RFC 3339), when the file was deleted.

Payload shape

Sample payload

{
  "deleted_at": "2026-06-10T09:30:00+05:30",
  "file": {
    "alt_text": "Trail shoe in black",
    "created_at": "2026-06-09T12:00:00+05:30",
    "filename": "8f2a1c2b-9d4e-4a56-b789-0123456789ab.glb",
    "height": null,
    "id": "8f2a1c2b-9d4e-4a56-b789-0123456789ab",
    "media_type": "3d",
    "mime_type": "model/gltf-binary",
    "original_filename": "trail-shoe.glb",
    "preview_completed_at": "2026-06-09T12:01:10+05:30",
    "preview_error_code": null,
    "preview_requested_at": "2026-06-09T12:00:02+05:30",
    "preview_revision": 1,
    "preview_status": "ready",
    "revision": 1,
    "size_bytes": 8421934,
    "type": "site_asset",
    "updated_at": "2026-06-09T12:01:10+05:30",
    "width": null
  }
}

Endpoints#

Headers

Errors

Headers

Errors

Query parameters

Headers

Errors

Headers

Body parameters

Errors

Headers

Body parameters

Errors

Headers

Body parameters

Errors

Headers

Body parameters

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Headers

Body parameters

Errors

Headers

Body parameters

Errors

Webhook events#

Payload fields

Payload fields

Payload fields

Payload fields

Payload fields

Payload fields

Complete or recover an upload#

Use video and 3D previews#

Confirm deletion impact#