@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Spinitron v2 API
@base https://spinitron.com/api
@version 1.0.0
@auth Bearer bearer | ApiKey access-token in query
@endpoints 9
@toc personas(2), shows(2), playlists(2), spins(3)

@group personas
@endpoint GET /personas
@optional {name: str, count: int=20, page: int, fields: [str], expand: [str]}
@returns(200)

@endpoint GET /personas/{id}
@required {id: int}
@optional {fields: [str], expand: [str]}
@returns(200) {id: int, name: str, bio: str, since: int(year), email: str(email), website: str(url), image: str(url), _links: map{self: map{href: str}, shows: [map]}}
@errors {404}

@endgroup

@group shows
@endpoint GET /shows
@optional {start: str(date-time), end: str(date-time), count: int=20, page: int, fields: [str], expand: [str]}
@returns(200)
@errors {422}

@endpoint GET /shows/{id}
@required {id: int}
@optional {fields: [str], expand: [str]}
@returns(200) {id: int, start: str(date-time), end: str(date-time), duration: int, timezone: str, one_off: bool, category: str, title: str, description: str, since: int(year), url: str(url), hide_dj: bool, image: str(url), _links: map{self: map{href: str}, personas: [map], playlists: map{href: str}}}
@errors {404}

@endgroup

@group playlists
@endpoint GET /playlists
@optional {start: str(date-time), end: str(date-time), show_id: int, persona_id: int, count: int=20, page: int, fields: [str], expand: [str]}
@returns(200)

@endpoint GET /playlists/{id}
@required {id: int}
@optional {fields: [str], expand: [str]}
@returns(200) {id: int, persona_id: int, show_id: int, start: str(date-time), end: str(date-time), duration: int, timezone: str, category: str, title: str, description: str, since: int(year), url: str(url), hide_dj: bool, image: str(url), automation: bool, episode_name: str, episode_description: str, _links: map{self: map{href: str}, persona: map{href: str}, show: map{href: str}, spins: map{href: str}}}
@errors {404}

@endgroup

@group spins
@endpoint GET /spins
@optional {start: str(date-time), end: str(date-time), playlist_id: int, show_id: int, count: int=20, page: int, fields: [str], expand: [str]}
@returns(200)

@endpoint POST /spins
@returns(201) {id: int, playlist_id: int, start: str(date-time), end: str(date-time), duration: int, timezone: str, image: str(url), classical: bool, artist: str, artist-custom: str, composer: str, release: str, release-custom: str, va: bool, label: str, label-custom: str, released: int, medium: str, genre: str, song: str, note: str, request: bool, local: bool, new: bool, work: str, conductor: str, performers: str, ensemble: str, catalog-number: str, isrc: str, upc: str, iswc: str, _links: map{self: map{href: str}, playlist: map{href: str}}}
@errors {422}

@endpoint GET /spins/{id}
@required {id: int}
@optional {fields: [str], expand: [str]}
@returns(200) {id: int, playlist_id: int, start: str(date-time), end: str(date-time), duration: int, timezone: str, image: str(url), classical: bool, artist: str, artist-custom: str, composer: str, release: str, release-custom: str, va: bool, label: str, label-custom: str, released: int, medium: str, genre: str, song: str, note: str, request: bool, local: bool, new: bool, work: str, conductor: str, performers: str, ensemble: str, catalog-number: str, isrc: str, upc: str, iswc: str, _links: map{self: map{href: str}, playlist: map{href: str}}}
@errors {404}

@endgroup

@end