1--- 2swagger: '2.0' 3 4################################################################################ 5# API Information # 6################################################################################ 7info: 8 version: v1 9 title: Instagram API 10 description: | 11 The first version of the Instagram API is an exciting step forward towards 12 making it easier for users to have open access to their data. We created it 13 so that you can surface the amazing content Instagram users share every 14 second, in fun and innovative ways. 15 16 Build something great! 17 18 Once you've 19 [registered your client](http://instagram.com/developer/register/) it's easy 20 to start requesting data from Instagram. 21 22 All endpoints are only accessible via https and are located at 23 `api.instagram.com`. For instance: you can grab the most popular photos at 24 the moment by accessing the following URL with your client ID 25 (replace CLIENT-ID with your own): 26 ``` 27 https://api.instagram.com/v1/media/popular?client_id=CLIENT-ID 28 ``` 29 You're best off using an access_token for the authenticated user for each 30 endpoint, though many endpoints don't require it. 31 In some cases an access_token will give you more access to information, and 32 in all cases, it means that you are operating under a per-access_token limit 33 vs. the same limit for your single client_id. 34 35 36 ## Limits 37 Be nice. If you're sending too many requests too quickly, we'll send back a 38 `503` error code (server unavailable). 39 You are limited to 5000 requests per hour per `access_token` or `client_id` 40 overall. Practically, this means you should (when possible) authenticate 41 users so that limits are well outside the reach of a given user. 42 43 ## Deleting Objects 44 We do our best to have all our URLs be 45 [RESTful](http://en.wikipedia.org/wiki/Representational_state_transfer). 46 Every endpoint (URL) may support one of four different http verbs. GET 47 requests fetch information about an object, POST requests create objects, 48 PUT requests update objects, and finally DELETE requests will delete 49 objects. 50 51 Since many old browsers don't support PUT or DELETE, we've made it easy to 52 fake PUTs and DELETEs. All you have to do is do a POST with _method=PUT or 53 _method=DELETE as a parameter and we will treat it as if you used PUT or 54 DELETE respectively. 55 56 ## Structure 57 58 ### The Envelope 59 Every response is contained by an envelope. That is, each response has a 60 predictable set of keys with which you can expect to interact: 61 ```json 62 { 63 "meta": { 64 "code": 200 65 }, 66 "data": { 67 ... 68 }, 69 "pagination": { 70 "next_url": "...", 71 "next_max_id": "13872296" 72 } 73 } 74 ``` 75 76 #### META 77 The meta key is used to communicate extra information about the response to 78 the developer. If all goes well, you'll only ever see a code key with value 79 200. However, sometimes things go wrong, and in that case you might see a 80 response like: 81 ```json 82 { 83 "meta": { 84 "error_type": "OAuthException", 85 "code": 400, 86 "error_message": "..." 87 } 88 } 89 ``` 90 91 #### DATA 92 The data key is the meat of the response. It may be a list or dictionary, 93 but either way this is where you'll find the data you requested. 94 #### PAGINATION 95 Sometimes you just can't get enough. For this reason, we've provided a 96 convenient way to access more data in any request for sequential data. 97 Simply call the url in the next_url parameter and we'll respond with the 98 next set of data. 99 ```json 100 { 101 ... 102 "pagination": { 103 "next_url": "https://api.instagram.com/v1/tags/puppy/media/recent?access_token=fb2e77d.47a0479900504cb3ab4a1f626d174d2d&max_id=13872296", 104 "next_max_id": "13872296" 105 } 106 } 107 ``` 108 On views where pagination is present, we also support the "count" parameter. 109 Simply set this to the number of items you'd like to receive. Note that the 110 default values should be fine for most applications - but if you decide to 111 increase this number there is a maximum value defined on each endpoint. 112 113 ### JSONP 114 If you're writing an AJAX application, and you'd like to wrap our response 115 with a callback, all you have to do is specify a callback parameter with 116 any API call: 117 ``` 118 https://api.instagram.com/v1/tags/coffee/media/recent?access_token=fb2e77d.47a0479900504cb3ab4a1f626d174d2d&callback=callbackFunction 119 ``` 120 Would respond with: 121 ```js 122 callbackFunction({ 123 ... 124 }); 125 ``` 126 termsOfService: http://instagram.com/about/legal/terms/api 127 128################################################################################ 129# Host, Base Path, Schemes and Content Types # 130################################################################################ 131host: api.instagram.com 132basePath: /v1 133schemes: 134 - https 135produces: 136 - application/json 137consumes: 138 - application/json 139 140################################################################################ 141# Tags # 142################################################################################ 143tags: 144 - name: Users 145 - name: Relationships 146 description: | 147 Relationships are expressed using the following terms: 148 149 **outgoing_status**: Your relationship to the user. Can be "follows", 150 "requested", "none". 151 **incoming_status**: A user's relationship to you. Can be "followed_by", 152 "requested_by", "blocked_by_you", "none". 153 - name: Media 154 description: | 155 At this time, uploading via the API is not possible. We made a conscious 156 choice not to add this for the following reasons: 157 158 * Instagram is about your life on the go – we hope to encourage photos 159 from within the app. 160 * We want to fight spam & low quality photos. Once we allow uploading 161 from other sources, it's harder to control what comes into the Instagram 162 ecosystem. All this being said, we're working on ways to ensure users 163 have a consistent and high-quality experience on our platform. 164 - name: Commnts 165 - name: Likes 166 - name: Tags 167 - name: Location 168 - name: Subscribtions 169 170################################################################################ 171# Security # 172################################################################################ 173securityDefinitions: 174 oauth: 175 type: oauth2 176 flow: implicit 177 authorizationUrl: https://instagram.com/oauth/authorize/?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=token 178 scopes: 179 basic: | 180 to read any and all data related to a user (e.g. following/followed-by 181 lists, photos, etc.) (granted by default) 182 comments: to create or delete comments on a user’s behalf 183 relationships: to follow and unfollow users on a user’s behalf 184 likes: to like and unlike items on a user’s behalf 185 key: 186 type: apiKey 187 in: query 188 name: access_token 189security: 190 - oauth: 191 - basic 192 - comments 193 - relationships 194 - likes 195 - key: [] 196 197################################################################################ 198# Parameters # 199################################################################################ 200parameters: 201 user-id: 202 name: user-id 203 in: path 204 description: The user identifier number 205 type: number 206 required: true 207 tag-name: 208 name: tag-name 209 in: path 210 description: Tag name 211 type: string 212 required: true 213 214################################################################################ 215# Paths # 216################################################################################ 217paths: 218 /users/{user-id}: 219 parameters: 220 - $ref: '#/parameters/user-id' 221 get: 222 security: 223 - key: [] 224 - oauth: 225 - basic 226 tags: 227 - Users 228 description: Get basic information about a user. 229 responses: 230 200: 231 description: The user object 232 schema: 233 type: object 234 properties: 235 data: 236 $ref: '#/definitions/User' 237 238 /users/self/feed: 239 get: 240 tags: 241 - Users 242 description: See the authenticated user's feed. 243 parameters: 244 - name: count 245 in: query 246 description: Count of media to return. 247 type: integer 248 - name: max_id 249 in: query 250 description: Return media earlier than this max_id.s 251 type: integer 252 - name: min_id 253 in: query 254 description: Return media later than this min_id. 255 256 type: integer 257 responses: 258 200: 259 description: OK 260 schema: 261 type: object 262 properties: 263 data: 264 type: array 265 items: 266 $ref: '#/definitions/Media' 267 268 /users/{user-id}/media/recent: 269 parameters: 270 - $ref: '#/parameters/user-id' 271 get: 272 tags: 273 - Users 274 responses: 275 200: 276 description: | 277 Get the most recent media published by a user. To get the most recent 278 media published by the owner of the access token, you can use `self` 279 instead of the `user-id`. 280 schema: 281 type: object 282 properties: 283 data: 284 type: array 285 items: 286 $ref: '#/definitions/Media' 287 parameters: 288 - name: count 289 in: query 290 description: Count of media to return. 291 type: integer 292 - name: max_timestamp 293 in: query 294 description: Return media before this UNIX timestamp. 295 type: integer 296 - name: min_timestamp 297 in: query 298 description: Return media after this UNIX timestamp. 299 type: integer 300 - name: min_id 301 in: query 302 description: Return media later than this min_id. 303 type: string 304 - name: max_id 305 in: query 306 description: Return media earlier than this max_id. 307 type: string 308 309 /users/self/media/liked: 310 get: 311 tags: 312 - Users 313 description: | 314 See the list of media liked by the authenticated user. 315 Private media is returned as long as the authenticated user 316 has permissionto view that media. Liked media lists are only 317 available for the currently authenticated user. 318 responses: 319 200: 320 description: OK 321 schema: 322 type: object 323 properties: 324 data: 325 type: array 326 items: 327 $ref: '#/definitions/Media' 328 parameters: 329 - name: count 330 in: query 331 description: Count of media to return. 332 type: integer 333 - name: max_like_id 334 in: query 335 description: Return media liked before this id. 336 type: integer 337 338 /users/search: 339 get: 340 tags: 341 - Users 342 description: Search for a user by name. 343 parameters: 344 - name: q 345 in: query 346 description: A query string 347 type: string 348 required: true 349 - name: count 350 in: query 351 description: Number of users to return. 352 type: string 353 responses: 354 200: 355 description: OK 356 schema: 357 type: object 358 properties: 359 data: 360 type: array 361 items: 362 $ref: '#/definitions/MiniProfile' 363 364 /users/{user-id}/follows: 365 parameters: 366 - $ref: '#/parameters/user-id' 367 get: 368 tags: 369 - Relationships 370 description: Get the list of users this user follows. 371 responses: 372 200: 373 description: OK 374 schema: 375 properties: 376 data: 377 type: array 378 items: 379 $ref: '#/definitions/MiniProfile' 380 381 /users/{user-id}/followed-by: 382 parameters: 383 - $ref: '#/parameters/user-id' 384 get: 385 tags: 386 - Relationships 387 description: Get the list of users this user is followed by. 388 responses: 389 200: 390 description: OK 391 schema: 392 properties: 393 data: 394 type: array 395 items: 396 $ref: '#/definitions/MiniProfile' 397 398 /users/self/requested-by: 399 get: 400 tags: 401 - Relationships 402 description: | 403 List the users who have requested this user's permission to follow. 404 responses: 405 200: 406 description: OK 407 schema: 408 properties: 409 meta: 410 properties: 411 code: 412 type: integer 413 data: 414 type: array 415 items: 416 $ref: '#/definitions/MiniProfile' 417 418 /users/{user-id}/relationship: 419 parameters: 420 - $ref: '#/parameters/user-id' 421 post: 422 tags: 423 - Relationships 424 description: | 425 Modify the relationship between the current user and thetarget user. 426 security: 427 - oauth: 428 - relationships 429 parameters: 430 - name: action 431 in: body 432 description: One of follow/unfollow/block/unblock/approve/ignore. 433 schema: 434 type: string 435 enum: 436 - follow 437 - unfollow 438 - block 439 - unblock 440 - approve 441 442 responses: 443 200: 444 description: OK 445 schema: 446 properties: 447 data: 448 type: array 449 items: 450 $ref: '#/definitions/MiniProfile' 451 452 /media/{media-id}: 453 parameters: 454 - name: media-id 455 in: path 456 description: The media ID 457 type: integer 458 required: true 459 get: 460 tags: 461 - Media 462 description: | 463 Get information about a media object. 464 The returned type key will allow you to differentiate between `image` 465 and `video` media. 466 467 Note: if you authenticate with an OAuth Token, you will receive the 468 `user_has_liked` key which quickly tells you whether the current user 469 has liked this media item. 470 responses: 471 200: 472 description: OK 473 schema: 474 $ref: '#/definitions/Media' 475 476 /media1/{shortcode}: #FIXME: correct path is /media/{shortcode} 477 parameters: 478 - name: shortcode 479 in: path 480 description: The media shortcode 481 type: string 482 required: true 483 get: 484 tags: 485 - Media 486 description: | 487 This endpoint returns the same response as **GET** `/media/media-id`. 488 489 A media object's shortcode can be found in its shortlink URL. 490 An example shortlink is `http://instagram.com/p/D/` 491 Its corresponding shortcode is D. 492 493 responses: 494 200: 495 description: OK 496 schema: 497 $ref: '#/definitions/Media' 498 499 /media/search: 500 get: 501 tags: 502 - Media 503 description: | 504 Search for media in a given area. The default time span is set to 5 505 days. The time span must not exceed 7 days. Defaults time stamps cover 506 the last 5 days. Can return mix of image and video types. 507 508 parameters: 509 - name: LAT 510 description: | 511 Latitude of the center search coordinate. If used, lng is required. 512 type: number 513 in: query 514 - name: MIN_TIMESTAMP 515 description: | 516 A unix timestamp. All media returned will be taken later than 517 this timestamp. 518 type: integer 519 in: query 520 - name: LNG 521 description: | 522 Longitude of the center search coordinate. If used, lat is required. 523 type: number 524 in: query 525 - name: MAX_TIMESTAMP 526 description: | 527 A unix timestamp. All media returned will be taken earlier than this 528 timestamp. 529 type: integer 530 in: query 531 - name: DISTANCE 532 description: Default is 1km (distance=1000), max distance is 5km. 533 type: integer 534 maximum: 5000 535 default: 1000 536 in: query 537 responses: 538 200: 539 description: OK 540 schema: 541 type: object 542 description: List of all media with added `distance` property 543 properties: 544 data: 545 type: array 546 items: 547 allOf: 548 - $ref: '#/definitions/Media' 549 - 550 properties: 551 distance: 552 type: number 553 554 /media/popular: 555 get: 556 tags: 557 - Media 558 description: | 559 Get a list of what media is most popular at the moment. 560 Can return mix of image and video types. 561 responses: 562 200: 563 description: OK 564 schema: 565 type: object 566 properties: 567 data: 568 type: array 569 items: 570 $ref: '#/definitions/Media' 571 572 /media/{media-id}/comments: 573 parameters: 574 - name: media-id 575 in: path 576 description: Media ID 577 type: integer 578 required: true 579 get: 580 tags: 581 - Comments 582 description: | 583 Get a list of recent comments on a media object. 584 responses: 585 200: 586 description: OK 587 schema: 588 properties: 589 meta: 590 properties: 591 code: 592 type: number 593 data: 594 type: array 595 items: 596 $ref: '#/definitions/Comment' 597 post: 598 tags: 599 - Comments 600 - Media 601 description: | 602 Create a comment on a media object with the following rules: 603 604 * The total length of the comment cannot exceed 300 characters. 605 * The comment cannot contain more than 4 hashtags. 606 * The comment cannot contain more than 1 URL. 607 * The comment cannot consist of all capital letters. 608 security: 609 - oauth: 610 - comments 611 parameters: 612 - name: TEXT 613 description: | 614 Text to post as a comment on the media object as specified in 615 media-id. 616 in: body 617 schema: 618 type: number 619 responses: 620 200: 621 description: OK 622 schema: 623 type: object 624 properties: 625 meta: 626 properties: 627 code: 628 type: number 629 data: 630 type: object 631 delete: 632 tags: 633 - Comments 634 description: | 635 Remove a comment either on the authenticated user's media object or 636 authored by the authenticated user. 637 responses: 638 200: 639 description: OK 640 schema: 641 type: object 642 properties: 643 meta: 644 properties: 645 code: 646 type: number 647 data: 648 type: object 649 650 /media/{media-id}/likes: 651 parameters: 652 - name: media-id 653 in: path 654 description: Media ID 655 type: integer 656 required: true 657 get: 658 tags: 659 - Likes 660 - Media 661 description: | 662 Get a list of users who have liked this media. 663 responses: 664 200: 665 description: OK 666 schema: 667 properties: 668 meta: 669 properties: 670 code: 671 type: number 672 data: 673 type: array 674 items: 675 $ref: '#/definitions/Like' 676 post: 677 tags: 678 - Likes 679 description: Set a like on this media by the currently authenticated user. 680 security: 681 - oauth: 682 - comments 683 responses: 684 200: 685 description: OK 686 schema: 687 type: object 688 properties: 689 meta: 690 properties: 691 code: 692 type: number 693 data: 694 type: object 695 delete: 696 tags: 697 - Likes 698 description: | 699 Remove a like on this media by the currently authenticated user. 700 responses: 701 200: 702 description: OK 703 schema: 704 type: object 705 properties: 706 meta: 707 properties: 708 code: 709 type: number 710 data: 711 type: object 712 713 /tags/{tag-name}: 714 parameters: 715 - $ref: '#/parameters/tag-name' 716 get: 717 tags: 718 - Tags 719 description: Get information about a tag object. 720 responses: 721 200: 722 description: OK 723 schema: 724 $ref: '#/definitions/Tag' 725 726 /tags/{tag-name}/media/recent: 727 parameters: 728 - $ref: '#/parameters/tag-name' 729 get: 730 tags: 731 - Tags 732 description: | 733 Get a list of recently tagged media. Use the `max_tag_id` and 734 `min_tag_id` parameters in the pagination response to paginate through 735 these objects. 736 responses: 737 200: 738 description: OK 739 schema: 740 properties: 741 data: 742 type: array 743 items: 744 $ref: '#/definitions/Tag' 745 746 /tags/search: 747 get: 748 tags: 749 - Tags 750 parameters: 751 - name: q 752 description: | 753 A valid tag name without a leading #. (eg. snowy, nofilter) 754 in: query 755 type: string 756 responses: 757 200: 758 description: OK 759 schema: 760 type: object 761 properties: 762 meta: 763 properties: 764 code: 765 type: integer 766 data: 767 type: array 768 items: 769 $ref: '#/definitions/Tag' 770 771 /locations/{location-id}: 772 parameters: 773 - name: location-id 774 description: Location ID 775 in: path 776 type: integer 777 required: true 778 get: 779 tags: 780 - Location 781 description: Get information about a location. 782 responses: 783 200: 784 description: OK 785 schema: 786 type: object 787 properties: 788 data: 789 $ref: '#/definitions/Location' 790 791 /locations/{location-id}/media/recent: 792 parameters: 793 - name: location-id 794 description: Location ID 795 in: path 796 type: integer 797 required: true 798 get: 799 tags: 800 - Location 801 - Media 802 description: Get a list of recent media objects from a given location. 803 parameters: 804 - name: max_timestamp 805 in: query 806 description: Return media before this UNIX timestamp. 807 type: integer 808 - name: min_timestamp 809 in: query 810 description: Return media after this UNIX timestamp. 811 type: integer 812 - name: min_id 813 in: query 814 description: Return media later than this min_id. 815 type: string 816 - name: max_id 817 in: query 818 description: Return media earlier than this max_id. 819 type: string 820 responses: 821 200: 822 description: OK 823 schema: 824 type: object 825 properties: 826 data: 827 type: array 828 items: 829 $ref: '#/definitions/Media' 830 831 /locations/search: 832 get: 833 tags: 834 - Location 835 description: Search for a location by geographic coordinate. 836 parameters: 837 - name: distance 838 in: query 839 description: Default is 1000m (distance=1000), max distance is 5000. 840 type: integer 841 842 - name: facebook_places_id 843 in: query 844 description: | 845 Returns a location mapped off of a Facebook places id. If used, a 846 Foursquare id and lat, lng are not required. 847 type: integer 848 849 - name: foursquare_id 850 in: query 851 description: | 852 returns a location mapped off of a foursquare v1 api location id. 853 If used, you are not required to use lat and lng. Note that this 854 method is deprecated; you should use the new foursquare IDs with V2 855 of their API. 856 type: integer 857 858 - name: lat 859 in: query 860 description: | 861 atitude of the center search coordinate. If used, lng is required. 862 type: number 863 864 - name: lng 865 in: query 866 description: | 867 ongitude of the center search coordinate. If used, lat is required. 868 type: number 869 870 - name: foursquare_v2_id 871 in: query 872 description: | 873 Returns a location mapped off of a foursquare v2 api location id. If 874 used, you are not required to use lat and lng. 875 type: integer 876 responses: 877 200: 878 description: OK 879 schema: 880 type: object 881 properties: 882 data: 883 type: array 884 items: 885 $ref: '#/definitions/Location' 886 887 /geographies/{geo-id}/media/recent: 888 parameters: 889 - name: geo-id 890 in: path 891 description: Geolocation ID 892 type: integer 893 required: true 894 get: 895 description: | 896 Get recent media from a geography subscription that you created. 897 **Note**: You can only access Geographies that were explicitly created 898 by your OAuth client. Check the Geography Subscriptions section of the 899 [real-time updates page](https://instagram.com/developer/realtime/). 900 When you create a subscription to some geography 901 that you define, you will be returned a unique geo-id that can be used 902 in this query. To backfill photos from the location covered by this 903 geography, use the [media search endpoint 904 ](https://instagram.com/developer/endpoints/media/). 905 parameters: 906 - name: count 907 in: query 908 description: Max number of media to return. 909 type: integer 910 - name: min_id 911 in: query 912 description: Return media before this `min_id`. 913 type: integer 914 responses: 915 200: 916 description: OK 917 918################################################################################ 919# Definitions # 920################################################################################ 921definitions: 922 User: 923 type: object 924 properties: 925 id: 926 type: integer 927 username: 928 type: string 929 full_name: 930 type: string 931 profile_picture: 932 type: string 933 bio: 934 type: string 935 website: 936 type: string 937 counts: 938 type: object 939 properties: 940 media: 941 type: integer 942 follows: 943 type: integer 944 follwed_by: 945 type: integer 946 Media: 947 type: object 948 properties: 949 created_time: 950 description: Epoc time (ms) 951 type: integer 952 type: 953 type: string 954 filter: 955 type: string 956 tags: 957 type: array 958 items: 959 $ref: '#/definitions/Tag' 960 id: 961 type: integer 962 user: 963 $ref: '#/definitions/MiniProfile' 964 users_in_photo: 965 type: array 966 items: 967 $ref: '#/definitions/MiniProfile' 968 location: 969 $ref: '#/definitions/Location' 970 comments:: 971 type: object 972 properties: 973 count: 974 type: integer 975 data: 976 type: array 977 items: 978 $ref: '#/definitions/Comment' 979 likes: 980 type: object 981 properties: 982 count: 983 type: integer 984 data: 985 type: array 986 items: 987 $ref: '#/definitions/MiniProfile' 988 images: 989 properties: 990 low_resolution: 991 $ref: '#/definitions/Image' 992 thumbnail: 993 $ref: '#/definitions/Image' 994 standard_resolution: 995 $ref: '#/definitions/Image' 996 videos: 997 properties: 998 low_resolution: 999 $ref: '#/definitions/Image' 1000 standard_resolution: 1001 $ref: '#/definitions/Image' 1002 Location: 1003 type: object 1004 properties: 1005 id: 1006 type: string 1007 name: 1008 type: string 1009 latitude: 1010 type: number 1011 longitude: 1012 type: number 1013 Comment: 1014 type: object 1015 properties: 1016 id: 1017 type: string 1018 created_time: 1019 type: string 1020 text: 1021 type: string 1022 from: 1023 $ref: '#/definitions/MiniProfile' 1024 Like: 1025 type: object 1026 properties: 1027 user_name: 1028 type: string 1029 first_name: 1030 type: string 1031# x-go-name: NoName 1032 last_name: 1033 type: string 1034 type: 1035 type: string 1036 id: 1037 type: string 1038 Tag: 1039 type: object 1040 properties: 1041 media_count: 1042 type: integer 1043 name: 1044 type: string 1045 Image: 1046 type: object 1047 properties: 1048 width: 1049 type: integer 1050 height: 1051 type: integer 1052 url: 1053 type: string 1054 MiniProfile: 1055 type: object 1056 description: A shorter version of User for likes array 1057 properties: 1058 user_name: 1059 type: string 1060 full_name: 1061 type: string 1062 id: 1063 type: integer 1064 profile_picture: 1065 type: string 1066