@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api TVmaze user API
@base https://api.tvmaze.com/v1
@version 1.0
@auth basic
@endpoints 42
@hint download_for_search
@toc user(35), scrobble(4), auth(3)

@group user
@endpoint GET /user/episodes
@desc List the marked episodes
@optional {show_id: any # Only return episodes from this specific show}
@returns(200) An array of marked episodes

@endpoint GET /user/episodes/{episode_id}
@desc Check if an episode is marked
@returns(200) The marked episode
@errors {404: This episode is not marked}

@endpoint PUT /user/episodes/{episode_id}
@desc Mark an episode
@optional {body: map}
@returns(200) this episode is now marked
@errors {404: this episode does not exist, 422: invalid input data}

@endpoint DELETE /user/episodes/{episode_id}
@desc Unmark an episode
@returns(200) the episode is now unmarked
@errors {404: this episode was not marked}

@endpoint GET /user/follows/shows
@desc List the followed shows
@optional {embed: any # Embed full show info}
@returns(200) An array of followed shows

@endpoint GET /user/follows/shows/{show_id}
@desc Check if a show is followed
@returns(200) The followed show
@errors {404: This show is not followed}

@endpoint PUT /user/follows/shows/{show_id}
@desc Follow a show
@returns(200) This show is now followed
@errors {404: This show does not exist}

@endpoint DELETE /user/follows/shows/{show_id}
@desc Unfollow a show
@returns(200) The show is now unfollowed
@errors {404: This show was not followed}

@endpoint GET /user/follows/people
@desc List the followed people
@optional {embed: any # Embed full person info}
@returns(200) An array of followed people

@endpoint GET /user/follows/people/{person_id}
@desc Check if a person is followed
@returns(200) The followed person
@errors {404: this person is not followed}

@endpoint PUT /user/follows/people/{person_id}
@desc Follow a person
@returns(200) this person is now followed
@errors {404: this person does not exist}

@endpoint DELETE /user/follows/people/{person_id}
@desc Unfollow a person
@returns(200) the person is now unfollowed
@errors {404: this person was not followed}

@endpoint GET /user/follows/networks
@desc List the followed networks
@optional {embed: any # Embed full network info}
@returns(200) An array of followed networks

@endpoint GET /user/follows/networks/{network_id}
@desc Check if a network is followed
@returns(200) The followed network
@errors {404: this network is not followed}

@endpoint PUT /user/follows/networks/{network_id}
@desc Follow a network
@returns(200) this network is now followed
@errors {404: this network does not exist}

@endpoint DELETE /user/follows/networks/{network_id}
@desc Unfollow a network
@returns(200) the network is now unfollowed
@errors {404: this network was not followed}

@endpoint GET /user/follows/webchannels
@desc List the followed webchannels
@optional {embed: any # Embed full webchannel info}
@returns(200) An array of followed webchannels

@endpoint GET /user/follows/webchannels/{webchannel_id}
@desc Check if a webchannel is followed
@returns(200) The followed webchannel
@errors {404: this webchannel is not followed}

@endpoint PUT /user/follows/webchannels/{webchannel_id}
@desc Follow a webchannel
@returns(200) this webchannel is now followed
@errors {404: this webchannel does not exist}

@endpoint DELETE /user/follows/webchannels/{webchannel_id}
@desc Unfollow a webchannel
@returns(200) the webchannel is now unfollowed
@errors {404: this webchannel was not followed}

@endpoint GET /user/tags
@desc List all tags
@returns(200) An array of tags

@endpoint POST /user/tags
@desc Create a new tag
@optional {body: map}
@returns(200) The newly created tag
@errors {422: invalid input data}

@endpoint DELETE /user/tags/{tag_id}
@desc Delete a specific tag
@required {tag_id: any}
@returns(200) The tag was deleted
@errors {404: The tag does not exist}

@endpoint PATCH /user/tags/{tag_id}
@desc Update a specific tag
@required {tag_id: any}
@optional {body: map}
@returns(200) The tag was updated
@errors {404: The tag does not exist, 422: The tag could not be updated}

@endpoint GET /user/tags/{tag_id}/shows
@desc List all shows under this tag
@required {tag_id: any}
@optional {embed: any # Embed full show info}
@returns(200) A list of tagged shows
@errors {404: The tag does not exist}

@endpoint PUT /user/tags/{tag_id}/shows/{show_id}
@desc Tag a show
@required {tag_id: any, show_id: any}
@returns(200) The show was tagged
@errors {404: The show or tag does not exist}

@endpoint DELETE /user/tags/{tag_id}/shows/{show_id}
@desc Untag a show
@required {tag_id: any, show_id: any}
@returns(200) The show was untagged
@errors {404: The show was not tagged}

@endpoint GET /user/votes/shows
@desc List the shows voted for
@optional {embed: any # Embed full show info}
@returns(200) An array of show votes

@endpoint GET /user/votes/shows/{show_id}
@desc Check if a show is voted for
@returns(200) The show vote
@errors {404: This show is not voted for}

@endpoint PUT /user/votes/shows/{show_id}
@desc Vote for a show
@optional {body: map}
@returns(200) This show is now voted for
@errors {404: This show does not exist, 422: Invalid vote}

@endpoint DELETE /user/votes/shows/{show_id}
@desc Remove a show vote
@returns(200) The show vote is now removed
@errors {404: This show was not voted for}

@endpoint GET /user/votes/episodes
@desc List the episodes voted for
@returns(200) An array of episode votes

@endpoint GET /user/votes/episodes/{episode_id}
@desc Check if an episode is voted for
@returns(200) The episode vote
@errors {404: This episode is not voted for}

@endpoint PUT /user/votes/episodes/{episode_id}
@desc Vote for an episode
@optional {body: map}
@returns(200) This episode is now voted for
@errors {404: This episode does not exist, 422: Invalid vote}

@endpoint DELETE /user/votes/episodes/{episode_id}
@desc Remove an episode vote
@returns(200) The episode vote is now removed
@errors {404: This episode was not voted for}

@endgroup

@group scrobble
@endpoint GET /scrobble/shows/{show_id}
@desc List watched and acquired episodes for a show
@returns(200) An array of marked episodes

@endpoint PUT /scrobble/episodes/{episode_id}
@desc Mark an episode as acquired or watched based on its ID
@optional {body: map}
@returns(200) this episode is now marked
@errors {404: this episode does not exist, 422: invalid input data}

@endpoint POST /scrobble/shows
@desc Mark episodes within a show as acquired or watched based on their attributes
@optional {tvmaze_id: any # The show's TVmaze ID, thetvdb_id: any # The show's TheTVDB ID, imdb_id: any # The show's IMDB ID, episodes: [map]}
@returns(200) All episodes were succesfully marked
@returns(207) Some episodes were succesfully marked, but there are errors
@errors {422: None of the episodes were succesfully marked}

@endpoint POST /scrobble/episodes
@desc Mark episodes as acquired or watched based on their IDs
@optional {episodes: [map]}
@returns(200) All episodes were succesfully marked
@returns(207) Some episodes were succesfully marked, but there are errors
@errors {422: None of the episodes were succesfully marked}

@endgroup

@group auth
@endpoint POST /auth/start
@desc Start an authentication request
@required {body: map}
@returns(200) The authentication request was succesfully started
@errors {401: The email address was found, but not confirmed, 404: The email address was not found, 429: You are starting authentication requests too quickly, please back off}

@endpoint POST /auth/poll
@desc Poll whether an authentication request was confirmed
@required {body: map}
@returns(200) The user confirmed the authentication request
@errors {403: The authentication request was not confirmed yet, 404: The authentication request was not found, 429: You are polling too quickly, please back off}

@endpoint GET /auth/validate
@desc Validate your authentication credentials
@returns(200) The supplied credentials are valid
@errors {401: The supplied credentials are not valid}

@endgroup

@end