albums

Creates an empty album, or reuses a matching album without changing it. The API checks names within the library, ignoring case and surrounding whitespace. Returns 201 for a new record or 200 for an existing matching name. Only supplied create fields must match; omitted fields leave existing values intact. A different supplied value returns 409 without changing the record; repeating that request does not resolve the conflict. Omitting the name uses the default name New Album. A new album starts empty; follow up with add_assets_to_album to populate it. A reused album may already contain assets. Does not delete existing records. To rename an existing album, use update_album instead of creating a new one.

post/api/albums

Request

  • Base URL
    https://api.gumnut.ai
  • Auth
    • HTTP bearer
    • or HTTP bearer

Request body

namestring nullable

Display name for the new album. Optional; callers that need to name an album can set it here or via update_album after creation. If supplied, it must not be blank; surrounding whitespace is trimmed.

descriptionstring nullable

Optional free-form description shown alongside the album name.

library_idstring nullable

Library to create the album in. Optional if the user has a single live (non-trashed) library; required when they have multiple.

Response

Existing matching album

idstring required

Unique album identifier with 'album_' prefix

namestring required

Display name of the album. Names supplied as text on create or update are trimmed and must not be blank.

descriptionstring nullable

Optional description text for the album

asset_countinteger required

Total number of assets in this album

album_cover_asset_idstring nullable

ID of the asset displayed as the album cover. May be a server-selected default when the album has no explicit cover set, or null when the album has no live assets.

asset_urlsobject nullable

Asset variants for the album cover: 'thumbnail'

start_datestring date-time nullable

The oldest asset date (local_datetime) in the album, or null if empty

end_datestring date-time nullable

The newest asset date (local_datetime) in the album, or null if empty

created_atstring date-time required

When this album was created

updated_atstring date-time required

When this album was last updated

Changes

    • breaking

      the / request property's minLength was increased from 0 to 1

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the success response with the status

    • breaking

      response property detail list-of-types was widened by adding types string to media type application/json of response 422

    • info

      the response property became required for the status