Files & Formats¶

This is an integration guide, not a separate /v1/files endpoint. The supplied specification does not declare a files endpoint. File information is embedded in an asset's formats array.

Find a File¶

1. Retrieve an asset using the Assets API.
2. Inspect its formats array.
3. Choose a format supported by your application.
4. Inspect root, resources and zip_archive_url rather than constructing storage URLs.
5. Check the asset's licence and attribution requirements before downloading or redistributing it.

isPreferredForDownload and isPreferredForGalleryViewer describe intended format preference. Do not assume a matching format always exists. Handle missing or null values.

Formats and Resources¶

The root resource and additional resources each describe a URL, MIME type and relative path. Some formats may rely on additional files; do not assume the root alone is self-contained.

A nullable zip_archive_url is also exposed. The schema does not define archive contents, URL lifetime, resource availability or permission requirements for returned URLs.

Browser Access¶

isCorsAllowed is format metadata. It does not prove the JSON API allows every website origin. Browser access to API JSON and access to resource URLs are separate questions.

Do not automatically attach your API bearer token to arbitrary resource URLs returned in metadata. Validate destinations before a server downloads remote resources, especially when processing user-controlled URLs.

Thumbnails¶

Public thumbnail metadata appears in thumbnail. Account operations for uploading replacement thumbnails use multipart form data with the required field image; see Users.

Deprecated Fields¶

AssetFormat.role is explicitly deprecated. Do not depend on it for format selection.

Schema Reference¶

AssetFormat¶

AssetResource¶

FormatComplexity¶

Thumbnail¶

ImageSchema¶