Skip to content
PinBridge
Start free
Home / Docs / Docs

Schedules API

GET /v1/schedules

List Schedules

List schedules for the workspace, latest run_at first by default, with optional filters.

The X-Total-Count response header carries the number of schedules matching
the filters and search, so clients can page with limit and offset.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
limit query no integer
offset query no integer
q query no string? Case-insensitive search across the pin title, description and link URL
sort query no enum(run_at_desc, run_at_asc, created_at_desc, created_at_asc, title_asc, title_desc, status_asc, status_desc) Sort order; run_at_asc lists the next run first
account_id query no string? Only schedules for this Pinterest account
board_id query no string? Only schedules targeting this board
status query no ScheduleStatus? Only schedules in this status
since query no string? Only schedules running at or after this ISO 8601 timestamp
until query no string? Only schedules running before this ISO 8601 timestamp

Response 200

curl -X GET "https://api.pinbridge.io/v1/schedules" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

POST /v1/schedules

Create Schedule

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.

Auth: ApiKeyAuth, BearerAuth

Request body (ScheduleCreate)

Field Type Required Description
account_id string yes Pinterest account ID to publish with
run_at string yes When to publish this pin (ISO 8601 timestamp)
board_id string yes Pinterest board ID
title string yes Pin title (max 100)
description string? no Pin description
alt_text string? no Alternative text used for accessibility
cover_image_url string? no Optional public cover image URL for scheduled video pins
cover_image_asset_id string? no Optional uploaded image asset ID used as a video cover image
link_url string? no Destination URL for the pin
image_url string? no Public URL of the image to pin
asset_id string? no Uploaded PinBridge asset ID to use for the scheduled image or video

Response 201 (ScheduleResponse)

curl -X POST "https://api.pinbridge.io/v1/schedules" \
  -H "X-API-Key: $PINBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "run_at": "2026-12-01T09:00:00Z", "board_id": "987654321098765432", "title": "Autumn table setting", "image_url": "https://example.com/image.jpg"}'

POST /v1/schedules/bulk-cancel

Bulk Cancel Schedules

Cancel multiple schedules in one call.

Per-item outcomes:
* succeeded — schedule was canceled.
* skipped (error_code=ineligible_status) — schedule status is not
SCHEDULED/QUEUED/DEFERRED.
* failed (error_code=not_found) — schedule not found in workspace.

Auth: ApiKeyAuth, BearerAuth

Request body (BulkIdsRequest)

Field Type Required Description
ids array yes List of resource IDs to act on (up to 500 per request).

Response 200 (BulkOperationResponse)

curl -X POST "https://api.pinbridge.io/v1/schedules/bulk-cancel" \
  -H "X-API-Key: $PINBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]}'

POST /v1/schedules/bulk-delete

Bulk Delete Schedules

Delete multiple terminal-state schedules in one call.

Per-item outcomes:
* succeeded — schedule was deleted.
* skipped (error_code=ineligible_status) — schedule status is not done,
failed, or canceled.
* failed (error_code=not_found) — schedule not found in workspace.

Auth: ApiKeyAuth, BearerAuth

Request body (BulkIdsRequest)

Field Type Required Description
ids array yes List of resource IDs to act on (up to 500 per request).

Response 200 (BulkOperationResponse)

curl -X POST "https://api.pinbridge.io/v1/schedules/bulk-delete" \
  -H "X-API-Key: $PINBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]}'

POST /v1/schedules/bulk-retry

Bulk Retry Schedules

Retry multiple failed schedules in one call.

Per-item outcomes:
* succeeded — schedule was reset to a runnable state.
* skipped (error_code=ineligible_status) — schedule status is not FAILED.
* failed (error_code=not_found) — schedule not found in workspace.

Auth: ApiKeyAuth, BearerAuth

Request body (BulkIdsRequest)

Field Type Required Description
ids array yes List of resource IDs to act on (up to 500 per request).

Response 200 (BulkOperationResponse)

curl -X POST "https://api.pinbridge.io/v1/schedules/bulk-retry" \
  -H "X-API-Key: $PINBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]}'

POST /v1/schedules/validate

