Skip to content

Custom API

Listing gallery

Reference only. Not a decision unless cited in product/DECISIONS.md.

Listing gallery

Photos and video that sell a listing. One cover photo is not enough to sell a weekend, so a listing carries a small mosaic guests can look through.

A gallery belongs to a listing, and a listing is one of two things:

  • a series (a production, such as a three night festival), or
  • an independent event (a one off show).

A child show inside a series does not own a gallery. Every night of a series shows the series gallery, so guests see one story instead of three. If you ask for a child show's gallery you get 409 series_gallery_is_production_scoped, and the response names the production_id to use instead.

This is not the post event photo gallery. That one registers organizer hosted photo URLs after the show, under guest consent, and lives at /v1/me/event-photos.

Item shape

FieldMeaning
idRow id. Stable while the item is in the gallery.
kindimage or video.
image_urlPhoto bytes for image. Poster still for video, or null.
video_embed_urlPlayer URL for video, safe to use as an iframe src. Null for image.
video_provideryoutube or vimeo. Null for image.
alt_textScreen reader description. Empty string when the organizer left it blank.
cropfocus_x, focus_y (0 to 1) and zoom (1 to 4). Same framing model as the cover photo.
width_px, height_pxIntrinsic pixel size of the stored photo. Null for video.
sort_orderPosition in the mosaic, starting at 0.

The gallery rides along with the catalog payload you already fetch, so there is no extra call and no request per listing.

  • GET /v1/productions/:productionId returns gallery on the series.
  • GET /v1/events/:eventId returns gallery on an independent event. On a child show it is empty: read the series instead.

An empty gallery is an empty array, never a missing key. Render nothing when it is empty rather than showing a placeholder.

These need catalog:write.

  • GET /v1/productions/:id/gallery and GET /v1/events/:id/gallery read the editable list.
  • POST /v1/productions/:id/gallery/images and POST /v1/events/:id/gallery/images upload one photo as multipart/form-data with a file part. The response gives you image_url, width_px and height_px.
  • PUT /v1/productions/:id/gallery and PUT /v1/events/:id/gallery replace the whole gallery with { "items": [...] }. Array order is the order guests see, so reorder by sending the array you want. Sending { "items": [] } clears the gallery.

Upload the photo first, then send its image_url in the PUT. A gallery photo has to be one AXYN stored for your tenant; any other URL is refused, so you cannot point the mosaic at someone else's server.

Photos

AXYN reads the file's own bytes to decide what it is. The Content-Type your client sends is ignored, so a renamed file does not get through.

  • JPEG, PNG, or WebP.
  • 5 MB or smaller.
  • 4096 pixels or fewer on the long edge, and 24 megapixels in total.

A photo over those limits is refused with image_too_large_for_web rather than shipped to buyers. Export a smaller file and upload again.

Video

v1 plays allowlisted embeds only. AXYN stores no video files and runs no transcode pipeline, so there is nothing to upload.

  • YouTube and Vimeo links are accepted, in any of their usual shapes (youtu.be/ID, youtube.com/watch?v=ID, youtube.com/shorts/ID, vimeo.com/ID, and so on).
  • AXYN rewrites every accepted link to its canonical player URL. Use the video_embed_url that comes back, not the URL you sent.
  • Anything else is refused with gallery_video_url_not_allowlisted.

A video item may carry an uploaded poster still in image_url.

Limits

  • Up to 12 items in one gallery.
  • alt_text up to 300 characters.

Errors

CodeStatusWhat happened
series_gallery_is_production_scoped409You aimed at a child show. Use the production_id in the response.
gallery_too_many_items400More than 12 items.
gallery_image_url_required400An image item with no photo behind it.
gallery_image_url_not_uploaded400That photo was not uploaded to AXYN for this tenant.
gallery_video_url_not_allowlisted400Not a YouTube or Vimeo link.
gallery_crop_out_of_range400Focus outside 0 to 1, or zoom outside 1 to 4.
gallery_alt_text_too_long400Over 300 characters.
invalid_image400The bytes are not a JPEG, PNG, or WebP.
file_too_large400Over 5 MB.
image_too_large_for_web400Too many pixels.
image_dimensions_unreadable400AXYN could not read the photo header.