path: root/www/swagger/spec-files/instagram.yaml

---
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.

    All endpoints are only accessible via https and are located at
    `api.instagram.com`. For instance: you can grab the most popular photos at
    the moment by accessing the following URL with your client ID
    (replace CLIENT-ID with your own):
    ```
      https://api.instagram.com/v1/media/popular?client_id=CLIENT-ID
    ```
    You're best off using an access_token for the authenticated user for each
    endpoint, though many endpoints don't require it.
    In some cases an access_token will give you more access to information, and
    in all cases, it means that you are operating under a per-access_token limit
    vs. the same limit for your single client_id.


    ## Limits
    Be nice. If you're sending too many requests too quickly, we'll send back a
    `503` error code (server unavailable).
    You are limited to 5000 requests per hour per `access_token` or `client_id`
    overall. Practically, this means you should (when possible) authenticate
    users so that limits are well outside the reach of a given user.

    ## Deleting Objects
    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.

    ## Structure

    ### The Envelope
    Every response is contained by an envelope. That is, each response has a
    predictable set of keys with which you can expect to interact:
    ```json
    {
        "meta": {
            "code": 200
        },
        "data": {
            ...
        },
        "pagination": {
            "next_url": "...",
            "next_max_id": "13872296"
        }
    }
    ```

    #### META
    The meta key is used to communicate extra information about the response to
    the developer. If all goes well, you'll only ever see a code key with value
    200. However, sometimes things go wrong, and in that case you might see a
    response like:
    ```json
    {
        "meta": {
            "error_type": "OAuthException",
            "code": 400,
            "error_message": "..."
        }
    }
    ```

    #### DATA
    The data key is the meat of the response. It may be a list or dictionary,
    but either way this is where you'll find the data you requested.
    #### PAGINATION
    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.

    ### JSONP
    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({
        ...
    });
    ```
  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: 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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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
      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:
      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