Pinterest API v5 — Examples & Documentation

Base URL

https://pinterest-api-bay.vercel.app

All endpoints support GET and POST methods
No authentication or API key required
Add &compact=true to pin endpoints for minimal response (ideal for bots)
Interactive testing available at /docs

Search

GET POST /v5/pins/search?query={query}&count={count}&compact={bool}

Parameters

Name	Type	Description
query	string (required)	Search keyword
count	int (1-100, default 20)	Number of results
compact	bool (default false)	Minimal fields for bots

GET Example


# Search anime pins, 5 results, compact mode

GET /v5/pins/search?query=Anime&count=5&compact=true


# Response:

{

  "items": [

    {

      "id": "123456789",

      "title": "Satoru Gojo",

      "image": "https://i.pinimg.com/736x/...",

      "owner": "username",

      "url": "https://www.pinterest.com/pin/123456789/"

    }

  ],

  "total": 5

}

POST Example


POST /v5/pins/search

Content-Type: application/json


{

  "query": "Anime",

  "count": 5,

  "compact": true

}

Short URL

GET /search/pins?q=Anime&count=5&compact=true

GET POST /v5/boards/search?query={query}&count={count}

Parameters

Name	Type	Description
query	string (required)	Search keyword
count	int (1-100, default 20)	Number of results

GET Example


GET /v5/boards/search?query=Anime&count=3


# Response:

{

  "items": [

    {

      "id": "688487930474369703",

      "name": "Anime",

      "description": "",

      "url": "https://www.pinterest.com/user/anime/",

      "pin_count": 112,

      "follower_count": 0,

      "cover_image": "https://i.pinimg.com/...",

      "owner": { "username": "user" }

    }

  ],

  "total": 3

}

Short URL

GET /search/boards?q=Anime&count=3

Pins

GET POST /v5/pins/{pin_id}

Parameters

Name	Type	Description
pin_id	string (required)	Pinterest pin ID

GET Example


GET /v5/pins/38773246786634748


# Response:

{

  "id": "38773246786634748",

  "title": "Pin Title",

  "description": "Pin description",

  "link": "",

  "image": {

    "small": { "url": "...", "width": 236, "height": 362 },

    "medium": { "url": "...", "width": 474, "height": 727 },

    "large": { "url": "...", "width": 736, "height": 1130 },

    "original": { "url": "...", "width": 736, "height": 1130 }

  },

  "owner": { "username": "username" },

  "saves": 2129,

  "url": "https://www.pinterest.com/pin/38773246786634748/"

}

POST Example


POST /v5/pins/38773246786634748

Content-Type: application/json


{ "pin_id": "38773246786634748" }

Short URL

GET /pin/38773246786634748

Users

GET POST /v5/users/{username}

Parameters

Name	Type	Description
username	string (required)	Pinterest username

GET Example


GET /v5/users/pinterest


# Response:

{

  "username": "pinterest",

  "full_name": "Pinterest",

  "about": "Find your reason to go offline.",

  "profile_image": "https://i.pinimg.com/280x280_RS/...",

  "website_url": "http://www.pinterest.com",

  "followers": 6257599,

  "following": 395,

  "pins": 95425,

  "boards": 115,

  "url": "https://www.pinterest.com/pinterest/"

}

Short URL

GET /user/pinterest

GET POST /v5/users/{username}/pins?count={count}&compact={bool}

Parameters

Name	Type	Description
username	string (required)	Pinterest username
count	int (1-100, default 25)	Number of results
compact	bool (default false)	Minimal fields for bots

GET Example

GET /v5/users/pinterest/pins?count=5&compact=true

Short URL

GET /user/pinterest/pins?count=5&compact=true

GET POST /v5/users/{username}/boards?count={count}

Parameters

Name	Type	Description
username	string (required)	Pinterest username
count	int (1-100, default 25)	Number of results

GET Example

GET /v5/users/pinterest/boards?count=5

Short URL

GET /user/pinterest/boards?count=5

Boards

GET POST /v5/boards/{username}/{slug}

Parameters

Name	Type	Description
username	string (required)	Board owner username
slug	string (required)	Board URL slug

GET Example


GET /v5/boards/pinterest/festival-season-unlocked


# Response:

{

  "id": "424605139808106786",

  "name": "Festival season unlocked",

  "description": "Tap into trending outfits...",

  "url": "https://www.pinterest.com/pinterest/festival-season-unlocked/",

  "pin_count": 174,

  "follower_count": 4220474,

  "cover_image": "https://i.pinimg.com/...",

  "owner": { "username": "pinterest" }

}

Short URL

GET /board/pinterest/festival-season-unlocked

GET POST /v5/boards/{username}/{slug}/pins?count={count}&compact={bool}

Parameters

Name	Type	Description
username	string (required)	Board owner username
slug	string (required)	Board URL slug
count	int (1-100, default 25)	Number of results
compact	bool (default false)	Minimal fields for bots

GET Example

GET /v5/boards/pinterest/festival-season-unlocked/pins?count=5&compact=true

Short URL

GET /board/pinterest/festival-season-unlocked/pins?count=5&compact=true

Compact Mode

What is Compact Mode?

Add compact=true parameter to any pin endpoint for a minimal response. Perfect for bots, low bandwidth, or when you only need the image URL and title.

Compact response removes description, link, saves fields
Image becomes a single URL string (largest available) instead of size objects
Owner becomes a plain string instead of an object
Response size is ~3x smaller — ideal for Bots.Business, Telegram bots, etc.

Error Format

All errors follow Pinterest's official format


{

  "code": 4,

  "message": "query: Field required",

  "status": "failure"

}

Code 1 — Pinterest returned an HTTP error (403, 404, etc.)
Code 2 — Failed to parse Pinterest response
Code 3 — Pinterest request failed
Code 4 — Invalid request parameters
Code 10 — Pin not found
Code 11 — User not found
Code 12 — Board not found

URL Quick Reference

Endpoint	v5 URL	Short URL
Search Pins	/v5/pins/search?query=...	/search/pins?q=...
Search Boards	/v5/boards/search?query=...	/search/boards?q=...
Pin Detail	/v5/pins/{id}	/pin/{id}
User Profile	/v5/users/{username}	/user/{username}
User Pins	/v5/users/{username}/pins	/user/{username}/pins
User Boards	/v5/users/{username}/boards	/user/{username}/boards
Board Detail	/v5/boards/{username}/{slug}	/board/{username}/{slug}
Board Pins	/v5/boards/{username}/{slug}/pins	/board/{username}/{slug}/pins