Pins API

Create, list, retrieve and cancel pins.

Create a pin

POST /v1/pins

Field	Type	Required	Notes
`account_id`	string	yes	A connected Pinterest account
`board_id`	string	yes	A board of that account
`image_url`	string	yes	Public https URL; Pinterest downloads it
`title`	string	no	100 characters max
`description`	string	no	800 characters max
`alt_text`	string	no	500 characters max, accessibility text
`link`	string	no	Destination link of the pin
`publish_at`	string	no	ISO 8601 date; if in the future, the pin is scheduled

Without publish_at the pin is queued right away, subject to the account pacing. With a future publish_at it is scheduled and goes out at that time.

A past publish_at is treated as an immediate publication.

List pins

GET /v1/pins

Parameter	Type	Default	Notes
`status`	string	—	`queued`, `scheduled`, `publishing`, `published`, `failed`, `cancelled`
`limit`	number	50	1 to 100

curl "https://pincast.io/v1/pins?status=failed&limit=20" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Pins come back newest first, wrapped in { "data": [...] }.

Retrieve a pin

GET /v1/pins/{id}

Answers 404 with not_found when the pin does not exist or belongs to another organization — the API never reveals which of the two it is.

Cancel a pin

DELETE /v1/pins/{id}

Only a queued or scheduled pin can be cancelled. Once publishing has started, the API answers 400 with invalid_request.

Statuses

Status	Meaning
`queued`	Waiting for its pacing slot
`scheduled`	Waiting for its `publish_at`
`publishing`	Being sent to Pinterest
`published`	Accepted; `pinterest_pin_id` is filled
`failed`	Gave up after retries; `error` explains why
`cancelled`	Cancelled before publication

A failed pin can be retried from the dashboard. attempts counts how many times Pincast has tried.

Quota

The monthly quota counts published pins. A pin that fails or is cancelled consumes nothing. Once the quota is reached, creation answers 402 with quota_exceeded.