Albums API

Photo albums of a community. Every route sits behind the router-level feature gate requireFeature(albums): a plan without it gets 403 FEATURE_NOT_AVAILABLE, reads included. Tenant context comes from ?communityId= (or X-Tenant-Id / the custom domain).

Reads are optionalAuth and follow the community's read scope:

• An APPROVED member reads every album. Hidden albums are for albums:manage and albums:moderate only.
• A guest, or a signed-in non-member, reads only albums opted into guest preview, in a PUBLIC community whose plan includes albums.
• Anyone else gets 404.

Writes need an APPROVED member who isn't suspended or blocked from media. Editing ANY album needs albums:manage or albums:moderate. Anyone may edit their OWN album. albums:create lets you create and edit your own, never anyone else's.

14 endpoints.

GET /api/albums

Auth: optional — a token changes what you can see (see "Who may read what").

Parameters

Responses

POST /api/albums

Needs albums:manage or albums:create. The community is the one the guards checked. A body communityId that disagrees is refused with 400 COMMUNITY_MISMATCH. Photos count against the plan's storage and are refused over the cap. Up to 50 photos, 25 MB each. Only PUBLIC communities that opted albums into guest preview accept isGuestVisible=true.

Auth: Bearer JWT required.

Request body (required) — application/json

Type: CreateAlbumRequest

Responses

DELETE /api/albums/{albumId}

Gives the photos' storage back and removes the album from the home feed. Auth: Bearer JWT required.

Responses

GET /api/albums/{albumId}

A hidden album, or one a guest may not preview, answers 404 exactly as a missing id does. Auth: optional — a token changes what you can see (see "Who may read what").

Responses

PUT /api/albums/{albumId}

Auth: Bearer JWT required.

Request body — application/json

Responses

POST /api/albums/{albumId}/hide

A hidden album leaves every listing. It, its likes and its comment thread answer 404 to everyone but moderators. Auth: Bearer JWT required.

Parameters

Responses

DELETE /api/albums/{albumId}/images

Auth: Bearer JWT required.

Request body (required) — application/json

Responses

POST /api/albums/{albumId}/images

Appended atomically, so concurrent uploads never lose photos. At most 50 per album. Counts against storage. Auth: Bearer JWT required.

Request body (required) — multipart/form-data

Responses

DELETE /api/albums/{albumId}/images/all

Auth: Bearer JWT required.

Parameters

Responses

PUT /api/albums/{albumId}/images/reorder

images must be an exact reordering of the album's current photos, matched by filename (url for old photos). The server stores its own copy of each photo, never the client's. The first photo becomes the cover.

Auth: Bearer JWT required.

Parameters

Request body (required) — application/json

Responses

POST /api/albums/{albumId}/like

Any APPROVED member not blocked from liking, on an album they may open (a hidden one answers 404). The album's creator is notified while still a member. Auth: Bearer JWT required.

Parameters

Responses

GET /api/albums/{albumId}/likes

Readable exactly when the album is (same rule as GET /api/albums/albumId). Auth: optional — a token changes what you can see (see "Who may read what").

Parameters

Responses

POST /api/albums/{albumId}/unhide

Auth: Bearer JWT required.

Parameters

Responses

GET /api/albums/preview/{slug}/{albumId}

Answers only for an album a guest may see (public community, albums in guest preview, album opted in). Everything else is 404. Auth: Bearer JWT required.

Parameters

Responses