API Reference

Serializations

Responses from the MLTSHP API are application/json responses that represent the various MLTSHP API objects. Those objects are:

shake

A shake is a stream of files posted to MLTSHP by users. Shakes can be user shakes, which every user has one of, or group shakes that can have multiple posters.

Contents:
  • id – the shake’s numeric shake ID as a number
  • name – the display title of the shake
  • owner – the user who created the shake
  • url – the URL of the shake on the MLTSHP site
  • thumbnail_url – the URL of the shake’s thumbnail logo image
  • description – the shake’s description displayed under its logo on its page (optional)
  • type – the type of shake: either user or group
  • created_at – the time when the shake was first created
  • updated_at – the time when the shake was last updated
sharedfile

A file that someone posted to a shake. A file can be either an image or a link to a video.

Contents:
  • sharekey – the sharekey of the shared file
  • name – the filename of the shared file
  • user – the user who shared the file
  • title – the custom title the poster gave the file (optional)
  • description – the caption displayed under the file on its page (optional)
  • posted_at – the time the file was posted
  • permalink_page – the URL where the file can be viewed on MLTSHP
  • width – the width of the file (image or video embed) in pixels as a number
  • height – the height of the file (image or video embed) in pixels as a number
  • views – the number of times the image has been viewed
  • likes – the number of times the image has been “liked” to someone’s favorites
  • saves – the number of times the image has been saved to another shake
  • comments – the number of comments on the file
  • nsfw – whether the file has been marked NSFW, and so is hidden by default when displayed on MLTSHP (true for NSFW/hidden, false for SFW/visible)
  • original_image_url – if the file is an image, the URL of the image on MLTSHP
  • url – if the file is not an image, the original URL of the shared item
  • pivot_id – a key that is used for pagination. It varies based on the API method.
  • saved – flag indicating whether authenticated user has already saved the sharedfile
  • liked – flag indicating whether authenticated user has already liked the sharedfile
sharekey

The alphanumeric ID of a sharedfile, such as GK4N. These are the codes in the permalink page (and image URL) of files posted to MLTSHP.

timestamp

Timestamps represent particular times when events occurred, such as users posting files to shakes. Timestamps are always represented in the MLTSHP API as ISO8601 timestamps in UTC (where the timezone is Z) with resolution to seconds (no microseconds).

user

A person with a MLTSHP account. Users own or manage shakes and post files in them.

Contents:
  • id – the user’s numeric user ID as a number
  • name – the user’s username
  • profile_image_url – the URL to the user’s profile picture
  • about – a brief text blurb about the user. Only available when querying the user resource.
  • website – the user’s URL. Only available when querying the user resource.
  • shakes – the list of shakes that belong to the user, including their main user shake. Only available when querying the user resource.
comment

A traditional comment associated with a sharedfile.

Contents:
  • body – the actual text body of the comment
  • user – the user that posted the comment
  • posted_at – the time when the comment was posted

Resources

The resources (URL endpoints) in the MLTSHP API are:

GET /api/favorites
GET /api/favorites/before/(beforekey)
GET /api/favorites/after/(afterkey)

Returns the files the authorized user has “liked” most recently (or as specified).

Use the before/beforekey and after/afterkey variations to page through the user’s favorites. That is, specify the last pivot_id as the key to the before/beforekey resource to get the page of files the user “liked” before the current page.

Parameters:
  • beforekey – the pivot_id of the file to show posts before
  • afterkey – the pivot_id of the file to show posts after
Status Codes:
  • 200 OK –

    the response is the requested section of the user’s favorites as an object containing:

GET /api/friends
GET /api/friends/before/(beforekey)
GET /api/friends/after/(afterkey)

Returns the files posted most recently (or as specified) by the users whom the authorized user follows.

Use the before/beforekey and after/afterkey variations to page through the user’s friend shake. That is, to request the next page of a friend shake, specify the last pivot_id in the current page as the key to a /api/friends/before/beforekey request.

Parameters:
  • beforekey – the pivot_id of the post to show posts before
  • afterkey – the pivot_id of the post to show posts after
Status Codes:
  • 200 OK –

    the response is the requested section of friend shake as an object containing:

GET /api/magicfiles
GET /api/magicfiles/before/(beforekey)
GET /api/magicfiles/after/(afterkey)

Returns the 10 most recent files accepted by the “magic” file selection algorithm. Currently any files with 10 or more likes are magic.

