---
title: "Create Schedule"
method: POST
path: "/v1/schedules"
tags: ["Schedules"]
---

# Create Schedule

`POST /v1/schedules`

## Request

- Base URL: `https://api.pinbridge.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pinbridge.io/v1/schedules`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Schedule a pin for future publishing.

The pin will be published at the specified run_at time. The target board is
preflighted at scheduling time so a board the account cannot publish to is
rejected now rather than when the schedule fires.

## Headers

- `x-api-key` string, nullable
- `authorization` string, nullable

## Request body

- ScheduleCreate: Request schema for creating a scheduled pin.
  - `account_id` string, uuid, required: Pinterest account ID to publish with
  - `run_at` string, date-time, required: When to publish this pin (ISO 8601 timestamp)
  - `board_id` string, required: Pinterest board ID
  - `title` string, required: Pin title
  - `description` string, nullable: Pin description
  - `cover_image_url` string, uri, nullable: Optional public cover image URL for scheduled video pins
  - `cover_image_asset_id` string, uuid, nullable: Optional uploaded image asset ID used as a video cover image
  - `link_url` string, uri, nullable: Destination URL for the pin
  - `image_url` string, uri, nullable: Public URL of the image to pin
  - `asset_id` string, uuid, nullable: Uploaded PinBridge asset ID to use for the scheduled image or video

## Response `201`

Successful Response

- ScheduleResponse: Response schema for a schedule.
  - `id` string, uuid, required
  - `workspace_id` string, uuid, required
  - `pinterest_account_id` string, uuid, required
  - `run_at` string, date-time, required
  - `status` 'scheduled' | 'queued' | 'deferred' | 'running' | 'done' | 'failed' | 'canceled', required: Schedule status enum.
  - `payload` object, required
  - `last_error` string, nullable
  - `pin_id` string, uuid, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `warnings` ScheduleWarning[]: Set when creating or rescheduling: quota_may_be_exceeded means the schedule's month already has as many pins published or scheduled as the plan includes, so this pin may not publish.
    - `code` string, required: Stable warning code, e.g. quota_may_be_exceeded
    - `message` string, required
    - `remediation` string, nullable
    - `limit_type` string, nullable
    - `plan` string, nullable
    - `plan_name` string, nullable
    - `limit` integer, nullable
    - `used` integer, nullable: Pins already published or scheduled in the schedule's month
    - `recommended_plan` string, nullable
    - `recommended_plan_name` string, nullable
    - `recommended_limit` integer, nullable
    - `upgrade_url` string, nullable

## Other responses

- `403`: `plan_limit` once pending schedules reach twice the monthly pin quota (see `error.upgrade_url`).
- `422`: Board access preflight failed (see `error.code`).

---

[API](https://skmtc.dev/pinbridge/apis/pinbridge-api.md) · [All operations](https://skmtc.dev/pinbridge/apis/pinbridge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pinbridge/apis/pinbridge-api/revisions/b17603589d01?raw)