PinBridge

Advanced Topics

Scheduling

Schedule pins for future publication with reliable cancellation and edits.

Overview

Scheduling works best when you treat publish time, idempotency, and cancellation behavior as a controlled workflow instead of a one-off API call.

What You Will Learn

  • How to convert local campaign calendars into valid UTC `run_at` timestamps.
  • How to handle schedule edits safely using cancel-and-recreate patterns.
  • How schedule lifecycle states map to downstream pin publishing outcomes.

Implementation Checklist

  • Store `schedule_id`, source record ID, and idempotency key in your campaign system.
  • Convert local date/time inputs to timezone-aware UTC timestamps before submission.
  • Validate media and board/account mappings before creating schedules.
  • Treat edits as explicit workflow actions (cancel + new schedule) with audit notes.
  • Monitor `scheduled` -> `queued` -> `running` -> terminal states and alert on stuck transitions.

Deep Dive

1) Timezone and DST-safe scheduling

Most scheduling bugs come from local time assumptions. Normalize everything to timezone-aware UTC before sending to the API.

  • Store source timezone and converted UTC timestamp together for traceability.
  • Avoid naive datetime strings without offset information.
  • Recompute affected schedules around daylight saving transitions.

2) Editing schedules without duplicates

Direct in-place edits can create ambiguity in downstream systems. Prefer explicit cancel-and-recreate behavior for schedule changes.

  • Cancel old schedule if still pending, then create a replacement.
  • Reuse business-level identifiers while generating a fresh idempotency key per new action.
  • Log reason codes for schedule changes (time shift, content change, target board change).

3) State-aware operations near publish time

Late edits and cancellations can race with queue execution. Build state-aware UX and automation logic.

  • Allow cancellation only while schedule is still cancelable.
  • Handle `running`/`done` as immutable execution states.
  • Escalate `failed` schedules with remediation paths and optional retry workflows.

Relevant Endpoints

POST
/v1/schedules

Create a future publish operation.

GET
/v1/schedules

List scheduled publishes for the workspace.

GET
/v1/schedules/{schedule_id}

Fetch one scheduled publish resource.

POST
/v1/schedules/{schedule_id}/cancel

Cancel pending schedules before execution.

Example

curl -X POST "$API_BASE_URL/v1/schedules" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "<ACCOUNT_ID>",
    "board_id": "<BOARD_ID>",
    "title": "Spring campaign - morning slot",
    "description": "Scheduled publish from campaign calendar",
    "image_url": "https://example.com/campaign-image.jpg",
    "run_at": "2026-03-22T08:30:00Z",
    "idempotency_key": "spring-campaign-slot-20260322-0830"
  }'

Related Guides

Schedules APIJob Status