Pinterest Assets API
The Assets API from Pinterest — 9 operation(s) for assets.
OpenAPI Specification
openapi: 3.0.3
info:
version: 5.13.0
title: Pinterest Assets 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: Assets
paths:
/businesses/{business_id}/assets/{asset_id}/members:
get:
summary: Get members with access to asset
description: Get all the members the requesting business has granted access to on the given asset.
operationId: business_asset_members/get
security:
- pinterest_oauth2:
- biz_access:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
- $ref: '#/components/parameters/path_asset_id'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_business_access_start_index'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
description: List of members with permissions to the asset.
items:
$ref: '#/components/schemas/UserSingleAssetBinding'
description: Sucess
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Assets
/businesses/{business_id}/assets/{asset_id}/partners:
get:
summary: Get partners with access to asset
description: 'Get all the partners the requesting business has granted access to on the given asset.
Note: If the asset has been shared with you, an empty array will be returned. This is because an asset shared with
you cannot be shared with a different partner.'
operationId: business_asset_partners/get
security:
- pinterest_oauth2:
- biz_access:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
- $ref: '#/components/parameters/path_asset_id'
- $ref: '#/components/parameters/query_business_access_start_index'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
description: List of partners with permissions to the asset.
items:
$ref: '#/components/schemas/UserSingleAssetBinding'
description: Sucess
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Assets
/businesses/{business_id}/invites/assets/access:
post:
summary: Update invite/request with an asset permission
description: "Assign asset permissions information to an existing invite/request. Can be used to:\n- Request access to a partner's asset. Note: This is only for when no existing partnership exists. If an existing\n partnership exists, use \"Create a request to access an existing partner's assets\" to request access to your\n partner's assets.\n - invite_type=\"PARTNER_REQUEST\"\n- Invite a partner to access your business assets. Note: This is only for when there is no existing partnership.\n If there is an existing partnership, use \"Assign/Update partner asset permissions\" to assign a partner access to\n new assets.\n - invite_type=\"PARTNER_INVITE\"\n- Invite a member to access your business assets. Note: This is only for when there is no existing membership.\n If there is an existing membership, use \"Assign/Update member asset permissions\" to assign a member access to new\n assets.\n - invite_type=\"MEMBER_INVITE\"\n\nTo learn more about permission levels, visit https://help.pinterest.com/en/business/article/business-manager-overview."
operationId: create_asset_invites
security:
- pinterest_oauth2:
- biz_access:read
- biz_access:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAssetInvitesRequest'
description: 'A list of invites/requests together with the asset permissions to be assigned to the invite/request.
'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateInvitesResultsResponseArray'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Assets
/businesses/{business_id}/requests/assets/access:
post:
summary: Create a request to access an existing partner's assets.
description: Create a request to access an existing partner's assets with the specified permissions. The request will be sent to the partner for approval. The assets that can be requested are ad accounts and profiles.
operationId: asset_access_requests/create
security:
- pinterest_oauth2:
- biz_access:read
- biz_access:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAssetAccessRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAssetAccessRequestResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Assets
/businesses/{business_id}/assets:
get:
summary: List business assets
description: Get all the assets the requesting business has access to. This includes assets the business owns and assets the business has access to through partnerships.
operationId: business_assets/get
security:
- pinterest_oauth2:
- biz_access:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
- name: permissions
in: query
description: A list of asset permissions used to filter the assets. Only assets where the requesting business has at least one of the specified permissions will be returned.
required: false
schema:
type: array
items:
$ref: '#/components/schemas/PermissionsWithOwner'
- $ref: '#/components/parameters/query_resource_type'
- $ref: '#/components/parameters/query_business_access_start_index'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
description: List of assets the requesting business has access to.
items:
$ref: '#/components/schemas/GetBusinessAssetsResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Assets
/businesses/{business_id}/members/{member_id}/assets:
get:
summary: Get assets assigned to a member
description: 'Get assets on which you assigned asset permissions to the given member. Can be used to:
- get all assets, regardless of asset type or
- get assets of one asset type by using the asset_type query.
The return response will include the permissions the member has to that asset and the asset type.'
operationId: business_member_assets/get
security:
- pinterest_oauth2:
- biz_access:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
- $ref: '#/components/parameters/path_business_member_user'
- $ref: '#/components/parameters/query_resource_type'
- $ref: '#/components/parameters/query_business_access_start_index'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
description: List asset permissions the given member was granted.
items:
$ref: '#/components/schemas/AssetIdPermissions'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Assets
/businesses/{business_id}/members/assets/access:
patch:
description: 'Grant multiple members access to assets and/or update multiple member''s exisiting permissions to an asset.
Note: Not all listed permissions are applicable to each asset type. For example, PROFILE_PUBLISHER would not be applicable to an asset of type AD_ACCOUNT. The permission level PROFILE_PUBLISHER is only available to an asset of the type PROFILE.
'
summary: Assign/Update member asset permissions
operationId: business_members_asset_access/update
security:
- pinterest_oauth2:
- biz_access:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMemberAssetAccessBody'
description: List of member asset permissions to create or update.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMemberAssetsResultsResponseArray'
description: response
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Assets
delete:
description: Terminate multiple members' access to an asset.
summary: Delete member access to asset
operationId: business_members_asset_access/delete
security:
- pinterest_oauth2:
- biz_access:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
requestBody:
content:
application/json:
schema:
type: object
required:
- accesses
properties:
accesses:
type: array
minItems: 1
maxItems: 100
description: List of members asset access to be deleted
items:
type: object
required:
- asset_id
- member_id
properties:
asset_id:
type: string
description: Id of the asset on which to remove member permissions.
example: '549755885175'
maxLength: 25
pattern: ^\d+$
member_id:
type: string
description: Unique identifier of the member on which to perform the asset permission removal
example: '140943737684417'
maxLength: 25
pattern: ^\d+$
description: List member assset permissions to delete.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMemberAccessResultsResponseArray'
description: response
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Assets
/businesses/{business_id}/partners/assets:
patch:
summary: Assign/Update partner asset permissions
description: 'Grant multiple partners access to assets and/or update multiple partner''s exisiting permissions to an asset.
If your partner already had permissions on the asset, they will be overriden with the new permissions you assign to them.
To learn more about permission levels, visit https://help.pinterest.com/en/business/article/business-manager-overview
Note: Not all listed permissions are applicable to each asset type. For example, PROFILE_PUBLISHER would not be
applicable to an asset of type AD_ACCOUNT. The permission level PROFILE_PUBLISHER is only available to an asset of
the type PROFILE.'
operationId: update_partner_asset_access_handler_impl
security:
- pinterest_oauth2:
- biz_access:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
requestBody:
description: A list of assets and permissions to assign to your partners.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePartnerAssetAccessBody'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePartnerAssetsResultsResponseArray'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Assets
delete:
summary: Delete partner access to asset
description: 'Terminate multiple partners'' access to an asset. If
- partner_type=INTERNAL: You will terminate a partner''s asset access to your business assets.
- partner_type=EXTERNAL: You will terminate your own access to your partner''s business assets.'
operationId: delete_partner_asset_access_handler_impl
security:
- pinterest_oauth2:
- biz_access:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeletePartnerAssetAccessBody'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DeletePartnerAssetsResultsResponseArray'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Assets
/businesses/{business_id}/partners/{partner_id}/assets:
get:
summary: Get assets assigned to a partner or assets assigned by a partner
description: 'Can be used to get the business assets your partner has granted you access to or the business assets you have
granted your partner access to. If you specify:
- partner_type=INTERNAL, you will retrieve your business assets that the partner has access to.
- partner_type=EXTERNAL, you will retrieve the partner''s business assets that the partner has granted you access to.'
operationId: business_partner_asset_access/get
security:
- pinterest_oauth2:
- biz_access:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_business_user'
- $ref: '#/components/parameters/path_business_partner_user'
- name: partner_type
in: query
description: 'Specifies whether to fetch internal or external (shared) partners.
If partner_type=INTERNAL, the asset being queried is for accesses the partner has to your business assets.<br>
If partner_type=EXTERNAL, the asset being queried is for the accesses you have to the partner''s business asset.'
example: INTERNAL
required: false
schema:
allOf:
- $ref: '#/components/schemas/PartnerType'
- default: INTERNAL
- $ref: '#/components/parameters/query_resource_type'
- $ref: '#/components/parameters/query_business_access_start_index'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_bookmark'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
description: List assets on which you granted access to your partner or assets on which your partner has granted you access.
items:
$ref: '#/components/schemas/GetPartnerAssetsResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Assets
components:
schemas:
GetBusinessAssetsResponse:
type: object
description: An object containing the permissions a business has on the asset.
properties:
asset_id:
description: Unique identifier of a business asset.
example: '549755885175'
pattern: ^\d+$
type: string
maxLength: 20
minLength: 1
asset_type:
$ref: '#/components/schemas/AssetTypeResponse'
DeleteMemberAccessResult:
type: object
description: The terminated asset access.
properties:
asset_id:
type: string
description: Unique identifier of the business asset.
example: '549755885175'
pattern: ^\d+$
member_id:
type: string
description: Unique identifier of the business member.
example: '140943737684417'
pattern: ^\d+$
UpdatePartnerAssetsResult:
type: object
description: An object containing the permissions a business partner has on the asset.
properties:
asset_id:
description: Unique identifier of a business asset.
example: '549755885175'
pattern: ^\d+$
type: string
asset_type:
$ref: '#/components/schemas/AssetTypeResponse'
partner_id:
description: Unique identifier of a business partner.
example: '140943737684417'
pattern: ^\d+$
type: string
permissions:
$ref: '#/components/schemas/PermissionsResponse'
Error:
title: Error
type: object
properties:
code:
type: integer
message:
type: string
required:
- code
- message
UsersForIndividualAssetResponse:
type: object
description: An object containing the permissions a business member has on the asset.
properties:
asset_id:
description: Unique identifier of a business asset.
example: '549755885175'
type: string
pattern: ^\d+$
member_id:
description: Unique identifier of the business member with asset access.
example: '140943737684417'
type: string
pattern: ^\d+$
permissions:
$ref: '#/components/schemas/PermissionsResponse'
BaseInviteDataResponse:
type: object
nullable: true
properties:
id:
type: string
description: Unique identifier of the invite/request.
example: '383791336903426391'
pattern: ^\d+$
invite_data:
type: object
description: Metadata for the invite/request.
properties:
invite_expiration:
type: integer
description: The date and time when the invite/request will expire. Returned in milliseconds.
example: 1709748104775
invite_status:
type: string
description: The current status of the invite. The invite can be in one of the following states PENDING, ACCEPTED, DECLINED, CANCELLED, EXPIRED.
example: PENDING
invite_type:
type: string
description: The type of invite. <br>'MEMBER_INVITE' is to invite a member to access your business assets. <br>'PARTNER_INVITE' is to invite a partner to access your business assets. <br>'PARTNER_REQUEST' is to request access a partner's business assets.
example: MEMBER_INVITE
last_updated_time:
type: integer
description: The date and time the invite/request was last updated. Returned in milliseconds.
example: 1646767577816
sent_at:
type: integer
description: The date and time the invite/request was sent/created. Returned in milliseconds.
example: 1646767577816
is_received_invite:
type: boolean
description: Indicates whether the invite/request was received.
user:
type: object
description: Metadata for the member/partner that was sent the invite/request.
allOf:
- $ref: '#/components/schemas/BusinessAccessUserSummary'
UpdateMemberAssetAccessBody:
type: object
description: An object with a list of all the new accesses.
required:
- accesses
properties:
accesses:
type: array
minItems: 1
maxItems: 50
items:
type: object
required:
- asset_id
- member_id
- permissions
properties:
asset_id:
type: string
description: Id of the asset to update.
example: '549755885175'
maxLength: 25
pattern: ^\d+$
member_id:
type: string
description: Unique identifier of the member on which to perform the update
example: '140943737684417'
maxLength: 25
pattern: ^\d+$
permissions:
type: array
description: A non-empty array of permissions to assign to the member.
example:
- ANALYST
- ADMIN
minItems: 1
maxItems: 50
items:
$ref: '#/components/schemas/Permissions'
BusinessAccessUserSummary:
type: object
description: Metadata of the member/partner that has access to the asset.
properties:
email:
description: Email of the business member/partner.
example: business0101@business.com
type: string
nullable: true
id:
description: Unique identifier of the business member/partner.
example: '383791336903426391'
type: string
nullable: true
minLength: 1
maxLength: 20
username:
description: Username of the business member/partner.
example: business0101
nullable: true
type: string
UpdateMemberAssetsResultsResponseArray:
type: object
properties:
items:
type: array
description: 'List of assigned/updated member asset access.
If there is an error, an exception object will be returned. If the action was successfully completed, a response object will be returned.'
items:
type: object
properties:
response:
$ref: '#/components/schemas/UsersForIndividualAssetResponse'
Paginated:
type: object
properties:
items:
type: array
items:
type: object
bookmark:
type: string
nullable: true
required:
- items
UpdatePartnerAssetsResultsResponseArray:
type: object
properties:
items:
type: array
description: List of assigned/updated partner asset access.
items:
type: object
$ref: '#/components/schemas/UpdatePartnerAssetsResult'
InviteBusinessRoleBinding:
type: object
description: An invite object if the invite/request was successfully updated. Will only be provided if the an invite/request is successfully updated.
nullable: true
allOf:
- $ref: '#/components/schemas/BaseInviteDataResponse'
properties:
created_by_business_id:
type: string
description: Unique identifier for the business that created the invite/request.
example: '1234567890123'
created_by_user_id:
type: string
description: Unique identifier for the user that created the invite/request.
example: '1234567890123'
user:
type: object
description: Metadata for the user that updated the invite/request.
allOf:
- $ref: '#/components/schemas/BusinessAccessUserSummary'
DeletePartnerAssetsResult:
type: object
description: The terminated asset access.
properties:
asset_id:
description: Unique identifier of a business asset.
example: '549755885175'
pattern: ^\d+$
type: string
asset_type:
$ref: '#/components/schemas/AssetTypeResponse'
permissions:
$ref: '#/components/schemas/PermissionsResponse'
is_shared_partner:
type: boolean
description: If is_shared_partner=FALSE, you terminated a partner's asset access to your business asset.<br> If is_shared_partner=TRUE, you terminated your asset access to your partner's business asset.
example: false
partner_id:
description: Unique identifier of a business partner.
example: '140943737684417'
pattern: ^\d+$
type: string
CreateAssetInvitesRequest:
description: Request body for updating asset roles for existing invites.
type: object
required:
- invites
properties:
invites:
type: array
minItems: 1
maxItems: 50
items:
$ref: '#/components/schemas/CreateAssetInvitesRequestItem'
GetPartnerAssetsResponse:
type: object
description: An object containing the permissions a you/your business partner has on the asset.
properties:
asset_id:
description: Unique identifier of a business asset.
example: '549755885175'
pattern: ^\d+$
type: string
maxLength: 20
minLength: 1
asset_type:
$ref: '#/components/schemas/AssetTypeResponse'
permissions:
type: array
description: The permissions you or your partner has on the asset. If partner_type=INTERNAL, the permission levels are for the access the partner has to your business asset.<br> If partner_type=EXTERNAL, the permission levels are for the access you have to the partner's business asset.
example:
- FINANCE_MANAGER
- CATALOGS_MANAGER
- AUDIENCE_MANAGER
items:
description: The permission level a user has on an asset.
example: FINANCE_MANAGER
type: string
PermissionsResponse:
type: array
description: Permission levels member or partner has on an asset.
example:
- FINANCE_MANAGER
- CATALOGS_MANAGER
- AUDIENCE_MANAGER
items:
type: string
DeletePartnerAssetsResultsResponseArray:
type: object
properties:
items:
type: array
description: List of terminated asset access.
items:
type: object
$ref: '#/components/schemas/DeletePartnerAssetsResult'
UserSingleAssetBinding:
type: object
description: An object containing the permissions a business member/partner has on the asset.
properties:
permissions:
$ref: '#/components/schemas/PermissionsResponse'
user:
$ref: '#/components/schemas/BusinessAccessUserSummary'
CreateAssetAccessRequestBody:
type: object
description: An object containing a list of all the asset access requests
required:
- asset_requests
properties:
asset_requests:
type: array
minItems: 1
maxItems: 100
items:
type: object
required:
- partner_id
- asset_id_to_permissions
properties:
partner_id:
description: Unique identifier of a business partner to request asset access to.
example: '809944451643622187'
type: string
pattern: ^\d+$
asset_id_to_permissions:
$ref: '#/components/schemas/AssetIdToPermissions'
PermissionsWithOwner:
type: string
enum:
- ADMIN
- ANALYST
- FINANCE_MANAGER
- AUDIENCE_MANAGER
- CAMPAIGN_MANAGER
- CATALOGS_MANAGER
- PROFILE_PUBLISHER
- OWNER
CreateAssetAccessRequestErrorMessage:
type: array
description: A list of errors associated with the asset access requests. Will be returned if there is an error.
nullable: true
items:
type: object
properties:
code:
type: integer
description: Error code associated with the error in requesting asset access.
example: 2932
messages:
type: array
example:
- 'Invalid asset id: 549760723247'
- 'Invalid asset id: 546760723248'
items:
type: string
AssetIdPermissions:
type: object
description: An object containing the permissions a business member has on the asset.
properties:
asset_id:
description: Unique identifier of a business asset.
example: '549755885175'
pattern: ^\d+$
type: string
maxLength: 20
minLength: 1
asset_type:
$ref: '#/components/schemas/AssetTypeResponse'
permissions:
$ref:
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinterest/refs/heads/main/openapi/pinterest-assets-api-openapi.yml