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.
What owns a gallery
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
| Field | Meaning |
|---|---|
id | Row id. Stable while the item is in the gallery. |
kind | image or video. |
image_url | Photo bytes for image. Poster still for video, or null. |
video_embed_url | Player URL for video, safe to use as an iframe src. Null for image. |
video_provider | youtube or vimeo. Null for image. |
alt_text | Screen reader description. Empty string when the organizer left it blank. |
crop | focus_x, focus_y (0 to 1) and zoom (1 to 4). Same framing model as the cover photo. |
width_px, height_px | Intrinsic pixel size of the stored photo. Null for video. |
sort_order | Position in the mosaic, starting at 0. |
Reading a gallery
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/:productionIdreturnsgalleryon the series.GET /v1/events/:eventIdreturnsgalleryon 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.
Editing a gallery
These need catalog:write.
GET /v1/productions/:id/galleryandGET /v1/events/:id/galleryread the editable list.POST /v1/productions/:id/gallery/imagesandPOST /v1/events/:id/gallery/imagesupload one photo asmultipart/form-datawith afilepart. The response gives youimage_url,width_pxandheight_px.PUT /v1/productions/:id/galleryandPUT /v1/events/:id/galleryreplace 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_urlthat 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_textup to 300 characters.
Errors
| Code | Status | What happened |
|---|---|---|
series_gallery_is_production_scoped | 409 | You aimed at a child show. Use the production_id in the response. |
gallery_too_many_items | 400 | More than 12 items. |
gallery_image_url_required | 400 | An image item with no photo behind it. |
gallery_image_url_not_uploaded | 400 | That photo was not uploaded to AXYN for this tenant. |
gallery_video_url_not_allowlisted | 400 | Not a YouTube or Vimeo link. |
gallery_crop_out_of_range | 400 | Focus outside 0 to 1, or zoom outside 1 to 4. |
gallery_alt_text_too_long | 400 | Over 300 characters. |
invalid_image | 400 | The bytes are not a JPEG, PNG, or WebP. |
file_too_large | 400 | Over 5 MB. |
image_too_large_for_web | 400 | Too many pixels. |
image_dimensions_unreadable | 400 | AXYN could not read the photo header. |