--- swagger: '2.0' ################################################################################ # API Information # ################################################################################ info: version: v1 title: Instagram API description: | The first version of the Instagram API is an exciting step forward towards making it easier for users to have open access to their data. We created it so that you can surface the amazing content Instagram users share every second, in fun and innovative ways. Build something great! Once you've [registered your client](http://instagram.com/developer/register/) it's easy to start requesting data from Instagram. termsOfService: http://instagram.com/about/legal/terms/api ################################################################################ # Host, Base Path, Schemes and Content Types # ################################################################################ host: api.instagram.com basePath: /v1 schemes: - https produces: - application/json consumes: - application/json ################################################################################ # Tags # ################################################################################ tags: - name: JSONP x-secondaryTag: true description: | If you're writing an AJAX application, and you'd like to wrap our response with a callback, all you have to do is specify a callback parameter with any API call: ``` https://api.instagram.com/v1/tags/coffee/media/recent?access_token=fb2e77d.47a0479900504cb3ab4a1f626d174d2d&callback=callbackFunction ``` Would respond with: ```js callbackFunction({ ... }); ``` - name: Pagination x-secondaryTag: true description: | Sometimes you just can't get enough. For this reason, we've provided a convenient way to access more data in any request for sequential data. Simply call the url in the next_url parameter and we'll respond with the next set of data. ```json { ... "pagination": { "next_url": "https://api.instagram.com/v1/tags/puppy/media/recent?access_token=fb2e77d.47a0479900504cb3ab4a1f626d174d2d&max_id=13872296", "next_max_id": "13872296" } } ``` On views where pagination is present, we also support the "count" parameter. Simply set this to the number of items you'd like to receive. Note that the default values should be fine for most applications - but if you decide to increase this number there is a maximum value defined on each endpoint. - name: PUT & DELETE in old browsers x-secondaryTag: true description: | We do our best to have all our URLs be [RESTful](http://en.wikipedia.org/wiki/Representational_state_transfer). Every endpoint (URL) may support one of four different http verbs. GET requests fetch information about an object, POST requests create objects, PUT requests update objects, and finally DELETE requests will delete objects. Since many old browsers don't support PUT or DELETE, we've made it easy to fake PUTs and DELETEs. All you have to do is do a POST with _method=PUT or _method=DELETE as a parameter and we will treat it as if you used PUT or DELETE respectively. - name: Users - name: Relationships description: | Relationships are expressed using the following terms: **outgoing_status**: Your relationship to the user. Can be "follows", "requested", "none". **incoming_status**: A user's relationship to you. Can be "followed_by", "requested_by", "blocked_by_you", "none". - name: Media description: | At this time, uploading via the API is not possible. We made a conscious choice not to add this for the following reasons: * Instagram is about your life on the go – we hope to encourage photos from within the app. * We want to fight spam & low quality photos. Once we allow uploading from other sources, it's harder to control what comes into the Instagram ecosystem. All this being said, we're working on ways to ensure users have a consistent and high-quality experience on our platform. - name: Commnts - name: Likes - name: Tags - name: Location - name: Subscribtions ################################################################################ # Security # ################################################################################ securityDefinitions: oauth: type: oauth2 flow: implicit authorizationUrl: https://instagram.com/oauth/authorize/?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=token scopes: basic: | to read any and all data related to a user (e.g. following/followed-by lists, photos, etc.) (granted by default) comments: to create or delete comments on a user’s behalf relationships: to follow and unfollow users on a user’s behalf likes: to like and unlike items on a user’s behalf key: type: apiKey in: query name: access_token security: - oauth: - basic - comments - relationships - likes - key: [] ################################################################################ # Parameters # ################################################################################ parameters: user-id: name: user-id in: path description: The user identifier number type: number required: true tag-name: name: tag-name in: path description: Tag name type: string required: true ################################################################################ # Paths # ################################################################################ paths: /users/{user-id}: parameters: - $ref: '#/parameters/user-id' get: security: - key: [] - oauth: - basic tags: - Users - JSONP - Pagination description: Get basic information about a user. responses: 200: description: The user object schema: type: object properties: data: $ref: '#/definitions/User' /users/self/feed: get: tags: - Users - JSONP - Pagination description: See the authenticated user's feed. parameters: - name: count in: query description: Count of media to return. type: integer - name: max_id in: query description: Return media earlier than this max_id.s type: integer - name: min_id in: query description: Return media later than this min_id. type: integer responses: 200: description: OK schema: type: object properties: data: type: array items: $ref: '#/definitions/Media' /users/{user-id}/media/recent: parameters: - $ref: '#/parameters/user-id' get: tags: - Users - JSONP - Pagination responses: 200: description: | Get the most recent media published by a user. To get the most recent media published by the owner of the access token, you can use `self` instead of the `user-id`. schema: type: object properties: data: type: array items: $ref: '#/definitions/Media' parameters: - name: count in: query description: Count of media to return. type: integer - name: max_timestamp in: query description: Return media before this UNIX timestamp. type: integer - name: min_timestamp in: query description: Return media after this UNIX timestamp. type: integer - name: min_id in: query description: Return media later than this min_id. type: string - name: max_id in: query description: Return media earlier than this max_id. type: string /users/self/media/liked: get: tags: - Users - JSONP - Pagination description: | See the list of media liked by the authenticated user. Private media is returned as long as the authenticated user has permissionto view that media. Liked media lists are only available for the currently authenticated user. responses: 200: description: OK schema: type: object properties: data: type: array items: $ref: '#/definitions/Media' parameters: - name: count in: query description: Count of media to return. type: integer - name: max_like_id in: query description: Return media liked before this id. type: integer /users/search: get: tags: - Users - JSONP - Pagination description: Search for a user by name. parameters: - name: q in: query description: A query string type: string required: true - name: count in: query description: Number of users to return. type: string responses: 200: description: OK schema: type: object properties: data: type: array items: $ref: '#/definitions/MiniProfile' /users/{user-id}/follows: parameters: - $ref: '#/parameters/user-id' get: tags: - Relationships - JSONP - Pagination description: Get the list of users this user follows. responses: 200: description: OK schema: properties: data: type: array items: $ref: '#/definitions/MiniProfile' /users/{user-id}/followed-by: parameters: - $ref: '#/parameters/user-id' get: tags: - Relationships - JSONP - Pagination description: Get the list of users this user is followed by. responses: 200: description: OK schema: properties: data: type: array items: $ref: '#/definitions/MiniProfile' /users/self/requested-by: get: tags: - Relationships - JSONP - Pagination description: | List the users who have requested this user's permission to follow. responses: 200: description: OK schema: properties: meta: properties: code: type: integer data: type: array items: $ref: '#/definitions/MiniProfile' /users/{user-id}/relationship: parameters: - $ref: '#/parameters/user-id' post: tags: - Relationships - JSONP description: | Modify the relationship between the current user and thetarget user. security: - oauth: - relationships parameters: - name: action in: body description: One of follow/unfollow/block/unblock/approve/ignore. schema: type: string enum: - follow - unfollow - block - unblock - approve responses: 200: description: OK schema: properties: data: type: array items: $ref: '#/definitions/MiniProfile' /media/{media-id}: parameters: - name: media-id in: path description: The media ID type: integer required: true get: tags: - Media - JSONP - Pagination description: | Get information about a media object. The returned type key will allow you to differentiate between `image` and `video` media. Note: if you authenticate with an OAuth Token, you will receive the `user_has_liked` key which quickly tells you whether the current user has liked this media item. responses: 200: description: OK schema: $ref: '#/definitions/Media' /media1/{shortcode}: #FIXME: correct path is /media/{shortcode} parameters: - name: shortcode in: path description: The media shortcode type: string required: true get: tags: - Media - JSONP - Pagination description: | This endpoint returns the same response as **GET** `/media/media-id`. A media object's shortcode can be found in its shortlink URL. An example shortlink is `http://instagram.com/p/D/` Its corresponding shortcode is D. responses: 200: description: OK schema: $ref: '#/definitions/Media' /media/search: get: tags: - Media - JSONP - Pagination description: | Search for media in a given area. The default time span is set to 5 days. The time span must not exceed 7 days. Defaults time stamps cover the last 5 days. Can return mix of image and video types. parameters: - name: LAT description: | Latitude of the center search coordinate. If used, lng is required. type: number in: query - name: MIN_TIMESTAMP description: | A unix timestamp. All media returned will be taken later than this timestamp. type: integer in: query - name: LNG description: | Longitude of the center search coordinate. If used, lat is required. type: number in: query - name: MAX_TIMESTAMP description: | A unix timestamp. All media returned will be taken earlier than this timestamp. type: integer in: query - name: DISTANCE description: Default is 1km (distance=1000), max distance is 5km. type: integer maximum: 5000 default: 1000 in: query responses: 200: description: OK schema: type: object description: List of all media with added `distance` property properties: data: type: array items: allOf: - $ref: '#/definitions/Media' - properties: distance: type: number /media/popular: get: tags: - Media - JSONP - Pagination description: | Get a list of what media is most popular at the moment. Can return mix of image and video types. responses: 200: description: OK schema: type: object properties: data: type: array items: $ref: '#/definitions/Media' /media/{media-id}/comments: parameters: - name: media-id in: path description: Media ID type: integer required: true get: tags: - Comments - JSONP - Pagination description: | Get a list of recent comments on a media object. responses: 200: description: OK schema: properties: meta: properties: code: type: number data: type: array items: $ref: '#/definitions/Comment' post: tags: - Comments - Media - JSONP description: | Create a comment on a media object with the following rules: * The total length of the comment cannot exceed 300 characters. * The comment cannot contain more than 4 hashtags. * The comment cannot contain more than 1 URL. * The comment cannot consist of all capital letters. security: - oauth: - comments parameters: - name: TEXT description: | Text to post as a comment on the media object as specified in media-id. in: body schema: type: number responses: 200: description: OK schema: type: object properties: meta: properties: code: type: number data: type: object delete: tags: - Comments - PUT & DELETE in old browsers description: | Remove a comment either on the authenticated user's media object or authored by the authenticated user. responses: 200: description: OK schema: type: object properties: meta: properties: code: type: number data: type: object /media/{media-id}/likes: parameters: - name: media-id in: path description: Media ID type: integer required: true get: tags: - Likes - Media - JSONP - Pagination description: | Get a list of users who have liked this media. responses: 200: description: OK schema: properties: meta: properties: code: type: number data: type: array items: $ref: '#/definitions/Like' post: tags: - Likes description: Set a like on this media by the currently authenticated user. security: - oauth: - comments responses: 200: description: OK schema: type: object properties: meta: properties: code: type: number data: type: object delete: tags: - Likes - PUT & DELETE in old browsers description: | Remove a like on this media by the currently authenticated user. responses: 200: description: OK schema: type: object properties: meta: properties: code: type: number data: type: object /tags/{tag-name}: parameters: - $ref: '#/parameters/tag-name' get: tags: - Tags - JSONP - Pagination description: Get information about a tag object. responses: 200: description: OK schema: $ref: '#/definitions/Tag' /tags/{tag-name}/media/recent: parameters: - $ref: '#/parameters/tag-name' get: tags: - Tags - JSONP - Pagination description: | Get a list of recently tagged media. Use the `max_tag_id` and `min_tag_id` parameters in the pagination response to paginate through these objects. responses: 200: description: OK schema: properties: data: type: array items: $ref: '#/definitions/Tag' /tags/search: get: tags: - Tags - JSONP - Pagination parameters: - name: q description: | A valid tag name without a leading #. (eg. snowy, nofilter) in: query type: string responses: 200: description: OK schema: type: object properties: meta: properties: code: type: integer data: type: array items: $ref: '#/definitions/Tag' /locations/{location-id}: parameters: - name: location-id description: Location ID in: path type: integer required: true get: tags: - Location - JSONP - Pagination description: Get information about a location. responses: 200: description: OK schema: type: object properties: data: $ref: '#/definitions/Location' /locations/{location-id}/media/recent: parameters: - name: location-id description: Location ID in: path type: integer required: true get: tags: - Location - Media - JSONP - Pagination description: Get a list of recent media objects from a given location. parameters: - name: max_timestamp in: query description: Return media before this UNIX timestamp. type: integer - name: min_timestamp in: query description: Return media after this UNIX timestamp. type: integer - name: min_id in: query description: Return media later than this min_id. type: string - name: max_id in: query description: Return media earlier than this max_id. type: string responses: 200: description: OK schema: type: object properties: data: type: array items: $ref: '#/definitions/Media' /locations/search: get: tags: - Location - JSONP - Pagination description: Search for a location by geographic coordinate. parameters: - name: distance in: query description: Default is 1000m (distance=1000), max distance is 5000. type: integer - name: facebook_places_id in: query description: | Returns a location mapped off of a Facebook places id. If used, a Foursquare id and lat, lng are not required. type: integer - name: foursquare_id in: query description: | 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. type: integer - name: lat in: query description: | atitude of the center search coordinate. If used, lng is required. type: number - name: lng in: query description: | ongitude of the center search coordinate. If used, lat is required. type: number - name: foursquare_v2_id in: query description: | Returns a location mapped off of a foursquare v2 api location id. If used, you are not required to use lat and lng. type: integer responses: 200: description: OK schema: type: object properties: data: type: array items: $ref: '#/definitions/Location' /geographies/{geo-id}/media/recent: parameters: - name: geo-id in: path description: Geolocation ID type: integer required: true get: tags: - Media - JSONP - Pagination description: | Get recent media from a geography subscription that you created. **Note**: You can only access Geographies that were explicitly created by your OAuth client. Check the Geography Subscriptions section of the [real-time updates page](https://instagram.com/developer/realtime/). When you create a subscription to some geography that you define, you will be returned a unique geo-id that can be used in this query. To backfill photos from the location covered by this geography, use the [media search endpoint ](https://instagram.com/developer/endpoints/media/). parameters: - name: count in: query description: Max number of media to return. type: integer - name: min_id in: query description: Return media before this `min_id`. type: integer responses: 200: description: OK ################################################################################ # Definitions # ################################################################################ definitions: User: type: object properties: id: type: integer username: type: string full_name: type: string profile_picture: type: string bio: type: string website: type: string counts: type: object properties: media: type: integer follows: type: integer follwed_by: type: integer Media: type: object properties: created_time: description: Epoc time (ms) type: integer type: type: string filter: type: string tags: type: array items: $ref: '#/definitions/Tag' id: type: integer user: $ref: '#/definitions/MiniProfile' users_in_photo: type: array items: $ref: '#/definitions/MiniProfile' location: $ref: '#/definitions/Location' comments:: type: object properties: count: type: integer data: type: array items: $ref: '#/definitions/Comment' likes: type: object properties: count: type: integer data: type: array items: $ref: '#/definitions/MiniProfile' images: properties: low_resolution: $ref: '#/definitions/Image' thumbnail: $ref: '#/definitions/Image' standard_resolution: $ref: '#/definitions/Image' videos: properties: low_resolution: $ref: '#/definitions/Image' standard_resolution: $ref: '#/definitions/Image' Location: type: object properties: id: type: string name: type: string latitude: type: number longitude: type: number Comment: type: object properties: id: type: string created_time: type: string text: type: string from: $ref: '#/definitions/MiniProfile' Like: type: object properties: user_name: type: string first_name: type: string last_name: type: string type: type: string id: type: string Tag: type: object properties: media_count: type: integer name: type: string Image: type: object properties: width: type: integer height: type: integer url: type: string MiniProfile: type: object description: A shorter version of User for likes array properties: user_name: type: string full_name: type: string id: type: integer profile_picture: type: string