> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Pinterest API
> Options for posting using the Pinterest API
## Posting an Image Pin to Pinterest
The Pinterest API requires an image to be included in the post. Other parameters are optional.
Please see [Pinterest Media Guidelines](/media-guidelines/pinterest) and [Pinterest Authorization](/dashboard/connect-social-accounts/pinterest) for more information.
```json Pinterest Post theme={"system"}
{
"post": "The best Pinterest API ever!", // Maximum 500 characters or empty string
"platforms": ["pinterest"],
"mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"]
}
```
## Pinterest Options
You can set additional options for a post by using the `pinterestOptions` parameter.
```json Pinterest Post theme={"system"}
{
"post": "The best Pinterest API ever!", // Maximum 500 characters or empty string
"platforms": ["pinterest"],
"mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"],
"pinterestOptions": {
"altText": ["This is my best pic", "😃 here is the next one"], // maximum 500 characters
"boardId": "93383204522",
"carouselOptions": [
{
"title": "Image 1",
"link": "https://www.cnn.com",
"description": "Super Image 1"
},
{
"title": "Image 2",
"link": "https://www.google.com",
"description": "Super Image 2"
}
],
"link": "https://www.ayrshare.com", // maximum 2048 characters
"note": "Private note", // maximum 1000 characters
"thumbNail": "https://images.ayrshare.com/imgs/GhostBusters.jpg",
"title": "A Pinterest Board for You" // maximum 100 characters
}
}
```
Pinterest options are optional fields that can be used to control the post.
The alternative text for images and videos for accessibility and screen readers. Maximum 500 characters.
See [Pinterest Alternative Text](/apis/post/social-networks/pinterest#alternative-text) for more information.
Post to another one of the user's Pinterest Boards by specifying the ID from the /user/details endpoint.
If not specified, posts to the default linked board.
See [Pinterest Board ID](/apis/post/social-networks/pinterest#board-id) for more information.
Add up to 5 images as a Pinterest carousel with optional titles, links, and descriptions.
Each object can contain: `title`, `link`, and `description`.
See [Pinterest Image Carousel](/apis/post/social-networks/pinterest#pinterest-image-carousel) for more information.
The destination URL users will be directed to when clicking the pin image. Maximum 2048 characters.
Creates a clickable link attached to your pin.
See [Pin Link](/apis/post/social-networks/pinterest#pin-link) for more information.
Add private notes to individual Pins that only you and board collaborators can see. Maximum 1000 characters.
See [Pin Note](/apis/post/social-networks/pinterest#pin-note) for more information.
Set a thumbnail for video pins. Must be PNG or JPG, same dimensions as video, under 10MB.
Required for video pins.
See [Video Pin (Thumbnail)](/apis/post/social-networks/pinterest#video-pin-thumbnail) for more information.
The title of the pin to display in the "Add your title" section. Maximum 100 characters.
See [Pin Title](/apis/post/social-networks/pinterest#pin-title) for more information.
\*Links in the `post` field are not clickable. Please use the `link` field to add a
clickable link to the Pin.
See [Pinterest Media Guidelines](/media-guidelines/pinterest) for more information.
## Alternative Text
Add alternative text, also known as alt text, to a Pinterest image or video. Pinterest alt text is an accessibility feature used for additional user info and screen readers.
Use the `altText` in the `pinterestOptions` object.
```json Pinterest Alt Text theme={"system"}
{
"pinterestOptions": {
"altText": ["This is my best pic", "😃 here is the next one"]
}
}
```
The alt text is limited to 500 characters.
## Board ID
Post to another one of the user's Pinterest Boards by specifying the ID obtained from the [/user/details](/apis/user/pinterest-board) endpoint. Otherwise post to the default linked board.
Use the `boardId` in the `pinterestOptions` object.
```json Pinterest Board ID theme={"system"}
{
"pinterestOptions": {
"boardId": "93383204522"
}
}
```
## Character Limits
Please see [Pinterest Character Limits](/help-center/technical-support/character_limits#pinterest-character-limits) for more information.
## Pin Link
The destination URL that users will be directed to when they click on your pin image. This creates a clickable link attached to your pin. Maximum length is 2048 characters.
Use the `link` in the `pinterestOptions` object.
```json Pin Link theme={"system"}
{
"pinterestOptions": {
"link": "https://www.ayrshare.com"
}
}
```
## Pin Note
You can add private notes to individual Pins on your boards. Only you and board collaborators will be able to see them.
Use the `note` in the `pinterestOptions` object.
```json Pin Note theme={"system"}
{
"pinterestOptions": {
"note": "Private note for collaborators"
}
}
```
## Pinterest Image Carousel
Post up to five images as a Pinterest carousel. By adding more than one media URL, a carousel is automatically created. You can also add in optional carousel parameter. Please see below.
```json Pinterest Carousel Post theme={"system"}
{
"post": "Carousel Time",
"platforms": ["pinterest"],
"mediaUrls": [
"https://img.ayrshare.com/random/photo-1.jpg",
"https://img.ayrshare.com/random/photo-2.jpg"
],
"pinterestOptions": {
"carouselOptions": [
// optional
{
"title": "Image 1",
"link": "https://www.cnn.com",
"description": "Super Image 1"
},
{
"title": "Image 2",
"link": "https://www.google.com",
"description": "Super Image 2"
}
]
}
}
```
The optional `carouselOptions` field takes an array of objects. Each carousel object corresponds to the equivalent media URL string, e.g. the first carousel object refers to the first `mediaUrl` string.
- `title`: The image title.
- `link`: The external destination link for the image.
- `description`: The image description.
## Pinterest Mentions
While you can add a @handle to a Pinterest post, Pinterest does not support resolving mentions in the post text.
The @handle will remain as plain text.
## Pin Title
The title of the pin to display. This appears in the "Add your title" section of a new pin. Maximum 100 characters.
Use the `title` in the `pinterestOptions` object.
```json Pin Title theme={"system"}
{
"pinterestOptions": {
"title": "A Pinterest Board for You"
}
}
```
## Video Pin (Thumbnail)
A video may be posted as a Pin using the standard `mediaUrls` field in the [/post endpoint](/apis/post/post). Additionally, a thumbnail image URL **must be included** with the video with a valid media Content-Type such as `image/jpeg`.
Please see [requirements](/media-guidelines/pinterest).
```json Video Pin with Thumbnail theme={"system"}
{
"pinterestOptions": {
// required
"thumbNail": "https://images.unsplash.com/photo-1513093496871-0a81425386e5?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=MnwxNjQ1ODN8MHwxfHJhbmRvbXx8fHx8fHx8fDE2Mzg0ODAzNDA&ixlib=rb-1.2.1&q=80&w=400"
}
}
```
Additional information on [posting Pins using the API](https://www.ayrshare.com/pinterest-api-integration-on-ayrshare/).
If your video doesn't end in a known video extension such as mp4, please use the `isVideo` parameter. See the [/post endpoint](/apis/post/post) for details.