Use the before/beforekey and after/afterkey variations to page through the sharedfiles. That is, specify the last pivot_id as the key to the before/beforekey resource to get the page of files saved before the current page.

Parameters:
  • beforekey – the pivot_id of the file to show posts before
  • afterkey – the pivot_id of the file to show posts after
Status Codes:
  • 200 OK –

    the response is the latest magic files as an object containing:

GET /api/incoming
GET /api/incoming/before/(beforekey)
GET /api/incoming/after/(afterkey)

Returns the 10 most recently posted sharedfiles.

Use the before/beforekey and after/afterkey variations to page through the sharedfiles. That is, specify the last pivot_id as the key to the before/beforekey resource to get the page of files saved before the current page.

Parameters:
  • beforekey – the pivot_id of the file to show posts before
  • afterkey – the pivot_id of the file to show posts after
Status Codes:
  • 200 OK –

    the response is the latest files as an object containing:

GET /api/shakes/(id)
GET /api/shakes/(id)/before/(beforekey)
GET /api/shakes/(id)/after/(afterkey)

Returns the sharedfiles for the specified shake in reverse chronological order.

Use the before/beforekey and after/afterkey variations to page through the sharefiles. That is, specify the last pivot_id as the key to the before/beforekey resource to get the page of files saved before the current page.

Parameters:
  • beforekey – the pivot_id of the file to show posts before
  • afterkey – the pivot_id of the file to show posts after
Status Codes:
GET /api/shake_id/(int: shakeid)

Returns information for the shake with the given numeric shake ID.

Parameters:
  • shakeid – the shake’s numeric ID
Status Codes:
GET /api/shake_name/(shakepathname)

Returns information for the shake with the given pathname.

Note that name in this case refers to the URL path to the shake. e.g., for https://mltshp.com/weloveamberandandre the pathname is weloveamberandandre.

Parameters:
  • shakepathname – the shake’s pathname
Status Codes:
GET /api/shake_user/(username)

Returns information for the shake belonging to the specified user.

Parameters:
  • username – the user’s username
Status Codes:
GET /api/shakes

Returns the authorized user’s shakes.

Status Codes:
GET /api/sharedfile/(sharekey)

Returns information for the file with the given share key.

Parameters:
Status Codes:
POST /api/sharedfile/(sharekey)

Update sharedfile’s editable details.

Parameters:
Form Parameters:
 
  • title – text for the image title (optional)
  • description – text for the image description (optional)
Status Codes:
POST /api/sharedfile/(sharekey)/like

“Likes” the file with the given sharekey as the authorized user. The file is then available in the user’s favorites.

Parameters:
  • sharekey – the sharekey of the file to like
Status Codes:
  • 200 OK – the file was liked, and the response is the liked sharedfile
  • 400 Bad Request – the file could not be liked, probably because the authorized user already liked it
  • 404 Not Found – no such file with that share key
POST /api/sharedfile/(sharekey)/save

“Saves” the file with the given sharekey as the authorized user. By default the file is saved to the user’s shake unless the shake_id parameter is provided.

Parameters:
  • sharekey – the sharekey of the file to save
Form Parameters:
 
  • shake_id – the id of the destination shake the file should be saved to (optional)
Status Codes:
  • 200 OK – the file was saved, and the response is the saved sharedfile
  • 400 Bad Request – the file could not be saved, probably because the file belongs to the authenticated user
  • 403 Forbidden – the file could not be saved due to permission issues
  • 404 Not Found – no such file with that share key or no such shake
GET /api/sharedfile/(sharekey)/comments

Returns a list of comments for the sharedfile with the given sharekey.

Parameters:
Status Codes:
POST /api/sharedfile/(sharekey)/comments

Posts a new comment on behalf of the authenticated user to the sharedfile referenced with the given sharekey.

Parameters:
Form Parameters:
 
  • body – the text contents of the comment
Status Codes:
POST /api/upload

Adds the submitted image to a shake. Images should be provided as multipart/form-data request bodies.

Form Parameters:
 
  • file – the file data of the image to upload
  • shake_id – numeric ID of the shake to post to (optional)
  • title – text for the image title (optional)
  • description – text for the image description (optional)
Status Codes:
GET /api/user

Returns the authorized user.

Status Codes:
GET /api/user_id/(int: userid)

Returns information for the user with the given numeric user ID.

Parameters:
  • userid (int) – the user’s numeric ID
Status Codes:
GET /api/user_name/(username)

Returns the user with the given username.

Parameters:
  • username – the user’s username
Status Codes: