# OmniSocials Pinterest API

> Publish image, carousel and video Pins to any of your boards, each with its own title, link and alt text. Tag your products and read what every Pin earns. One API key, no Pinterest app of your own.

This is the machine-readable version of [omnisocials.com/pinterest-api](https://omnisocials.com/pinterest-api), maintained for AI agents. Facts checked against the OmniSocials app and API on October 17, 2026. Platform reference: [docs.omnisocials.com/platforms/pinterest](https://docs.omnisocials.com/platforms/pinterest). API reference: [docs.omnisocials.com/api](https://docs.omnisocials.com/api).

## Basics

- Base URL: `https://api.omnisocials.com/v1`
- Auth: `Authorization: Bearer omsk_live_...`. One key belongs to one workspace. Keys are created in the app under Settings, API.
- Channel id in `accounts`: `pinterest`. The account connects inside the OmniSocials app, not through the API.
- Rate limit: 100 requests per minute per key. A 429 carries `Retry-After`.
- Responses use a `{ "data": ... }` envelope. Create returns `201`.
- Webhooks: `post.scheduled`, `post.published`, `post.failed`, `post.approved`, `post.rejected`, signed with HMAC-SHA256 in `X-OmniSocials-Signature`.

## Skip the Pinterest access tiers

Pinterest’s own API starts on Trial access, 1,000 requests a day for your whole app. More means applying for Standard access, then 30-day tokens to refresh and a video upload to poll. OmniSocials already did that work.

- On your own: Developer app, Trial access, Standard access, Token refresh, Video upload, Polling, Retries, then the first post.
- Permissions your own app must get approved: `boards:read`, `boards:write`, `pins:read`, `pins:write`, `user_accounts:read`.
- On OmniSocials: sign in, create an API key, POST. One sign-in grants all 5 scopes.

## Schedule a post

```bash
curl -X POST https://api.omnisocials.com/v1/posts/create \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "Post from your own code: SDKs in 8 languages.",
  "accounts": ["pinterest"],
  "media_urls": ["https://cdn.example.com/sdks.png"],
  "schedule_at": "2026-10-22T18:00:00Z",
  "pinterest": {
    "board_id": "1051379544199222969",
    "title": "OmniSocials SDKs in 8 languages",
    "link": "https://docs.omnisocials.com",
    "alt_text": "SDK code sample"
  }
}'
```

The answer (`201`, shortened):

```json
{
  "data": {
    "id": "1024",
    "status": "scheduled",
    "app_url": "https://app.omnisocials.com/create-post/1024"
  }
}
```

## Every Pin, one request

Image Pins, carousels of 2 to 5 images and video Pins share one request shape. Pick the board, add the media, a title, a link and a time. OmniSocials checks the media against Pinterest’s rules before it uploads.

- **Image Pins.** One image with its own title, link and alt text. A Pin taller than 2:3 is kept as it is, or cropped when you ask for it. (`pinterest.title`, `pinterest.link`, `media_fit`)
- **Carousel Pins.** 2 to 5 images in one Pin, all at one aspect ratio. A slide that doesn’t match answers 400 with mismatched_slides, before anything is sent. (`media_urls`, `mismatched_slides`)
- **Video Pins.** One MP4 or MOV, with your own cover image or the frame at 1 second. OmniSocials uploads it, waits for Pinterest to process it, then creates the Pin. (`pinterest.video_cover`)

### Pin

```json
{
  "content": "Post from your own code: SDKs in 8 languages.",
  "accounts": ["pinterest"],
  "media_urls": ["https://cdn.example.com/sdks.png"],
  "schedule_at": "2026-10-22T18:00:00Z",
  "pinterest": {
    "board_id": "1051379544199222969",
    "title": "OmniSocials SDKs in 8 languages",
    "link": "https://docs.omnisocials.com",
    "alt_text": "SDK code sample"
  }
}
```

### Carousel

```json
{
  "content": "Best times to post, worked out from your posts.",
  "accounts": ["pinterest"],
  "media_urls": [
    "https://cdn.example.com/best-times-1.png",
    "https://cdn.example.com/best-times-2.png"
  ],
  "schedule_at": "2026-10-24T11:00:00Z",
  "pinterest": {
    "board_id": "1051379544199222969",
    "title": "Best times to post",
    "link": "https://app.omnisocials.com"
  }
}
```

### Video

```json
{
  "content": "Upload videos up to 1GB.",
  "accounts": ["pinterest"],
  "media_urls": ["https://cdn.example.com/uploads.mp4"],
  "schedule_at": "2026-10-23T15:00:00Z",
  "pinterest": {
    "board_id": "1051379544199222969",
    "title": "1GB video uploads",
    "video_cover": "https://cdn.example.com/uploads-cover.jpg"
  }
}
```

## Boards, links and product tags

Every Pin goes to a board you pick from all of the account’s boards, with its own title, link and alt text. The options in the app and the pinterest object in the API set the same fields.

`POST /v1/posts/create`:

```json
{
  "content": "Post from your own code: SDKs in 8 languages.",
  "accounts": ["pinterest"],
  "media_urls": ["https://cdn.example.com/sdks.png"],
  "schedule_at": "2026-10-22T18:00:00Z",
  "pinterest": {
    "board_id": "1051379544199222969",
    "title": "OmniSocials SDKs in 8 languages",
    "link": "https://docs.omnisocials.com",
    "alt_text": "SDK code sample"
  }
}
```

- **Every board.** The accounts call lists all of the account’s boards, not only the first page. A Pin needs one, and new boards are made right in the composer. (`GET /v1/accounts`, `pinterest.board_id`)
- **Title, link and alt text.** Each Pin gets its own title of up to 100 characters, a destination link and alt text of up to 500. Without alt text, the image’s own is used. (`pinterest.title`, `pinterest.link`, `pinterest.alt_text`)
- **Product tags.** Tag up to 24 of your own product Pins. List them through the API or the MCP server; product_tags_result says what Pinterest tagged. (`pinterest.product_tags`, `/pinterest/products`)

## Connect Pinterest once, post from code

Sign in with Pinterest once inside OmniSocials. Create an API key, and your code lists the boards, publishes Pins and reads what they earn.

- **Pinterest sign-in.** Sign in with Pinterest once inside OmniSocials. One account per workspace, and its tokens are refreshed for you.
- **A key per workspace.** A key only reaches its own workspace, so every client or project gets a key of its own.
- **Every board, listed.** The accounts call returns the account with all of its boards, so your code can offer the same board picker. (`GET /v1/accounts`, `boards`)

`GET /v1/accounts?platform=pinterest` answers:

```json
{
  "data": [
    {
      "id": "4127_pinterest",
      "platform": "pinterest",
      "username": "omnisocials",
      "display_name": "OmniSocials",
      "content_types": ["post"],
      "status": "active",
      "boards": [
        { "id": "1051379544199222969", "name": "Changelog" },
        { "id": "1051379544199223417", "name": "Developers" }
      ]
    }
  ],
  "workspace_name": "OmniSocials"
}
```

## Read what Pinterest reports

Impressions, saves, pin clicks and outbound clicks per Pin, with their rates, and views and watch time for video Pins. The API returns the same numbers the app charts.

- **Per Pin.** Impressions, saves, pin clicks, outbound clicks, reactions and comments, with their rates. Video Pins add views, starts and watch time. (`/analytics/posts/:id`)
- **Per account and workspace.** A daily snapshot of the account: followers, monthly views, Pins and boards. Plus a workspace overview. (`/analytics/accounts`, `/analytics/overview`)
- **Best times to post.** Days and hours worked out from your own Pins, once 15 of them are analyzed. (`/analytics/best-times`)

`GET /v1/analytics/posts/1019` answers:

```json
{
  "data": {
    "post_id": "1019",
    "platforms": {
      "pinterest": {
        "metrics": {
          "impressions": 1600, "saves": 56,
          "pin_clicks": 88,
          "outbound_clicks": 24,
          "link_clicks": 24,
          "likes": 9, "comments": 1,
          "save_rate": 3.5,
          "pin_click_rate": 5.5,
          "outbound_click_rate": 1.5,
          "engagement": 178
        }
      }
    }
  }
}
```

## Pinterest’s rules, in one place

OmniSocials checks every Pin against them before it reaches Pinterest, so a bad file fails in your request, not at publish time.

| Limit | Value |
| --- | --- |
| Description | 800 characters, a Pin needs one |
| Title | 100 characters, optional |
| Alt text | 500 characters |
| Board | Required on every Pin |
| Images | JPEG, PNG or WebP, up to 20 MB each |
| Carousel | 2 to 5 images at one aspect ratio |
| Video | MP4 or MOV, 100 MB in media_urls, 1 GB via upload-from-url |
| Product tags | Up to 24 of your own product Pins |
| Rate limit | 100 requests a minute per API key |
| Accounts | One Pinterest account per workspace |

## Your first Pin in three steps

About five minutes from sign-up to a scheduled Pin on your board. Then hand the key to your coding agent.

1. **Create an API key** (`Settings › API`). Start your trial, open Settings, API and create a key. It is shown once.
2. **Connect Pinterest** (`GET /v1/accounts`). Sign in with Pinterest in OmniSocials once. Then list the account and its boards from your code.
3. **Send your first Pin** (`POST /v1/posts/create`). Pass a board_id from the list. Post now with create-and-publish, or add schedule_at to plan it.

## FAQ

### Do I need my own Pinterest developer app?

No. The account connects through OmniSocials’ Pinterest app, with Pinterest’s own sign-in. You call the OmniSocials API with an API key and never handle Pinterest tokens or access tiers.

### Which Pinterest accounts can I post to?

The Pinterest account you sign in with. Each workspace connects one account; a second account goes in a second workspace with its own key.

### Can my own users connect their Pinterest accounts through the API?

Not yet. Pinterest connects inside the OmniSocials app. Every API key in that workspace can then post to it.

### How do I pick the board?

GET /v1/accounts lists every board of the account with its id and name, not only the first page. Pass the id as pinterest.board_id: a Pin always needs a board. New boards are made in the OmniSocials composer. Through the MCP server, an agent that gets no board uses the first one and says which.

### Which formats can I publish?

Image Pins, carousel Pins of 2 to 5 images and video Pins. Every Pin has a description of up to 800 characters, and can have a title of up to 100, a link and alt text of up to 500. A carousel needs every image at the same aspect ratio: when they differ, the API answers 400 with mismatched_slides, the slide numbers to fix.

### Can I set the cover of a video Pin?

Yes. Set pinterest.video_cover to an image URL; without one, Pinterest shows the frame at 1 second. OmniSocials re-encodes the video to H.264 at up to 1920 x 1080, uploads it, waits until Pinterest has processed it and then creates the Pin.

### Can I tag products on a Pin?

Yes, up to 24 of your own product Pins in pinterest.product_tags. GET /v1/pinterest/products lists the ones you can tag, GET /v1/pinterest/products/validate checks one, and the MCP server has list_pinterest_products. Pinterest only takes public product Pins of the same account that link to a website the account claimed.

A product Pinterest refuses never fails the post: product_tags_result on the post lists what was tagged and why the rest was skipped.

### Can I schedule Pins through the API?

Yes. Send schedule_at and OmniSocials keeps the queue and publishes on time. When Pinterest answers with a passing error, the Pin is retried up to 3 times, 15 minutes apart. post.published or post.failed tells your webhook how it went.

### Can I read and answer Pinterest comments?

No. OmniSocials has no Pinterest inbox, so the API doesn’t list or answer Pinterest comments or messages. Comments do count in each Pin’s numbers.

### Which numbers can I read?

Per Pin: impressions, saves, pin clicks, outbound clicks, reactions and comments, with save, pin click and outbound click rates. Video Pins add video views, starts, 10 second views, completion rate and watch time. Per account: followers, monthly views, Pins and boards.

Pinterest doesn’t report reach or shares. The first numbers arrive about 12 hours after a Pin goes live, the full set within 72.

### Is the Pinterest API free?

Pinterest doesn’t charge for its API, but a new app starts on Trial access, 1,000 requests a day, until Pinterest approves Standard access. Through OmniSocials you skip that step, and the API is part of the plan, $10 per seat per month billed annually.

### What are the rate limits?

100 requests a minute per API key. Past that the API answers 429 with a Retry-After header that says when to try again.

### How much does OmniSocials cost?

One plan with every feature included: $10 per seat per month billed annually, or $12 billed monthly. Team members and client seats cost the same. Every account starts with a 14-day free trial.

The REST API, the SDKs, the CLI, webhooks and the MCP server are part of that one plan.

## Pricing

From $10 per seat a month, API included. 14-day free trial.

## Related

- [Pinterest scheduler](https://omnisocials.com/pinterest.md)
- [Pinterest MCP server](https://omnisocials.com/pinterest-mcp.md)
- [All channels](https://omnisocials.com/channels.md)
- [Pinterest character limits](https://omnisocials.com/pinterest-character-limits)
- [Pinterest video lengths](https://omnisocials.com/pinterest-video-lengths)

## Links

- Page: https://omnisocials.com/pinterest-api
- Pinterest platform docs: https://docs.omnisocials.com/platforms/pinterest
- API reference: https://docs.omnisocials.com/api
- REST API overview: https://omnisocials.com/api.md
- MCP server: https://omnisocials.com/mcp.md
- Sign up: https://app.omnisocials.com/signup