Pinterest Board API
The Board API from Pinterest — 5 operation(s) for board.
OpenAPI Specification
openapi: 3.0.3
info:
version: 5.13.0
title: Pinterest Board API
description: This is the description of your API.
contact:
name: Pinterest, Inc.
url: https://developers.pinterest.com/
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://developers.pinterest.com/terms/
servers:
- url: https://api.pinterest.com/v5
tags:
- name: Board
paths:
/boards/{board_id}:
get:
summary: Get board
description: 'Get a board owned by the operation user_account - or a group board that has been shared with this account.
- Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
- By default, the "operation user_account" is the token user_account.'
tags:
- Board
operationId: boards/get
security:
- pinterest_oauth2:
- boards:read
x-ratelimit-category: org_read
x-sandbox: enabled
x-codeSamples:
- lang: python
label: Python SDK
source: '# Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started
from pinterest.organic.boards import Board
# Board information can be fetched from profile page or from create/list board method here:
# https://developers.pinterest.com/docs/api/v5/#operation/boards/list
BOARD_ID="<Add your board id here>"
board_get = Board(board_id=BOARD_ID)
print("Board Id: %s, Board name:%s"%(board_get.id, board_get.name))
'
- lang: cURL
label: curl
source: '# Board information can be fetched from profile page or from create/list board method here:
# https://developers.pinterest.com/docs/api/v5/#operation/boards/list
curl --location --request GET ''https://api.pinterest.com/v5/boards/<insert_your_board_id>'' \
--header ''Authorization: Bearer <Add your token here>'' \
--header ''Content-Type: application/json''
'
- lang: cURL
label: curl (Sandbox)
source: '# Board information can be fetched from profile page or from create/ist board method here:
# https://developers.pinterest.com/docs/api/v5/#operation/boards/list
curl --location --request GET ''https://api-sandbox.pinterest.com/v5/boards/<insert_your_board_id>'' \
--header ''Authorization: Bearer <Add your token here>'' \
--header ''Content-Type: application/json''
'
parameters:
- $ref: '#/components/parameters/path_board_id'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
'200':
description: response
content:
application/json:
schema:
$ref: '#/components/schemas/Board'
'404':
description: Board not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 404
message: Board not found.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
summary: Update board
description: 'Update a board owned by the "operating user_account".
- Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
- By default, the "operation user_account" is the token user_account.'
tags:
- Board
operationId: boards/update
security:
- pinterest_oauth2:
- boards:read
- boards:write
x-ratelimit-category: org_write
x-sandbox: enabled
x-codeSamples:
- lang: python
label: Python SDK
source: "# Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started\n\nfrom pinterest.organic.boards import Board\n# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\nBOARD_ID=\"<Add your board id here>\"\nNEW_DESCRIPTION=\"Updated summer recipes!\"\nNEW_PRIVACY=\"SECRET\"\n\nboard_update = Board(board_id=BOARD_ID)\nboard_update.update_fields(\n description=NEW_DESCRIPTION,\n privacy=NEW_PRIVACY\n)\nprint(\"Board Id: %s, Board description:%s, Board privacy:%s\" %(board_update.id, board_update.description, board_update.privacy))\n"
- lang: cURL
label: curl
source: "# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\n\ncurl --location --request PATCH 'https://api.pinterest.com/v5/boards/<insert_board_id>' \\\n--header 'Authorization: Bearer <Add your token here>' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"name\": \"New Summer Recipes\",\n \"description\": \"Updated summer recipes!\",\n \"privacy\": \"SECRET\"\n}'\n"
- lang: cURL
label: curl (Sandbox)
source: "# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\n\ncurl --location --request PATCH 'https://api-sandbox.pinterest.com/v5/boards/<insert_board_id>' \\\n--header 'Authorization: Bearer <Add your token here>' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"name\": \"New Summer Recipes\",\n \"description\": \"Updated summer recipes!\",\n \"privacy\": \"SECRET\"\n}'\n"
parameters:
- $ref: '#/components/parameters/path_board_id'
- $ref: '#/components/parameters/query_ad_account_id'
requestBody:
description: Update a board.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BoardUpdate'
responses:
'200':
description: response
content:
application/json:
schema:
$ref: '#/components/schemas/Board'
'400':
description: Invalid board parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid board parameters.
'403':
description: Not authorized to update the board.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 403
message: Not authorized to update the board.
'429':
description: 'This request exceeded a rate limit. This can happen if the client exceeds one
of the published rate limits or if multiple write operations are applied to
an object within a short time window.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 8
message: 'This request exceeded a rate limit. This can happen if the client exceeds one
of the published rate limits or if multiple write operations are applied to
an object within a short time window.'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
summary: Delete board
description: 'Delete a board owned by the "operation user_account".
- Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
- By default, the "operation user_account" is the token user_account.'
tags:
- Board
operationId: boards/delete
security:
- pinterest_oauth2:
- boards:read
- boards:write
x-ratelimit-category: org_write
x-sandbox: enabled
x-codeSamples:
- lang: python
label: Python SDK
source: '# Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started
from pinterest.organic.boards import Board
# Board information can be fetched from profile page or from create/list board method here:
# https://developers.pinterest.com/docs/api/v5/#operation/boards/list
BOARD_ID="<Add your board id here>"
board_delete=Board.delete(board_id=BOARD_ID)
print("Board was deleted? %s" % (board_delete))
'
- lang: cURL
label: curl
source: '# Board information can be fetched from profile page or create/from list board method here:
# https://developers.pinterest.com/docs/api/v5/#operation/boards/list
curl --request DELETE ''https://api.pinterest.com/v5/boards/<insert_board_id>'' \
--header ''Authorization: Bearer <Add your token here>'' \
--header ''Content-Type: application/json'' \
'
- lang: cURL
label: curl (Sandbox)
source: '# Board information can be fetched from profile page or from create/list board method here:
# https://developers.pinterest.com/docs/api/v5/#operation/boards/list
curl --request DELETE ''https://api-sandbox.pinterest.com/v5/boards/<insert_board_id>'' \
--header ''Authorization: Bearer <Add your token here>'' \
--header ''Content-Type: application/json'' \
'
parameters:
- $ref: '#/components/parameters/path_board_id'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
'204':
description: Board deleted successfully
'403':
description: Not authorized to delete the board.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 403
message: Not authorized to delete the board.
'404':
description: Board not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 404
message: Board not found.
'409':
description: Could not get exclusive access to delete the board.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 409
message: Could not get exclusive access to delete the board.
'429':
description: 'This request exceeded a rate limit. This can happen if the client exceeds one
of the published rate limits or if multiple write operations are applied to
an object within a short time window.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 8
message: 'This request exceeded a rate limit. This can happen if the client exceeds one
of the published rate limits or if multiple write operations are applied to
an object within a short time window.'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/boards/{board_id}/pins:
get:
summary: List Pins on board
description: 'Get a list of the Pins on a board owned by the "operation user_account" - or on a group board that has been shared with this account.
- Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
- By default, the "operation user_account" is the token user_account.'
tags:
- Board
operationId: boards/list_pins
security:
- pinterest_oauth2:
- boards:read
- pins:read
x-ratelimit-category: org_read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_board_id'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_creative_types'
- $ref: '#/components/parameters/query_ad_account_id'
- $ref: '#/components/parameters/query_pin_metrics'
responses:
'200':
description: response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
description: Pins
items:
$ref: '#/components/schemas/Pin'
'404':
description: Board not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 404
message: Board not found.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/boards/{board_id}/sections:
get:
summary: List board sections
description: 'Get a list of all board sections from a board owned by the "operation user_account" - or a group board that has been shared with this account.
Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
- By default, the "operation user_account" is the token user_account.'
tags:
- Board
operationId: board_sections/list
security:
- pinterest_oauth2:
- boards:read
x-ratelimit-category: org_read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_board_id'
- $ref: '#/components/parameters/query_ad_account_id'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
responses:
'200':
description: response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
description: Board sections
items:
$ref: '#/components/schemas/BoardSection'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
summary: Create board section
description: 'Create a board section on a board owned by the "operation user_account" - or on a group board that has been shared with this account.
Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
- By default, the "operation user_account" is the token user_account.'
tags:
- Board
operationId: board_sections/create
security:
- pinterest_oauth2:
- boards:read
- boards:write
x-ratelimit-category: org_write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_board_id'
- $ref: '#/components/parameters/query_ad_account_id'
requestBody:
description: Create a board section.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BoardSection'
responses:
'201':
description: response
content:
application/json:
schema:
$ref: '#/components/schemas/BoardSection'
'400':
description: Invalid board section parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid board section parameters.
'403':
description: Not authorized to create board sections.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 403
message: Not authorized to create board sections.
'409':
description: Could not get exclusive access to the board to create a new section.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 409
message: Could not get exclusive access to the board to create a new section.
'500':
description: Could not create a new board section.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 500
message: Could not create a new board section.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/boards/{board_id}/sections/{section_id}:
patch:
summary: Update board section
description: 'Update a board section on a board owned by the "operation user_account" - or on a group board that has been shared with this account.
Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
- By default, the "operation user_account" is the token user_account.'
tags:
- Board
operationId: board_sections/update
security:
- pinterest_oauth2:
- boards:read
- boards:write
x-ratelimit-category: org_write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_board_id'
- $ref: '#/components/parameters/path_board_section_id'
- $ref: '#/components/parameters/query_ad_account_id'
requestBody:
description: Update a board section.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BoardSection'
responses:
'200':
description: response
content:
application/json:
schema:
$ref: '#/components/schemas/BoardSection'
'400':
description: Invalid board section parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid board section parameters.
'403':
description: Not authorized to update board section.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 403
message: Not authorized to update board section.
'409':
description: Board section conflict.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 409
message: Board section conflict.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
summary: Delete board section
description: 'Delete a board section on a board owned by the "operation user_account" - or on a group board that has been shared with this account.
Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
- By default, the "operation user_account" is the token user_account.'
tags:
- Board
operationId: board_sections/delete
security:
- pinterest_oauth2:
- boards:read
- boards:write
x-ratelimit-category: org_write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_board_id'
- $ref: '#/components/parameters/path_board_section_id'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
'204':
description: Board section deleted successfully
'403':
description: Not authorized to delete board section.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 403
message: Not authorized to delete board section.
'404':
description: Board section not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 404
message: Board section not found.
'409':
description: Board section conflict.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 409
message: Board section conflict.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/boards/{board_id}/sections/{section_id}/pins:
get:
summary: List Pins on board section
description: 'Get a list of the Pins on a board section of a board owned by the "operation user_account" - or on a group board that has been shared with this account.
Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
- By default, the "operation user_account" is the token user_account.'
tags:
- Board
operationId: board_sections/list_pins
security:
- pinterest_oauth2:
- boards:read
- pins:read
x-ratelimit-category: org_read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_board_id'
- $ref: '#/components/parameters/path_board_section_id'
- $ref: '#/components/parameters/query_ad_account_id'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
responses:
'200':
description: response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
description: Pins
items:
$ref: '#/components/schemas/Pin'
'403':
description: Not authorized to access Pins on board section.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 403
message: Not authorized to access Pins on board section.
'404':
description: Board or section not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 404
message: Board or section not found.
'409':
description: Board section conflict.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 409
message: Board section conflict.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
BoardSection:
title: Board section
description: Sections help organize pins within a board.
type: object
properties:
id:
type: string
readOnly: true
example: '549755885175'
name:
type: string
example: Salads
minLength: 1
maxLength: 180
required:
- name
PinMediaSourceImagesURL:
title: Images urls
description: Multiple images urls-based media source
additionalProperties: false
properties:
source_type:
type: string
enum:
- multiple_image_urls
items:
items:
additionalProperties: false
properties:
title:
type: string
description:
type: string
link:
type: string
description: Destination link for the image.
url:
description: URL of image to upload.
type: string
required:
- url
type: object
minItems: 2
maxItems: 5
description: Array with image objects.
type: array
index:
type: integer
minimum: 0
required:
- items
type: object
Error:
title: Error
type: object
properties:
code:
type: integer
message:
type: string
required:
- code
- message
PinMediaSourceImageURL:
title: Image URL
description: Image URL-based media source
type: object
properties:
source_type:
type: string
enum:
- image_url
url:
type: string
is_standard:
type: boolean
description: Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
default: true
required:
- source_type
- url
BoardUpdate:
title: BoardUpdate
description: Board fields for updates
type: object
properties:
name:
type: string
example: Summer Recipes
description:
type: string
nullable: true
example: My favorite summer recipes
privacy:
type: string
enum:
- PUBLIC
- SECRET
PinMediaSourcePinURL:
title: Pin URL
description: Pin URL-based media source for product pin creation. Currently the field is only available to a list of beta users.
type: object
properties:
source_type:
type: string
enum:
- pin_url
is_affiliate_link:
type: boolean
description: This is an affiliate link or sponsored product. The FTC requires disclosure for paid partnerships and affiliate products.
default: false
required:
- source_type
PinMediaSourceImageBase64:
title: Image Base64
description: Base64-encoded image media source
type: object
properties:
source_type:
type: string
enum:
- image_base64
content_type:
type: string
enum:
- image/jpeg
- image/png
data:
type: string
pattern: '[a-zA-Z0-9+\/=]+'
is_standard:
type: boolean
description: Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
default: true
required:
- source_type
- content_type
- data
Paginated:
type: object
properties:
items:
type: array
items:
type: object
bookmark:
type: string
nullable: true
required:
- items
BoardOwner:
title: Board owner
type: object
properties:
username:
type: string
readOnly: true
CreativeType:
type: string
description: Ad creative type enum. For update, only draft ads may update creative type. </p><strong>Note:</strong> SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
enum:
- REGULAR
- VIDEO
- SHOPPING
- CAROUSEL
- MAX_VIDEO
- SHOP_THE_PIN
- COLLECTION
- IDEA
- SHOWCASE
- QUIZ
example: REGULAR
title: CreativeType
PinMediaSourceVideoID:
title: Video ID
description: Video ID-based media source
type: object
properties:
source_type:
type: string
enum:
- video_id
cover_image_url:
type: string
description: Cover image url.
cover_image_content_type:
type: string
description: Content type for cover image Base64.
enum:
- image/jpeg
- image/png
cover_image_data:
type: string
description: Cover image Base64.
media_id:
type: string
pattern: ^\d+$
is_standard:
type: boolean
description: Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
default: true
required:
- source_type
- media_id
Board:
title: Board
description: Board
type: object
properties:
id:
type: string
readOnly: true
example: '549755885175'
created_at:
type: string
description: Date and time of board creation.
readOnly: true
format: date-time
example: '2020-01-01T20:10:40-00:00'
board_pins_modified_at:
type: string
description: Date and time of last board pins modified.
readOnly: true
format: date-time
example: '2020-01-01T20:10:40-00:00'
name:
type: string
example: Summer Recipes
description:
type: string
nullable: true
example: My favorite summer recipes
collaborator_count:
type: integer
description: Count of collaborators on the board.
minimum: 0
readOnly: true
example: 17
pin_count:
type: integer
description: Count of pins on the board.
minimum: 0
readOnly: true
example: 5
follower_count:
type: integer
description: Board follower count.
readOnly: true
minimum: 0
example: 13
media:
type: object
readOnly: true
description: Board media.
properties:
image_cover_url:
type: string
nullable: true
description: Board cover image.
example: https://i.pinimg.com/400x300/fd/cd/d5/fdcdd5a6d8a80824add0d054125cd957.jpg
pin_thumbnail_urls:
type: array
description: Board pin thumbnail urls.
items:
type: string
example:
- https://i.pinimg.com/150x150/b4/57/10/b45710f1ede96af55230f4b43935c4af.jpg
- https://i.pinimg.com/150x150/dd/ff/46/ddff4616e39c1935cd05738794fa860e.jpg
- https://i.pinimg.com/150x150/84/ac/59/84ac59b670ccb5b903dace480a98930c.jpg
- https://i.pinimg.com/150x150/4c/54/6f/4c546f521be85e30838fb742bfff6936.jpg
owner:
allOf:
- $ref: '#/components/schemas/BoardOwner'
type: object
readOnly: true
privacy:
type: string
default: PUBLIC
description: Privacy setting for a board. Learn more about <a href="https://help.pinterest.com/en/article/secret-boards">secret boards</a> and <a href
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinterest/refs/heads/main/openapi/pinterest-board-api-openapi.yml