@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Instagram API
@base https://api.instagram.com/v1
@version 1.0.0
@auth ApiKey access_token in query | OAuth2
@endpoints 27
@hint download_for_search
@toc geographies(1), locations(3), media(10), tags(3), users(10)

@group geographies
@endpoint GET /geographies/{geo-id}/media/recent
@desc Get recent media from a custom geo-id.
@required {geo-id: any # The geography ID.}
@optional {count: any # Max number of media to return., min_id: any # Return media before this `min_id`.}
@returns(200) List of recent media entries from a geography subscription.

@endgroup

@group locations
@endpoint GET /locations/search
@desc Search for a location by geographic coordinate.
@optional {distance: any # Default is 1000m (distance=1000), max distance is 5000., facebook_places_id: any # Returns a location mapped off of a Facebook places id. If used, a Foursquare id and `lat`, `lng` are not required., foursquare_id: any # Returns a location mapped off of a foursquare v1 api location id. If used, you are not required to use `lat` and `lng`. Note that this method is deprecated; you should use the new foursquare IDs with V2 of their API., lat: any # Latitude of the center search coordinate. If used, `lng` is required., lng: any # Longitude of the center search coordinate. If used, `lat` is required., foursquare_v2_id: any # Returns a location mapped off of a foursquare v2 api location id. If used, you are not required to use `lat` and `lng`.}
@returns(200) List of found locations.

@endpoint GET /locations/{location-id}
@desc Get information about a location.
@required {location-id: any # The location ID.}
@returns(200) Location information response.

@endpoint GET /locations/{location-id}/media/recent
@desc Get a list of recent media objects from a given location.
@required {location-id: any # The location ID.}
@optional {min_timestamp: any # Return media after this UNIX timestamp., max_timestamp: any # Return media before this UNIX timestamp., min_id: any # Return media before this `min_id`., max_id: any # Return media after this `max_id`.}
@returns(200) List of media entries from this location.

@endgroup

@group media
@endpoint GET /media/popular
@desc Get a list of currently popular media.
@returns(200) Found media resources (without likes information).

@endpoint GET /media/search
@desc Search for media in a given area.
@required {lat: any # Latitude of the center search coordinate. If used, `lng` is required., lng: any # Longitude of the center search coordinate. If used, `lat` is required.}
@optional {min_timestamp: any # A unix timestamp. All media returned will be taken later than this timestamp., max_timestamp: any # A unix timestamp. All media returned will be taken earlier than this timestamp., distance: any # Default is 1km (distance=1000), max distance is 5km.}
@returns(200) Found media resources (without likes information) in a given area.

@endpoint GET /media/shortcode/{shortcode}
@desc Get information about a media object.
@required {shortcode: any # The short code of the media resource.}
@returns(200) Media resource information.

@endpoint GET /media/{media-id}
@desc Get information about a media object.
@required {media-id: any # The ID of the media resource.}
@returns(200) Media resource information.

@endpoint GET /media/{media-id}/comments
@desc Get a list of recent comments on a media object.
@required {media-id: any # The ID of the media resource.}
@returns(200) List of comments of the media resource.

@endpoint POST /media/{media-id}/comments
@desc Create a comment on a media object.
@required {media-id: any # The ID of the media resource., text: any # Text to post as a comment on the media object as specified in `media-id`.}
@returns(200) Result of posting a comment.

@endpoint DELETE /media/{media-id}/comments/{comment-id}
@desc Remove a comment.
@required {media-id: any # The ID of the media resource., comment-id: any # The ID of the comment entry.}
@returns(200) Result of deleting a comment.

@endpoint DELETE /media/{media-id}/likes
@desc Remove a like on this media by the current user.
@required {media-id: any # The ID of the media resource.}
@returns(200) Result of removing a like.

@endpoint GET /media/{media-id}/likes
@desc Get a list of users who have liked this media.
@required {media-id: any # The ID of the media resource.}
@returns(200) List of users who liked the media resource.

@endpoint POST /media/{media-id}/likes
@desc Set a like on this media by the current user.
@required {media-id: any # The ID of the media resource.}
@returns(200) Result of setting a like.

@endgroup

@group tags
@endpoint GET /tags/search
@desc Search for tags by name.
@required {q: any # A valid tag name without a leading \#. (eg. snowy, nofilter)}
@returns(200) List of found tags and their statistics.

@endpoint GET /tags/{tag-name}
@desc Get information about a tag object.
@required {tag-name: any # The tag name.}
@returns(200) Tag information response.

@endpoint GET /tags/{tag-name}/media/recent
@desc Get a list of recently tagged media.
@required {tag-name: any # The tag name.}
@optional {count: any # Count of tagged media to return., min_tag_id: any # Return media before this `min_tag_id`., max_tag_id: any # Return media after this `max_tag_id`.}
@returns(200) List of media entries with this tag.

@endgroup

@group users
@endpoint GET /users/search
@desc Search for a user by name.
@required {q: any # A query string.}
@optional {count: any # Number of users to return.}
@returns(200) List of found users.

@endpoint GET /users/self/feed
@desc See the authenticated user's feed.
@optional {count: any # Count of media to return., min_id: any # Return media later than this `min_id`., max_id: any # Return media earlier than this `max_id`.}
@returns(200) Users feed entries.

@endpoint GET /users/self/media/liked
@desc See the list of media liked by the authenticated user.
@optional {count: any # Count of media to return., max_like_id: any # Return media liked before this id.}
@returns(200) Users media entries.

@endpoint GET /users/self/requested-by
@desc List the users who have requested this user's permission to follow.
@returns(200) List of users who have requested this user's permission to follow.

@endpoint GET /users/{user-id}
@desc Get basic information about a user.
@required {user-id: any # The ID of a user to get information about, or **self** to retrieve information about authenticated user.}
@returns(200) User basic information.
@errors {404: Not Found, user with such ID does not exist.}

@endpoint GET /users/{user-id}/followed-by
@desc Get the list of users this user is followed by.
@required {user-id: any # The ID of a user, or **self** to retrieve information about authenticated user.}
@returns(200) List of users this user is followed by.

@endpoint GET /users/{user-id}/follows
@desc Get the list of users this user follows.
@required {user-id: any # The ID of a user, or **self** to retrieve information about authenticated user.}
@returns(200) List of users this user follows.

@endpoint GET /users/{user-id}/media/recent
@desc Get the most recent media published by a user.
@required {user-id: any # The ID of a user to get recent media of, or **self** to retrieve media of authenticated user.}
@optional {count: any # Count of media to return., max_timestamp: any # Return media before this UNIX timestamp., min_timestamp: any # Return media after this UNIX timestamp., min_id: any # Return media later than this `min_id`., max_id: any # Return media earlier than this `max_id`.}
@returns(200) Users media entries.

@endpoint GET /users/{user-id}/relationship
@desc Get information about a relationship to another user.
@required {user-id: any # The ID of a user to get information about.}
@returns(200) Relationship information.

@endpoint POST /users/{user-id}/relationship
@desc Modify the relationship between the current user and the target user.
@required {user-id: any # The ID of the target user., action: any # Type of action to apply for relationship with the user.}
@returns(200) Relationship information.

@endgroup

@end