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
View as plain text