Quickstart
Publish your first pin through the Pincast API in five minutes.
Pincast publishes to Pinterest for you. You submit a pin, and the queue, the pacing, the retries and the webhooks are handled on our side.
1. Connect a Pinterest account
In the dashboard, open Pinterest accounts and click Connect an account. You will go through the Pinterest consent screen; Pincast stores the tokens encrypted and refreshes them before they expire.
2. Create an API key
Open Settings → API Keys and create a key. It starts with pk_live_ and is
shown once — copy it immediately.
Every request authenticates with it:
Authorization: Bearer pk_live_...3. Find the account and board ids
curl https://pincast.io/v1/accounts \
-H "Authorization: Bearer pk_live_YOUR_KEY"{ "data": [{ "id": "jh7bhse...", "username": "shopibest", "status": "active" }] }Then list that account's boards:
curl https://pincast.io/v1/accounts/ACCOUNT_ID/boards \
-H "Authorization: Bearer pk_live_YOUR_KEY"4. Publish a pin
POST /v1/pinsaccount_id, board_id and image_url are required. The image URL must be
public and served over https: Pinterest downloads it from there.
The response comes back immediately with "status": "queued" — the pin has not
been sent to Pinterest yet.
5. Follow the status
Poll the pin:
curl https://pincast.io/v1/pins/PIN_ID \
-H "Authorization: Bearer pk_live_YOUR_KEY"status moves through queued → publishing → published, and
pinterest_pin_id is filled once Pinterest accepts it.
Rather than polling, configure a webhook and let Pincast tell you.
Why a pin stays queued
Pinterest rate-limits pin creation per account. Pincast spaces publications out — five minutes between two pins on the same account by default — so your account stays within the limits.
A pin can therefore sit in queued for a few minutes. Do not resubmit it:
it will go out on its own.
Errors
Every error uses the same shape:
{ "error": { "code": "quota_exceeded", "message": "Monthly quota reached (50 pins). Upgrade your plan." } }