Validate Schedule

Dry-run a schedule request.

Same checks as POST /v1/pins/validate plus run_at. Nothing is stored.

Auth: ApiKeyAuth, BearerAuth

Request body (ScheduleCreate)

Field Type Required Description
account_id string yes Pinterest account ID to publish with
run_at string yes When to publish this pin (ISO 8601 timestamp)
board_id string yes Pinterest board ID
title string yes Pin title (max 100)
description string? no Pin description
alt_text string? no Alternative text used for accessibility
cover_image_url string? no Optional public cover image URL for scheduled video pins
cover_image_asset_id string? no Optional uploaded image asset ID used as a video cover image
link_url string? no Destination URL for the pin
image_url string? no Public URL of the image to pin
asset_id string? no Uploaded PinBridge asset ID to use for the scheduled image or video

Response 200 (PinValidationResponse)

curl -X POST "https://api.pinbridge.io/v1/schedules/validate" \
  -H "X-API-Key: $PINBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "run_at": "2026-12-01T09:00:00Z", "board_id": "987654321098765432", "title": "Autumn table setting", "image_url": "https://example.com/image.jpg"}'

DELETE /v1/schedules/{schedule_id}

Delete Schedule

Delete a schedule once it is in a terminal state (done, failed, or canceled).

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
schedule_id path yes string

Response 204

curl -X DELETE "https://api.pinbridge.io/v1/schedules/$SCHEDULE_ID" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

GET /v1/schedules/{schedule_id}

Get Schedule

Get schedule details.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
schedule_id path yes string

Response 200 (ScheduleResponse)

curl -X GET "https://api.pinbridge.io/v1/schedules/$SCHEDULE_ID" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

PATCH /v1/schedules/{schedule_id}

Update Schedule

Edit a pending schedule in place.

Change the publish time, board, title, description, alt text, link or media
of a schedule that has not started publishing, keeping its id and history. The
same checks as creating a schedule apply to the changed fields: run_at
must be in the future, a new board is preflighted, and new media is
resolved. Schedules that already started return 409; cancel and recreate,
or edit the resulting pin instead.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
schedule_id path yes string

Request body (ScheduleUpdate)

Field Type Required Description
run_at string? no New publish time (ISO 8601, with tz)
board_id string? no Move the schedule to another board
title string? no Pin title
description string? no Pin description
alt_text string? no Alternative text used for accessibility
link_url string? no Destination URL for the pin
image_url string? no Replace the media with a public URL
asset_id string? no Replace the media with an uploaded asset
cover_image_url string? no Video cover image URL
cover_image_asset_id string? no Video cover image asset ID

Response 200 (ScheduleResponse)

curl -X PATCH "https://api.pinbridge.io/v1/schedules/$SCHEDULE_ID" \
  -H "X-API-Key: $PINBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"run_at": "2026-12-01T09:00:00Z", "alt_text": "A dinner table set with candles and autumn leaves"}'

POST /v1/schedules/{schedule_id}/cancel

Cancel Schedule

Cancel a scheduled pin.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
schedule_id path yes string

Response 200 (ScheduleResponse)

curl -X POST "https://api.pinbridge.io/v1/schedules/$SCHEDULE_ID/cancel" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

POST /v1/schedules/{schedule_id}/retry

Retry Schedule

Retry a previously failed schedule.

Resets the schedule (and any linked, non-deleted pin) to a runnable state.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
schedule_id path yes string

Response 200 (ScheduleResponse)

curl -X POST "https://api.pinbridge.io/v1/schedules/$SCHEDULE_ID/retry" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"
Last updated October 29, 2026 Was this page helpful? Tell us →

Powered by
►
Necessary cookies enable essential site features like secure log-ins and consent preference adjustments. They do not store personal data.
None
►
Functional cookies support features like content sharing on social media, collecting feedback, and enabling third-party tools.
None
►
Analytical cookies track visitor interactions, providing insights on metrics like visitor count, bounce rate, and traffic sources.
None
►
Advertisement cookies deliver personalized ads based on your previous visits and analyze the effectiveness of ad campaigns.
None
Powered by