Skip to main content
This page explains Snag’s image/asset handling policy, supported sources, file size limits, and the recommended upload flow for use across admin and API. Use this when attaching images to objects such as Users, Loyalty Rules, Pages, and Badges.
  • Internal assets are required (most fields): For images that are uploaded from admin and linked to Snag objects (for example: UserMetadata.logoUrl, LoyaltyRule.mediaUrl, page builder images, and LoyaltyBadge.imageUrl), you must first upload the file using Snag’s asset endpoint and then reference the returned asset url in your create/update request.
  • External URLs allowed (specific fields only):
    • UserMetadata.logoUrl: May reference external sources (e.g., Twitter).
    • LoyaltyPost.mediaUrl: May reference external sources (e.g., Twitter and other social platforms).
For fields that require internal assets, Snag rejects external URLs. Always upload via the asset API first and then pass the returned url.

​
File size limits and validation

  • Images: up to 1 MB
  • Videos: up to 10 MB
  • You must provide the exact fileSize (in bytes) when requesting the presigned URL, and the uploaded file must match that size.
Supported paths include: announcements, images, videos, banners, fonts, posts, profiles, minting, loyalty, tokenClaims.
Use the Asset Upload endpoint to obtain a presigned URL, upload your file to that URL, and then reference the returned public url in your object mutation.
1

Request a presigned upload URL

Call the Asset Upload API with the file name, exact file size (in bytes), and desired filePath. You’ll receive a signedUrl (for PUT upload) and a public url (to store on your object). See the Asset upload endpoint documentation.
2

Upload the file to the signed URL (PUT)

Perform a PUT to signedUrl with the file as the request body. Ensure Content-Type matches the file type and upload before the URL expires.
3

Use the asset URL in your object create/update

Include the returned url in the appropriate field. This is required for fields that do not accept external URLs.

​
Common validation errors and fixes

  • Likely cause: fileSize mismatch between the presigned request and actual uploaded bytes.
  • Fix: Recompute the exact file size in bytes and request a new signedUrl with the corrected fileSize.
  • Likely causes: Expired signedUrl or incorrect Content-Type. - Fix: Request a new signedUrl and upload immediately; ensure Content-Type matches the file type (e.g., image/png).
  • Cause: The target field only accepts Snag-hosted assets. - Fix: Use the upload flow above and pass the returned url instead of an external link.
  • Allowed: UserMetadata.logoUrl, LoyaltyPost.mediaUrl (can reference external sources like Twitter and other social platforms).
  • Not allowed: Most admin-uploadable fields such as UserMetadata.logoUrl, LoyaltyRule.mediaUrl, page builder images, and LoyaltyBadge.imageUrl.

​
Admin UI behavior

When you upload images from the admin UI for fields that require internal assets, Snag uses the same flow under the hood: it requests a presigned URL, uploads your file, and stores the resulting asset url on the object. Pasting external URLs into these fields is blocked.

​
API reference

See the official endpoint for complete parameters, supported paths, and responses:
You now know when external URLs are allowed and how to upload images to Snag and attach them to your objects safely.
⌘I