Pinterest API is located at https://api.pinterest.com. All access occurs via HTTPS. As of now, all the data should be sent and received through JSON (JavaScript Object Notation). API does not support XML inputs or outputs yet.
Authentication
In order to access authenticated resources, client needs to authenticate itself to the Pinterest API first. Failing to do so would result in a HTTP – 400 Bad Request response.
OAuth2 is used by Pinterest for server side authentication purposes. Authentication process consists of 3 steps, which are as follows:
i) User Authentication - To ensure that user properly authenticates to the server and says who they are
ii) App Authorization - This involves the user knowing what kind of data they will be providing the app
iii) App Authentication - This ensures that the user is providing their information to the proper app, not anything or anybody else.
Once these steps are performed, a user token is issued by the server to the app to perform tasks on behalf of the user.
First, you need to redirect the user to Pinterest authentication screen.
Endpoints
User Endpoints
1) Returns detailed information for a given user, specified by username. (GET)
$ curl -i https://api.pinterest.com/v2/users/USERNAME/
access_token= ACCESS_TOKEN
2) Returns the "home" feed for an authenticated user. (GET)
$ curl -i https://api.pinterest.com/v2/home/
access_token= ACCESS_TOKEN
3) Returns detailed information for the recent pins from a given user, specified by username. (GET)
$ curl -i https://api.pinterest.com/v2/user/USERNAME/pins/
access_token= ACCESS_TOKEN
4) Returns detailed information for the recent pins a user has liked, specified by username. (GET)
$ curl -i https://api.pinterest.com/v2/user/USERNAME/likes/
access_token= ACCESS_TOKEN
5) Returns information for the users a given user is following, specified by username. (GET)
$ curl -i https://api.pinterest.com/v2/user/USERNAME/following/
access_token= ACCESS_TOKEN
6) Returns detailed information for the users a given user follows, specified by username. (GET)
$ curl -i https://api.pinterest.com/v2/user/USERNAME/followers/
access_token= ACCESS_TOKEN
7) Requests that an authenticated user follow another user. (GET)
$ curl -i https://api.pinterest.com/v2/user/USERNAME/follow/
access_token= ACCESS_TOKEN
8) Requests that an authenticated user unfollow another user. (GET)
$ curl -i https://api.pinterest.com/v2/user/USERNAME/unfollow/
access_token= ACCESS_TOKEN
Board Endpoints
1) Returns a list of boards for the authenticated user. (GET)
$ curl -i https://api.pinterest.com/v2/boards/
access_token= ACCESS_TOKEN
2) Returns detailed information for a given board specified by username and board slug. (GET)
$ curl -i https://api.pinterest.com/v2/boards/USERNAME/BOARD_SLUG/
access_token= ACCESS_TOKEN
3) Create a board for the authenticated user with the given name and description. (POST)
$ curl -i https://api.pinterest.com/v2/boards/create/
access_token= ACCESS_TOKEN
name= BOARD_NAME
description= BOARD_DESCRIPTION
category= BOARD_CATEGORY_TAG
4) Return the list of categories which a board can belong to. (GET)
$ curl -i https://api.pinterest.com/v2/boards/categories/
5) Request the authenticated user follows a board. (GET)
$ curl -i https://api.pinterest.com/v2/boards/USERNAME/BOARD_SLUG/follow/
access_token= ACCESS_TOKEN
6) Request the authenticated user unfollows a board. (GET)
$ curl -i https://api.pinterest.com/v2/boards/USERNAME/BOARD_SLUG/unfollow/
access_token= ACCESS_TOKEN
Pin Endpoints
1) Return detailed information for a given pin object specified by pin ID. (GET)
$ curl -i https://api.pinterest.com/v2/pin/PIN_ID/
access_token= ACCESS_TOKEN
2) Requests that an authenticated user adds a comment (specified by a text string) to a given pin. (POST)
$ curl -i https://api.pinterest.com/v2/pin/PIN_ID/comment/
access_token= ACCESS_TOKEN
text= TEXT
3) Requests that an authenticated user likes a given pin (specified by pin ID). (POST)
$ curl -i https://api.pinterest.com/v2/pin/PIN_ID/like/
access_token= ACCESS_TOKEN
4) Requests that an authenticated user unlikes a given pin (specified by pin ID). (POST)
$ curl -i https://api.pinterest.com/v2/pin/PIN_ID/unlike/
access_token= ACCESS_TOKEN
5) Requests that an authenticated user posts a pin to a given board with a number of optional flags. (POST)
$ curl -i https://api.pinterest.com/v2/pin/
access_token= ACCESS_TOKEN
board_id= BOARD_ID
details= PIN_DESCRIPTION
latitude= LATITUDE (Optional)
longitude= LONGITUDE (Optional)
place= PLACE_STRING (Optional)
publish_to_facebook= PUBLISH_TO_FB_FLAG (Optional)
publish_to_twitter= PUBLISH_TO_TWITTER_FLAG (Optional)
6) Requests that an authenticated user repins a given pin (specified by pin ID) to a given board (specified by a board ID). (POST)
$ curl -i https://api.pinterest.com/v2/repin/
access_token= ACCESS_TOKEN
board_id= BOARD_ID
details= PIN_DESCRIPTION (Existing description or new description)
7) Returns pin objects matching a given query string (specified by a query variable). (GET)
$ curl -i https://api.pinterest.com/v2/search/pins/
query= QUERY_STRING
8) Returns pin objects in the current "popular" feed. (GET)
$ curl -i https://api.pinterest.com/v2/popular/
Tips for developers
ñ Always use https to the domain: api.pinterest.com for all API access.
ñ Always send the following header parameters:
1. Host: api.pinterest.com
2. User-Agent: Pinterest For iPhone / 1.4.3
3. Accept-Encoding: gzip
4. Connection: keep-alive
5. Proxy-Connection: keep-alive
ñ Since the responses always return two key headers, make sure your apps watch out for this, so that you wouldn't go overboard. (There is a high chance that the server could block you in case you go overboard)
1. X-Ratelimit-Limit: 350
2. X-Ratelimit-Remaining: 349
Example Code
Unauthenticated Requests
1) Get list of all categories
GET /v2/boards/categories/?limit=36&
Response
[{"tag":string, "name":string},..]
Example:
[{"tag": "architecture", "name": "Architecture"}, {"tag": "art", "name": "Art"}, {"tag": "cars_motorcycles", "name": "Cars & Motorcycles"}, {"tag": "design", "name": "Design"}, {"tag": "diy_crafts", "name": "DIY & Crafts"}, {"tag": "education", "name": "Education"}, {"tag": "film_music_books", "name": "Film, Music & Books"}, {"tag": "fitness", "name": "Fitness"}, {"tag": "food_drink", "name": "Food & Drink"}, {"tag": "gardening", "name": "Gardening"}, {"tag": "geek", "name": "Geek"}, {"tag": "hair_beauty", "name": "Hair & Beauty"}, {"tag": "history", "name": "History"}, {"tag": "holidays", "name": "Holidays"}, {"tag": "home", "name": "Home Decor"}, {"tag": "humor", "name": "Humor"}, {"tag": "kids", "name": "Kids"}, {"tag": "mylife", "name": "My Life"}, {"tag": "women_apparel", "name": "Women's Apparel"}, {"tag": "men_apparel", "name": "Men's Apparel"}, {"tag": "outdoors", "name": "Outdoors"}, {"tag": "people", "name": "People"}, {"tag": "pets", "name": "Pets"}, {"tag": "photography", "name": "Photography"}, {"tag": "prints_posters", "name": "Print & Posters"}, {"tag": "products", "name": "Products"}, {"tag": "science", "name": "Science & Nature"}, {"tag": "sports", "name": "Sports"}, {"tag": "technology", "name": "Technology"}, {"tag": "travel_places", "name": "Travel & Places"}, {"tag": "wedding_events", "name": "Wedding & Events"}, {"tag": "other", "name": "Other"}]
2) Search
GET /v2/search/pins/?query=Test
To search for other items, just replace "/pins/" in the url with:
/boards/
/people/
Response
/pins/
{"status": "success", "search": "search_pins", "pagination": {"next": "/v2/search/pins/?query=Test&limit=36&page=2"}, "pins": PIN_ARRAY, "query": "Test", "counts": {"board": 0, "pin": 500, "user": 0}, "pages": 13}
PIN_ARRAY:[{"domain": "partybooths.com", "description": "test test test", "user": {"username": "hollenbarmer", "is_following": null, "full_name": "Hollen Barmer", "image_url": "http://graph.facebook.com/4806213/picture?type=square", "id": "190136552926478704", "image_large_url": "http://graph.facebook.com/4806213/picture?type=large"}, "images": {"mobile": "http://media-cdn.pinterest.com/upload/190136415487580107_gD2LuFhp_f.jpg", "closeup": "http://media-cdn.pinterest.com/upload/190136415487580107_gD2LuFhp_c.jpg", "thumbnail": "http://media-cdn.pinterest.com/upload/190136415487580107_gD2LuFhp_t.jpg", "board": "http://media-cdn.pinterest.com/upload/190136415487580107_gD2LuFhp_b.jpg"}, "counts": {"repins": 0, "comments": 1, "likes": 0}, "id": "190136415487580107", "sizes": {"mobile": {"width": 435, "height": 131}, "board": {"height": 57}}, "created_at": "2011-09-23T07:08:33", "comments": [{"text": "Nice.", "id": "190136621645962706", "user": {"username": "digitalac", "is_following": null, "full_name": "Brett Will", "image_url": "http://d30opm7hsgivgh.cloudfront.net/avatars/digitalac_1328766526.jpg", "id": "128423164282669655", "image_large_url": "http://media-cdn.pinterest.com/avatars/digitalac_1328766526_o.jpg"}}], "is_repin": false, "source": "http://partybooths.com/", "board": {"category": "wedding_events", "user_id": "190136552926478704", "description": "", "url": "/hollenbarmer/lh/", "is_following": null, "id": "190136484207004498", "name": "LH"}, "is_video": false},...]/boards/{"status": "success", "pagination": {"next": "/v2/search/boards/?query=Testing&limit=36&page=2"}, "boards": [{"category": "diy_crafts", "user_id": "286612101194055772", "description": "", "url": "/jonanneryen/testing-testing/", "is_following": false, "stats": {"followers_count": 89, "pins_count": 34}, "id": "286612032474580273", "name": "Testing, Testing"}, ...], "search": "search_boards", "query": "Testing", "counts": {"board": 500, "pin": 0, "user": 0}, "pages": 13}/people/{"status": "success", "pagination": {"next": "/v2/search/people/?query=Testing&limit=36&page=2"}, "users": [{"username": "testingsemi", "website": "", "about": "", "twitter_link": "http://www.twitter.com/testingsemi", "is_following": false, "facebook_link": "", "image_url": "http://d30opm7hsgivgh.cloudfront.net/avatars/testingsemi_1329981516.jpg", "location": "", "full_name": "testing", "stats": {"followers_count": 0, "likes_count": 1, "pins_count": 2, "following_count": 9, "boards_count": 0}, "id": "62276544755666017", "image_large_url": "http://media-cdn.pinterest.com/avatars/testingsemi_1329981516_o.jpg"},...], "search": "search_people", "query": "Testing", "counts": {"board": 0, "pin": 0, "user": 500}, "pages": 13}
3) Get user data
GET /v2/users/testingapps1/
Response
{"status": "success", "user": {"username": "testingapps1", "website": "", "about": "", "twitter_link": "http://www.twitter.com/TestingApps1", "is_following": false, "facebook_link": "", "image_url": "http://d30opm7hsgivgh.cloudfront.net/avatars/testingapps1_1329425714.jpg", "location": "", "full_name": "Testing Apps", "stats": {"followers_count": 0, "likes_count": 0, "pins_count": 0, "following_count": 0, "boards_count": 0}, "id": "264023734313028491", "image_large_url": "http://media-cdn.pinterest.com/avatars/testingapps1_1329425714_o.jpg"}, "boards": [{"category": "", "is_collaborator": false, "user_id": "264023734313028491", "description": "", "url": "/testingapps1/getting-down-to-business-apps/", "is_following": false, "thumbnails": [], "stats": {"followers_count": 0, "pins_count": 0}, "id": "264023665593573832", "name": "Getting Down to Business (apps)."}, {"category": "", "is_collaborator": false, "user_id": "264023734313028491", "description": "", "url": "/testingapps1/apps-in-progress/", "is_following": false, "thumbnails": [], "stats": {"followers_count": 0, "pins_count": 0}, "id": "264023665593573831", "name": "Apps in Progress"}, {"category": "", "is_collaborator": false, "user_id": "264023734313028491", "description": "", "url": "/testingapps1/products-we-love/", "is_following": false, "thumbnails": [], "stats": {"followers_count": 0, "pins_count": 0}, "id": "264023665593573830", "name": "Products We Love"}, {"category": "", "is_collaborator": false, "user_id": "264023734313028491", "description": "", "url": "/testingapps1/hop-on-a-plane-go-travel-apps/", "is_following": false, "thumbnails": [], "stats": {"followers_count": 0, "pins_count": 0}, "id": "264023665593573829", "name": "Hop on a Plane & Go! Travel Apps. "}, {"category": "", "is_collaborator": false, "user_id": "264023734313028491", "description": "", "url": "/testingapps1/apps-we-want/", "is_following": false, "thumbnails": [], "stats": {"followers_count": 0, "pins_count": 0}, "id": "264023665593573828", "name": "Apps We Want!"}]}
4) Get users pins
GET /v2/users/testingapps1/pins/
Response
{"pins": [], "status": "success", "pagination": {}, "user": {"username": "testingapps1", "website": "", "about": "", "twitter_link": "http://www.twitter.com/TestingApps1", "is_following": false, "facebook_link": "", "image_url": "http://d30opm7hsgivgh.cloudfront.net/avatars/testingapps1_1329425714.jpg", "location": "", "full_name": "Testing Apps", "stats": {"followers_count": 0, "likes_count": 0, "pins_count": 0, "following_count": 0, "boards_count": 0}, "id": "264023734313028491", "image_large_url": "http://media-cdn.pinterest.com/avatars/testingapps1_1329425714_o.jpg"}}
5) Get users likes
GET /v2/users/testingapps1/likes/
Response
{"pins": [], "status": "success", "pagination": {}, "user": {"username": "testingapps1", "website": "", "about": "", "twitter_link": "http://www.twitter.com/TestingApps1", "is_following": false, "facebook_link": "", "image_url": "http://d30opm7hsgivgh.cloudfront.net/avatars/testingapps1_1329425714.jpg", "location": "", "full_name": "Testing Apps", "stats": {"followers_count": 0, "likes_count": 0, "pins_count": 0, "following_count": 0, "boards_count": 0}, "id": "264023734313028491", "image_large_url": "http://media-cdn.pinterest.com/avatars/testingapps1_1329425714_o.jpg"}}
Authenticated Requests
1) Get access token via API
Email and password need to be sent as a base 64 encoded Basic Http Authentication header. Google it if you aren't sure how to do this.
POST /v2/oauth/access_token?
Post parameters:
client_id=1234567
client_secret=ab04920a718c1e35ae5b08ffa4603dd62ef7c8fc
grant_type=password
scope=read_write
redirect_uri=http://pinterest.com/about/iphone/
Headers:
HTTP/1.1
Host: api.pinterest.com
User-Agent: Pinterest For iPhone / 1.4.3
Content-Length: 96
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: Basic [[REMOVED]]
Accept-Encoding: gzip
Connection: close
Result
access_token=<Your token>
2) Get oauth token via facebook authorization
POST /v2/check_registered/facebook/
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Connection: close
Proxy-Connection: close
Post data:
facebook_id=[[USERS FACEBOOK ID NUMBER]]
client_id=1234567
oauth_token=Facebook oauth token
oauth_secret=
Result
access_token=[[pinterest access token]]
3) Get info on logged in user
GET /v2/me?limit=12&access_token=[[ACCESS_TOKEN]]
Response
{"username": string, "website": string, "about": "", "twitter_link": "", "is_following": null, "facebook_link": "", "is_connected_to_facebook": true, "status": "success", "image_url": "", "location": "", "full_name": "", "stats": {"followers_count": 11, "likes_count": 11, "pins_count": 11, "following_count": 11, "boards_count": 11}, "id": "", "image_large_url": "", "is_connected_to_twitter": true}