Posts

Publish to a Pinterest board through POST /v1/posts.

Cross-platform flow: Media guide. Board helpers: Overview — Boards API.

Supported formats

`mediaKind`	Supported	Notes
`image`	Yes	One image URL
`multi-image`	Yes	2–5 image URLs
`video`	Yes	One video URL. Not available in Sandbox
`text` / `stories`	No	`UNSUPPORTED_MEDIA_KIND`

Features

Feature	Supported	Notes
Thread / quote	No
Schedule	Yes	`scheduledFor` + `timezone`
Board	Yes	Optional `destinations[].boardId` (see resolution below)
Title	Yes	Post `text` → pin title (max 100)
Description	Yes	`destinations[].description` (max 800)
Link	Yes	`destinations[].link`
Remote delete	Yes	`DELETE …/destinations/:id`

Board resolution

Pinterest requires a board for every pin. When creating a post you may:

Pass destinations[].boardId explicitly, or
Omit it and let Onepostly resolve one at publish time:

Priority	Source
1	`destinations[].boardId`
2	Connection default board
3	First board on the account
4	Auto-create a board named `board`, then pin to it

After step 3 or 4, Onepostly remembers the default board on the connection so later posts without boardId reuse it.

List / create boards yourself anytime:

GET /v1/connections/:id/pinterest/boards
POST /v1/connections/:id/pinterest/boards { "name": "…" }

{
  "connectionId": "YOUR_PINTEREST_CONNECTION_ID",
  "boardId": "1234567890123456789",
  "description": "Optional longer pin description",
  "link": "https://example.com/landing"
}

boardId / link are Pinterest-only.

Create (image)

Minimal — no boardId (auto-resolve / auto-create board):

curl -X POST https://api.onepostly.com/v1/posts \
  -H "x-api-key: op_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Product pin title",
    "mediaKind": "image",
    "mediaUrls": ["https://cdn.example.com/photo.jpg"],
    "destinations": [
      { "connectionId": "YOUR_PINTEREST_CONNECTION_ID" }
    ]
  }'

With an explicit board:

curl -X POST https://api.onepostly.com/v1/posts \
  -H "x-api-key: op_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Product pin title",
    "mediaKind": "image",
    "mediaUrls": ["https://cdn.example.com/photo.jpg"],
    "destinations": [
      {
        "connectionId": "YOUR_PINTEREST_CONNECTION_ID",
        "boardId": "YOUR_BOARD_ID",
        "description": "Pin description with keywords.",
        "link": "https://example.com/product"
      }
    ]
  }'

Response: 202 with status: "queued". When published, externalPostId is the pin id and externalUrl is https://www.pinterest.com/pin/{id}/.

Multi-image

{
  "text": "Carousel title",
  "mediaKind": "multi-image",
  "mediaUrls": [
    "https://cdn.example.com/1.jpg",
    "https://cdn.example.com/2.jpg"
  ],
  "destinations": [
    { "connectionId": "YOUR_PINTEREST_CONNECTION_ID" }
  ]
}

Video

{
  "text": "Video pin title",
  "mediaKind": "video",
  "mediaUrls": ["https://cdn.example.com/clip.mp4"],
  "destinations": [
    { "connectionId": "YOUR_PINTEREST_CONNECTION_ID", "boardId": "YOUR_BOARD_ID" }
  ]
}

Remote delete

curl -X DELETE "https://api.onepostly.com/v1/posts/POST_ID/destinations/DEST_ID" \
  -H "x-api-key: op_YOUR_KEY"