Pinterest Feeds API
The Feeds API from Pinterest — 4 operation(s) for feeds.
OpenAPI Specification
openapi: 3.0.3
info:
version: 5.13.0
title: Pinterest Feeds 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: Feeds
paths:
/catalogs/feeds:
get:
x-ratelimit-category: catalogs_read
summary: List feeds
description: 'Fetch feeds owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
For Retail partners, refer to <a href=''https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs''>Before you get started with Catalogs</a>. For Hotel parterns, refer to <a href=''/docs/shopping/catalog/''>Pinterest API for shopping</a>.'
operationId: feeds/list
security:
- pinterest_oauth2:
- catalogs:read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_catalogs_catalog_id'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/CatalogsFeed'
description: Success
'400':
description: Invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: Parameter 'page_size' was not numeric (was 3e)"
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UnauthorizedAccess:
value:
code: 29
message: You are not permitted to access that resource.
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Feeds
post:
x-ratelimit-category: catalogs_write
summary: Create feed
description: 'Create a new feed owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Please, be aware that "default_country"
and "default_locale" are not required in the spec for forward compatibility
but for now the API will not accept requests without those fields.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
For Retail partners, refer to <a href=''https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs''>Before you get started with Catalogs</a>. For Hotel parterns, refer to <a href=''/docs/shopping/catalog/''>Pinterest API for shopping</a>.
Note: The catalog type of Creative Assets is only allowed in the <a href=''https://api-sandbox.pinterest.com/v5''>Pinterest API Sandbox</a>.
If access is required, please contact your partner manager.'
operationId: feeds/create
security:
- pinterest_oauth2:
- catalogs:read
- catalogs:write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_ad_account_id'
requestBody:
description: Request object used to created a feed.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CatalogsVerticalFeedsCreateRequest'
- $ref: '#/components/schemas/CatalogsFeedsCreateRequest'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogsFeed'
description: Success
'400':
description: Invalid feed parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: 'Invalid request: ...'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UnauthorizedAccess:
value:
code: 29
message: You are not permitted to access that resource.
'403':
description: Business account required.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
BusinessAccountRequired:
value:
code: 654
message: You must have a business account to operate as merchant.
MerchantDisapproved:
value:
code: 2625
message: Sorry, you cannot perform this action. Account is disapproved.
'409':
description: User website required.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UserWebsiteRequired:
value:
code: 4168
message: User does not have a website.
UserWebsiteNotVerified:
value:
code: 4169
message: User does not have a verified website.
'422':
description: Unique feed name is required.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
FeedDuplicatedName:
value:
code: 4170
message: The feed name already exists.
'501':
description: Not implemented (absent "default_country" or "default_locale").
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
NotImplemented:
value:
code: 4181
message: Not implemented at the moment. Please, see documentation
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Feeds
/catalogs/feeds/{feed_id}:
get:
x-ratelimit-category: catalogs_read
summary: Get feed
description: 'Get a single feed owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
For Retail partners, refer to <a href=''https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs''>Before you get started with Catalogs</a>. For Hotel parterns, refer to <a href=''/docs/shopping/catalog/''>Pinterest API for shopping</a>.'
operationId: feeds/get
security:
- pinterest_oauth2:
- catalogs:read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_feed_id'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogsFeed'
description: Success
'400':
description: Invalid feed parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: '''feed_id'' value ''1511851494501_'' must match the pattern: ^\d+$"}'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UnauthorizedAccess:
value:
code: 29
message: You are not permitted to access that resource.
'404':
description: Data feed not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
FeedNotFound:
value:
code: 4161
message: Sorry! We could not find your catalogs feed.
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Feeds
patch:
x-ratelimit-category: catalogs_write
summary: Update feed
description: 'Update a feed owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
For Retail partners, refer to <a href=''https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs''>Before you get started with Catalogs</a>. For Hotel parterns, refer to <a href=''/docs/shopping/catalog/''>Pinterest API for shopping</a>.
Note: The catalog type of Creative Assets is only allowed in the <a href=''https://api-sandbox.pinterest.com/v5''>Pinterest API Sandbox</a>.
If access is required, please contact your partner manager.'
operationId: feeds/update
security:
- pinterest_oauth2:
- catalogs:read
- catalogs:write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_feed_id'
- $ref: '#/components/parameters/query_ad_account_id'
requestBody:
description: Request object used to update a feed.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CatalogsVerticalFeedsUpdateRequest'
- $ref: '#/components/schemas/CatalogsFeedsUpdateRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogsFeed'
description: Success
'400':
description: Invalid feed parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: 'Invalid request: ...'
'403':
description: Forbidden. Account not approved for feed mutations yet.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
MerchantDisapproved:
value:
code: 2625
message: Sorry, you cannot perform this action. Account is disapproved.
MerchantUnderReview:
value:
code: 2626
message: Sorry, you cannot perform this action. Account is under review.
'404':
description: Data feed not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
FeedNotFound:
value:
code: 4161
message: Sorry! We could not find your catalogs feed.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Feeds
delete:
x-ratelimit-category: catalogs_write
summary: Delete feed
description: 'Delete a feed owned by the "operating user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
For Retail partners, refer to <a href=''https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs''>Before you get started with Catalogs</a>. For Hotel parterns, refer to <a href=''/docs/shopping/catalog/''>Pinterest API for shopping</a>.'
operationId: feeds/delete
security:
- pinterest_oauth2:
- catalogs:read
- catalogs:write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_feed_id'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
'204':
description: Feed deleted successfully.
'400':
description: Invalid feed parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: '''feed_id'' value ''1511851494501_'' must match the pattern: ^\d+$"}'
'403':
description: Forbidden. Account not approved for feed mutations yet.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
MerchantDisapproved:
value:
code: 2625
message: Sorry, you cannot perform this action. Account is disapproved.
MerchantUnderReview:
value:
code: 2626
message: Sorry, you cannot perform this action. Account is under review.
'404':
description: Data feed not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
FeedNotFound:
value:
code: 4161
message: Sorry! We could not find your catalogs feed.
'409':
description: Conflict. Can't delete a feed with active promotions.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
FeedHasActivePromotions:
value:
code: 4162
message: We can't disable a Product Group with active promotions.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Feeds
/catalogs/feeds/{feed_id}/ingest:
post:
x-ratelimit-category: catalogs_write
summary: Ingest items for a given feed
description: 'Ingest items for a given feed owned by the "operation user_account".
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
<a href=''/docs/shopping/catalog/''>Learn more</a>
Note: This endpoint is only allowed in the Pinterest API Sandbox (https://api-sandbox.pinterest.com/v5).
Go to https://developers.pinterest.com/docs/dev-tools/sandbox/ for more information.'
operationId: feeds/ingest
security:
- pinterest_oauth2:
- catalogs:write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_feed_id'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
'204':
description: The ingestion process was successfully started.
'400':
description: Invalid feed parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: '''feed_id'' value ''1511851494501_'' must match the pattern: ^\d+$"}'
'403':
description: Forbidden. Account not approved for feed mutations yet.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
MerchantDisapproved:
value:
code: 2625
message: Sorry, you cannot perform this action. Account is disapproved.
MerchantUnderReview:
value:
code: 2626
message: Sorry, you cannot perform this action. Account is under review.
'404':
description: Data feed not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
FeedNotFound:
value:
code: 4161
message: Sorry! We could not find your catalogs feed.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Feeds
/catalogs/feeds/{feed_id}/processing_results:
get:
x-ratelimit-category: catalogs_read
summary: List processing results for a given feed
description: 'Fetch a feed processing results owned by the "operation user_account". Please note that for now the bookmark parameter is not functional and only the first page will be available until it is implemented in some release in the near future.
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
<a href=''/docs/shopping/catalog/''>Learn more</a>'
operationId: feed_processing_results/list
security:
- pinterest_oauth2:
- catalogs:read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_feed_id'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/CatalogsFeedProcessingResult'
description: Success
'400':
description: Invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: Parameter 'page_size' was not numeric (was 3e)"
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UnauthorizedAccess:
value:
code: 29
message: You are not permitted to access that resource.
'404':
description: Feed not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
FeedNotFound:
value:
code: 4161
message: Sorry! We could not find your catalogs feed.
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Feeds
components:
parameters:
path_catalogs_feed_id:
description: Unique identifier of a feed
in: path
required: true
name: feed_id
schema:
type: string
pattern: ^\d+$
query_ad_account_id:
name: ad_account_id
description: Unique identifier of an ad account.
in: query
schema:
type: string
pattern: ^\d+$
maxLength: 18
query_catalogs_catalog_id:
description: Filter entities for a given catalog_id. If not given, all catalogs are considered.
in: query
required: false
name: catalog_id
schema:
type: string
pattern: ^\d+$
query_page_size:
name: page_size
description: Maximum number of items to include in a single page of the response. See documentation on <a href='/docs/getting-started/pagination/'>Pagination</a> for more information.
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 250
default: 25
query_bookmark:
name: bookmark
description: Cursor used to fetch the next page of items
in: query
required: false
schema:
type: string
schemas:
CatalogsFeedIngestionDetails:
type: object
properties:
errors:
$ref: '#/components/schemas/CatalogsFeedIngestionErrors'
info:
$ref: '#/components/schemas/CatalogsFeedIngestionInfo'
warnings:
$ref: '#/components/schemas/CatalogsFeedIngestionWarnings'
required:
- errors
- info
- warnings
CatalogsFeedIngestionErrors:
type: object
properties:
LINE_LEVEL_INTERNAL_ERROR:
type: integer
description: We experienced a technical difficulty and were unable to ingest this some items. The next ingestion will happen in 24 hours.
LARGE_PRODUCT_COUNT_DECREASE:
type: integer
enum:
- 1
description: The product count has decreased by more than 99% compared to the last successful ingestion.
ACCOUNT_FLAGGED:
type: integer
description: We detected an issue with your account and are not currently ingesting your items. Please review our policies at policy.pinterest.com/community-guidelines#section-spam or contact us at help.pinterest.com/contact for more information.
IMAGE_LEVEL_INTERNAL_ERROR:
type: integer
description: We experienced a technical difficulty and were unable to download some images. The next download attempt will happen in 24 hours.
IMAGE_FILE_NOT_ACCESSIBLE:
type: integer
description: Image files are unreadable. Please upload new files to continue.
IMAGE_MALFORMED_URL:
type: integer
description: Image files are unreadable. Please check your link and upload new files to continue.
IMAGE_FILE_NOT_FOUND:
type: integer
description: Image files are unreadable. Please upload new files to continue.
IMAGE_INVALID_FILE:
type: integer
description: Image files are unreadable. Please upload new files to continue.
CatalogsFeed:
type: object
title: catalogs_feed
description: Catalogs Feed object
oneOf:
- $ref: '#/components/schemas/CatalogsRetailFeed'
- $ref: '#/components/schemas/CatalogsHotelFeed'
- $ref: '#/components/schemas/CatalogsCreativeAssetsFeed'
discriminator:
propertyName: catalog_type
mapping:
RETAIL: '#/components/schemas/CatalogsRetailFeed'
HOTEL: '#/components/schemas/CatalogsHotelFeed'
CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsFeed'
CatalogsFeedValidationWarnings:
type: object
properties:
AD_LINK_FORMAT_WARNING:
type: integer
description: Some items have ad links that are formatted incorrectly.
AD_LINK_SAME_AS_LINK:
type: integer
description: Some items have ad link URLs that are duplicates of the link URLs for those items.
TITLE_LENGTH_TOO_LONG:
type: integer
description: The title for some items were truncated because they contain too many characters.
DESCRIPTION_LENGTH_TOO_LONG:
type: integer
description: The description for some items were truncated because they contain too many characters.
GENDER_INVALID:
type: integer
description: Some items have gender values that are formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences.
AGE_GROUP_INVALID:
type: integer
description: Some items have age group values that are formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences.
SIZE_TYPE_INVALID:
type: integer
description: Some items have size type values that are formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences.
SIZE_SYSTEM_INVALID:
type: integer
description: Some items have size system values which are not one of the supported size systems.
LINK_FORMAT_WARNING:
type: integer
description: Some items have an invalid product link which contains invalid UTM tracking paramaters.
SALES_PRICE_INVALID:
type: integer
description: Some items have sale price values that are higher than the original price of the item.
PRODUCT_CATEGORY_DEPTH_WARNING:
type: integer
description: Some items only have 1 or 2 levels of google_product_category values, which may limit visibility in recommendations, search results and shopping experiences.
ADWORDS_FORMAT_WARNING:
type: integer
description: Some items have adwords_redirect links that are formatted incorrectly.
ADWORDS_SAME_AS_LINK:
type: integer
description: Some items have adwords_redirect URLs that are duplicates of the link URLs for those items.
DUPLICATE_HEADERS:
type: integer
description: Your feed contains duplicate headers.
FETCH_SAME_SIGNATURE:
type: integer
description: Ingestion completed early because there are no changes to your feed since the last successful update.
enum:
- 1
ADDITIONAL_IMAGE_LINK_LENGTH_TOO_LONG:
type: integer
description: Some items have additional_image_link URLs that contain too many characters, so those items will not be published.
ADDITIONAL_IMAGE_LINK_WARNING:
type: integer
description: Some items have additional_image_link URLs that are formatted incorrectly and will not be published with your items.
IMAGE_LINK_WARNING:
type: integer
description: Some items have image_link URLs that are formatted incorrectly and will not be published with those items.
SHIPPING_INVALID:
type: integer
description: Some items have shipping values that are formatted incorrectly.
TAX_INVALID:
type: integer
description: Some items have tax values that are formatted incorrectly.
SHIPPING_WEIGHT_INVALID:
type: integer
description: Some items have invalid shipping_weight values.
EXPIRATION_DATE_INVALID:
type: integer
description: Some items have expiration_date values that are formatted incorrectly, those items will be published without an expiration date.
AVAILABILITY_DATE_INVALID:
type: integer
description: Some items have availability_date values that are formatted incorrectly, those items will be published without an availability date.
SALE_DATE_INVALID:
type: integer
description: Some items have sale_price_effective_date values that are formatted incorrectly, those items will be published without a sale date.
WEIGHT_UNIT_INVALID:
type: integer
description: Some items have weight_unit values that are formatted incorrectly, those items will be published without a weight unit.
IS_BUNDLE_INVALID:
type: integer
description: Some items have is_bundle values that are formatted incorrectly, those items will be published without being bundled with other products.
UPDATED_TIME_INVALID:
type: integer
description: Some items have updated_time values thate are formatted incorrectly, those items will be published without an updated time.
CUSTOM_LABEL_LENGTH_TOO_LONG:
type:
# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinterest/refs/heads/main/openapi/pinterest-feeds-api-openapi.yml