Assets, Versions & Folders

Assets

Assets are the durable resources returned after upload finalization or a completed remote import. Use the asset ID from the response for later operations; do not infer asset IDs from filenames or URLs.

List assets

assets:read is required. Results are cursor-paginated. The maximum page size is 100.

curl --request GET \
  --url "https://api.media2url.com/v1/assets?limit=20" \
  --header "Authorization: Bearer ${MEDIA2URL_API_KEY}"

When pagination.has_more is true, send pagination.next_cursor on the next request:

curl --request GET \
  --url "https://api.media2url.com/v1/assets?limit=20&cursor=CURSOR_FROM_PREVIOUS_RESPONSE" \
  --header "Authorization: Bearer ${MEDIA2URL_API_KEY}"

Do not assume that a cursor is reusable forever. Follow the cursor returned for the current page and handle an empty result set.

Retrieve one asset

curl --request GET \
  --url https://api.media2url.com/v1/assets/asset_example_123 \
  --header "Authorization: Bearer ${MEDIA2URL_API_KEY}"

An asset resource can include id, status, filename, content_type, size, checksum_sha256, privacy, direct_url, share_url, embeds, and created_at.

The direct_url is intended for systems that need the hosted file response. The share_url is intended for a person opening a browser-facing Media2URL page.

Delete an asset

assets:delete is required:

curl --request DELETE \
  --url https://api.media2url.com/v1/assets/asset_example_123 \
  --header "Authorization: Bearer ${MEDIA2URL_API_KEY}"

Deletion is an account action. Treat the response as authoritative and do not continue serving a deleted asset from application caches.

Replace an asset

Replacement requires assets:replace and uses its own presign/finalize pair:

curl --request POST \
  --url https://api.media2url.com/v1/assets/asset_example_123/replace/presign \
  --header "Authorization: Bearer ${MEDIA2URL_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "filename": "release-screenshot-v2.png",
    "content_type": "image/png",
    "size": 251902,
    "checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }'

PUT the replacement bytes to the returned upload URL, then finalize with the replacement upload ID:

curl --request POST \
  --url https://api.media2url.com/v1/assets/asset_example_123/replace/finalize \
  --header "Authorization: Bearer ${MEDIA2URL_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: replace-asset-example-20260920-001" \
  --data '{"upload_id":"upl_replace_example_123"}'

Use the same retry rules as new uploads: a repeated request must keep the same idempotency key and body, and an expired session requires a new presign request.

Versions

assets:read is required:

curl --request GET \
  --url https://api.media2url.com/v1/assets/asset_example_123/versions \
  --header "Authorization: Bearer ${MEDIA2URL_API_KEY}"

Version history is read-only through this endpoint. Use the replacement workflow when the current asset needs new bytes.

Folders

Folders organize assets within the authenticated account or active workspace. They do not change asset URLs, access policy, billing, or ownership.

List folders

Use folders:read:

curl --request GET \
  --url https://api.media2url.com/v1/folders \
  --header "Authorization: Bearer ${MEDIA2URL_API_KEY}"

The response contains folder resources with IDs, names, slugs, parent folder IDs, and timestamps.

Create a folder

Use folders:write:

curl --request POST \
  --url https://api.media2url.com/v1/folders \
  --header "Authorization: Bearer ${MEDIA2URL_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Release screenshots",
    "parent_folder_id": null
  }'

Use the returned folder ID when a later API operation accepts a folder relationship. Do not assume a folder slug is globally unique outside the authenticated account.

Workspace access

The API applies the active account and workspace permissions associated with the API key. A key does not bypass workspace roles, suspended access, plan controls, or abuse restrictions. If a workspace changes while an integration is running, treat 403 responses as an authorization state change rather than repeatedly retrying them.

Related Operations

Use Uploads, imports, and jobs to create an asset, and Errors, retries, and limits to interpret conflicts, quotas, and retry responses.