# Create a Pin with the API
URL: https://skedcast.com/developers/guides/publish-to-pinterest-api

To create a Pin, send boardId. A Pin publishes onto a board, so boardId is the one required field: a post without it is refused with 422 validation_failed (a draft is saved with a warning). The Pin title is the first line of content (the rest is the description) unless you send title. link sets the destination.

## What do you need before you publish?
You need one connected account for the platform. Connect it in the SkedCast console. If a client owns the account, create a connect link with `POST /v1/clients/{id}/connect-invites` and send it to them. They authorize from that page without a SkedCast login.
`GET /v1/accounts` lists the connected accounts with their ids. Pass that id in `targets.accountIds` below.

## How do you schedule a Pinterest post with the API?
```bash
curl -X POST https://api.skedcast.com/v1/posts \
  -H "Authorization: Bearer sked_live_YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "<clientId>",
    "content": "Launch day is here 🚀",
    "mediaIds": ["<mediaAssetId>"],
    "targets": { "mode": "selection", "accountIds": ["<pinterestAccountId>"] },
    "schedule": { "type": "at", "scheduledAt": "2030-01-15T15:00:00Z" }
  }'
```

## Which Pinterest fields can you set?
Put everything platform-specific in one `variants` entry with `"platform": "pinterest"` and an `overrides` object. Send only `pinterest` keys on a `pinterest` variant. SkedCast reads the keys in the table below and ignores the rest.

## Reference
Field | Type | Values / default | Notes
`boardId` | string — Required | The board's numeric id (digits only) | A Pin publishes onto a board. For a post to exactly one Pinterest account, the board's exact name also works and is turned into the id. Any other board value is refused at compose with `422 pinterest_board_unresolved`.
`boardSectionId` | string | — | Optional: files the Pin under one section of that board.
`accountOverrides` | object | — | Per-account values, keyed by account id. A board belongs to one Pinterest account, so a post to several Pinterest accounts gives each its own `boardId` here.
`title` | string (≤100) | — | Optional. When absent, the first line of the caption is the title and the rest is the description. A first line over 100 characters is refused.
`link` | string (url) | — | Destination URL.

## Unknown keys are ignored without an error
A misspelled or unknown key in `overrides` is not an error and not a warning. It is dropped, so check the field names in the table above, especially a required one.
A YouTube-only key (such as `privacyStatus`, `captions` or `chapters`) sent on another platform's variant is ignored and returns an `override_key_wrong_platform` warning.

## How do you add Pinterest-specific settings?
```json
{
  "clientId": "<clientId>",
  "content": "Autumn lookbook, five ways to style it.",
  "mediaIds": ["<imageAssetId>"],
  "targets": { "mode": "selection", "accountIds": ["<pinterestAccountId>"] },
  "variants": [
    { "platform": "pinterest", "overrides": { "boardId": "<boardId>", "title": "Autumn Lookbook", "link": "https://example.com/lookbook" } }
  ],
  "schedule": { "type": "at", "scheduledAt": "2030-01-15T15:00:00Z" }
}
```

## How do you check that the post published?
Publishing creates one post target per account. `GET /v1/post-targets/{id}` (or `GET /v1/posts/{id}`) reports `status`, plus `externalId` (Pinterest's own post id) and `permalink` (its public URL) once published. To avoid polling, subscribe to the `target.published` and `target.failed` webhooks (see the webhooks guide).

## FAQ
**Q: How do I find a board's id?**
A: Call GET /v1/accounts/{id}/boards (or the MCP tool list_pinterest_boards). It returns each board the account can pin to as { id, name }. POST /v1/accounts/{id}/boards creates a new one. In the SkedCast console the composer shows each Pinterest account's boards by name, with a New board button.

**Q: Can I send the board's name instead of its id?**
A: Only on a post to exactly one Pinterest account: send the board's exact name (case does not matter) as boardId and SkedCast looks up its id. Otherwise send the numeric id. A name that no board has, that several boards share, or that is used on a post to two or more Pinterest accounts is refused with 422 pinterest_board_unresolved.

**Q: Can I see which Pins perform best, including ones made outside SkedCast?**
A: Yes. GET /v1/analytics/accounts/{id}/top-pins (or the MCP tool get_pinterest_top_pins) returns the account's best Pins as Pinterest ranks them over the last 7, 30 or 90 days, by impressions, saves, Pin clicks, outbound clicks or engagements. It reads from Pinterest, so Pins made in Pinterest itself are included. A Pin SkedCast published carries its postId.

**Q: Can I publish a multi-image Pinterest carousel?**
A: Yes. Send 2–5 ids in the base mediaIds array (no extra override needed) and SkedCast publishes a carousel of that many images.