cancel_schedule
ChatGPTCancel a pending scheduled pin so it never publishes. Use when the pin should not go out at all. To remove a finished schedule from the list use delete_schedule; to re-arm a failed one use retry_schedule. Returns the schedule with status "canceled". Fails with not_found for an unknown id and bad_request when the schedule already ran (done, failed) or was canceled.
check_board_access
ChatGPTCheck whether an account can publish to a board right now, and why not. Use before publishing to a board not used recently, or after a publish failed with any board_* code, instead of retrying blind. For a full preflight of a specific pin use create_pin with dry_run=true. Returns publishable (bool), status (ok | failed | skipped when Pinterest was unreachable), code (board_not_found, board_not_owned, board_deleted, board_access_denied, scope_missing, token_expired), message, remediation, board, account_health, source (cache | pinterest). Never raises for a bad board; an unknown account fails with not_found.
create_board
ChatGPTCreate a new board on a connected Pinterest account. Use when no existing board from list_boards fits; check list_boards first, since Pinterest rejects duplicate names. Not needed for a one-off pin: publish to an existing board. Returns the board with id (use as board_id), name, description, privacy. Fails with forbidden (sandbox_board_limit) when a sandbox project hits its board cap, and token_expired / scope_missing when the Pinterest connection needs a reconnect (scope_missing with missing_scopes ["boards:write_secret"] for SECRET on an account connected before secret boards were supported).
create_pin
ChatGPTPublish a pin to Pinterest now, or preflight it with dry_run=true. Use for a pin that should go out immediately; for a future time use create_schedule, for many pins use create_pins_batch. Provide either image_url or asset_id (from upload_asset), not both. Run dry_run first and reuse resolved.idempotency_key on the real call. Returns the pin with id and status "queued" (poll get_pin), or with dry_run the validation result (valid, checks, resolved, headroom). Fails fast with board_not_found / board_not_owned / board_access_denied for an unpublishable board, quota_exceeded when the monthly quota is spent, and validation_error for bad fields.
create_pins_batch
ChatGPTPublish several pins in one call with a per-entry outcome. Use for bulk publishing (up to 100 pins) when the workspace has the bulk_imports feature; otherwise call create_pin per pin. Check get_billing_status for quota first: the batch needs quota for every entry. Supply an idempotency_key per entry if you may resend. Returns created_count, existing_count, failed_count, results (one {index, idempotency_key, status, pin, error} per entry) and headroom. Fails as a whole with payment_required without bulk_imports and quota_exceeded when quota is short; per-entry board or validation failures land in results instead.
create_schedule
ChatGPTSchedule a pin to publish at a future time. Use when the pin should go out later or when spreading many pins out after rate_limited; for an immediate publish use create_pin. Provide either image_url or asset_id, not both. The board is preflighted now, not at run time. A repeat call creates a second schedule, so check list_schedules before resending after a timeout. Returns the schedule with id and status "scheduled" (track it with get_schedule), or with dry_run the validation result. Fails with validation_error for a past or timezone-less run_at, board_* codes for an unpublishable board, and quota_exceeded when quota is spent.
create_webhook
ChatGPTRegister an endpoint PinBridge calls when a pin publishes or fails. Use instead of polling get_pin when the caller can receive HTTP callbacks. Check list_webhooks first to avoid registering the same URL twice; use update_webhook to change events or pause an existing one. Default events are pin.published and pin.failed. Returns id, url, events, is_enabled, created_at. Fails with validation_error when the URL is not a valid http(s) URL or the secret is shorter than 16 characters.
delete_asset
ChatGPTDelete an uploaded image or video from PinBridge storage. Irreversible; confirm first. Use to clean up media from upload_asset that is no longer needed; its public_url stops working. Published pins keep their image on Pinterest. With confirm=true, a pin or scheduled pin that has not published yet and uses the asset fails to publish, so tell the user which ones first. Returns asset_id, deleted, requires_confirmation, referenced_pin_count (pins plus scheduled pins that have not run yet) and freed_bytes. With confirm=false and the asset still in use, nothing is deleted: deleted is false and requires_confirmation true. Fails with not_found for an unknown id and insufficient_scope without the destructive scope.
delete_board
ChatGPTDelete a board on Pinterest together with every pin on it. Irreversible; confirm first. Use only when the whole board should go; to remove one pin use delete_pin. PinBridge keeps its records of the board's published pins and flags them removed_from_pinterest_at. Returns {"deleted": true, "board_id": "<id>"}. Fails with board_not_found for an unknown board, forbidden when sandbox board writes are blocked, insufficient_scope without the destructive scope, and token_expired / scope_missing when the Pinterest connection needs a reconnect.
delete_pin
ChatGPTDelete one pin, from Pinterest too by default. Irreversible; confirm first. Use for a pin that should not exist, or to replace a published pin that needs a correction (published pins cannot be edited). Before a pin publishes, fix it with update_pin instead. Never use delete_board to remove one pin. Returns id, deleted, removed_from_pinterest, pinterest_pin_id and reason when nothing was removed upstream (not_published, simulated_sandbox, record_only, api_version_too_old). Fails with not_found for an unknown id and insufficient_scope without the destructive scope.
delete_schedule
ChatGPTDelete a finished schedule record (status done, failed or canceled). Irreversible. Use to clean up history. A pending schedule cannot be deleted: use cancel_schedule first. Deleting does not touch the pin a done schedule already published. Returns {"deleted": true, "schedule_id": "<id>"}. Fails with not_found for an unknown id, bad_request while the schedule is still pending, and insufficient_scope without the destructive scope.
delete_webhook
ChatGPTDelete a webhook endpoint; deliveries stop immediately. Irreversible. Use when the endpoint is retired. To pause temporarily use update_webhook with is_enabled=false instead. Returns {"deleted": true, "webhook_id": "<id>"}. Fails with not_found for an unknown id and insufficient_scope without the destructive scope.
get_account_analytics
ChatGPTPinterest performance metrics for a whole connected account over a date range. Use for account-level reporting (all pins, not only ones published through PinBridge). For one pin use get_pin_analytics; for publish headroom use get_rate_meter. Returns account_id, start_date, end_date, provider_mode, totals, daily rows (empty with include_daily=false; pass that when the totals are enough), and source (stored or live) with data_as_of for stored reads. Fails with not_found for an unknown account and with token_expired / scope_missing when the Pinterest connection needs a reconnect.
get_billing_status
ChatGPTReturn the workspace's plan, monthly publish quota, usage and feature flags. Use before a large create_pins_batch or after quota_exceeded to see how many publishes remain, and to check plan features before upload_asset (uploaded_media_assets) or create_pins_batch (bulk_imports). For Pinterest's per-account publish rate use get_rate_meter; for pin performance use get_account_analytics. Returns plan, billing_status, quota_calls_monthly, calls_used, quota_reset_at, quota_exhausted, credits_remaining, storage_used_bytes / storage_quota_bytes, pinterest_accounts_limit, uploaded_media_assets, bulk_imports. Never fails for a valid key.
get_dashboard_summary
ChatGPTSummarize publishing activity over a period: how many pins went out and how it went. Use to answer "how did publishing go this week / today / last month": pin outcomes, success rate, the change against the previous period, and what is still queued or scheduled. Ranges up to 48 hours come back hourly, longer ones daily, up to 366 days. For Pinterest engagement (impressions, saves, clicks) use get_account_analytics; to see the individual failed pins use list_pins with status=failed. Returns start, end, timezone, granularity (hour | day), pins (total, submitted, by_status, success_rate from 0 to 1), previous_pins (same figures for the preceding period of equal length), series (created / published / failed per bucket), published_by_account, queue (queued, deferred, publishing right now), schedules (by_status in the range, upcoming) and import_jobs (null when filtered by account). Outcomes count by when they happened: published by publish time, failed by failure time (for pins still failed); pins.total is the sum of by_status, and pins.submitted and series.created count pins submitted in the range (API 1.38+; older APIs report submissions in pins.total and omit pins.submitted). Fails with invalid_date_range (start not before end, or more than 366 days), invalid_timezone, or account_not_permitted for an account outside the key's allow-list.
get_pin
ChatGPTFetch one pin's current status, Pinterest ID and any publish error. Use to poll a pin from create_pin until it is published, failed or deferred, or to read why it failed. To find pins without an id use list_pins; for impressions and clicks use get_pin_analytics; to fix a failure use retry_pin. Returns the pin with status, error_code and error_message when failed, pinterest_pin_id once published, and its media and board fields. removed_from_pinterest_at is set when the published pin was later deleted on Pinterest (status stays published). An unknown id fails with not_found.
get_pin_analytics
ChatGPTPinterest performance metrics for one published pin over a date range. Use after a pin has been published for a while to report impressions, saves and clicks. For the whole account use get_account_analytics; for publish status use get_pin. Returns pin_id, pinterest_pin_id, account_id, start_date, end_date, provider_mode, totals (each metric summed over the range, lowercase names), daily rows (empty with include_daily=false; pass that when the totals are enough), source (stored or live) and data_as_of for stored reads. total_comments and total_reactions are lifetime counts on live reads and 0 on stored reads, which do not keep them: use source=live for comments and reactions. They read 0 on every daily row, since Pinterest does not report them per day. A pin deleted on Pinterest is answered from stored history with removed_from_pinterest_at set, and fails with pin_removed_on_pinterest when none is stored. Fails with not_found for an unknown pin and with pin_not_published for a pin that has not published yet; sandbox pins return zeroed metrics.
get_rate_meter
ChatGPTReturn how many Pinterest publishes an account can make right now. Use before publishing many pins at once, or after rate_limited, to decide between publishing now and spreading pins out with create_schedule. This is Pinterest's publish pacing; for the PinBridge monthly quota use get_billing_status. Returns account and global token buckets, each with tokens_available, capacity and refill_rate (tokens per second). tokens_available of 0 means the next publish is deferred until the bucket refills. An unknown account fails with not_found.
get_schedule
ChatGPTFetch one scheduled pin (a pin queued to publish at a future time) by id. Use to check whether a schedule is still pending, has published, failed or was canceled. To browse schedules use list_schedules; once status is done, follow the resulting pin with get_pin using pin_id. Returns the schedule with status, run_at, pinterest_account_id, payload (board_id, title, media), pin_id and last_error. An unknown id fails with not_found.
list_activity_logs
ChatGPTRead the workspace audit trail: who did what, when, with what outcome. Use to reconstruct what happened to a pin or schedule, or to see changes made outside this session (dashboard, API, other agents). For current state use get_pin / get_schedule instead. Returns items (log entries with action, status, message, resource_type, resource_id, metadata, created_at) and next_cursor for the next page, null on the last page. Fails with validation_error for a malformed cursor or since value; unknown filter values return an empty page.
list_boards
ChatGPTList the boards an account can publish to. Use to pick a board_id for create_pin or create_schedule, or after board_not_found. Also read pinbridge://accounts/{account_id}/boards. To test one board's publishability use check_board_access. Returns id, name, description, privacy per board. Fails with not_found for an unknown account, account_not_permitted if the key cannot use it, and token_expired / token_revoked / scope_missing when the Pinterest connection needs a reconnect in the dashboard.
list_pins
ChatGPTList pins in this workspace, newest first, with search, filters and sorting. Use to find a pin's id (search its title with q), review what published or failed, or audit one board or account. For one known pin use get_pin; for scheduled (not yet published) pins use list_schedules; for totals over a period use get_dashboard_summary. Returns one page: {items, total, limit, offset, has_more}. items are pin summaries (id, title, status, board_id, pinterest_account_id, pinterest_pin_id, link_url, error_code, error_message, created_at, published_at, removed_from_pinterest_at); detail="full" returns every field, but read one pin with get_pin instead. removed=true lists published pins that were deleted on Pinterest. total counts every match across all pages, so "how many pins failed this week?" is one call with status=failed, since=... and limit=1. To read further, repeat the call with the same filters, q and sort and offset = offset + limit while has_more is true. total is null only against a PinBridge API older than 1.34. Filtering on an account outside the key's allow-list fails with account_not_permitted, and an unknown sort or status fails with validation_error.
list_pinterest_accounts
ChatGPTList the Pinterest accounts connected to this workspace with their health. Use first: list_boards, create_pin, create_schedule and get_rate_meter all need an account_id from here. Also read pinbridge://accounts. To connect a new account or fix reconnect_required, the user must use the PinBridge dashboard; there is no tool for that. Returns {"items": [...], "connect_url": "...", "next_step": ...}. items has one entry per account with id (the account_id), username, display_name, scopes (comma-separated), token_expires_at and health: health_status (healthy, refresh_due, reconnect_required or scope_missing), health_message, reconnect_required and missing_scopes. connect_url opens the dashboard's connect step. When items is empty nothing is connected: next_step says to give the user connect_url. Accounts outside this API key's allow-list are omitted. Never fails for a valid key.
list_related_terms
ChatGPTLook up the search terms Pinterest associates with your seed keywords. Use while drafting a description or choosing related_terms for create_pin; it reads Pinterest's own suggestions. Not needed for publishing itself. Returns id, related_term_count and related_terms_list (term plus its related terms). Counts against the workspace's Pinterest read limit and fails with rate_limited (with retry_after_seconds) when it is spent, or not_found for an unknown account.
list_schedules
ChatGPTList scheduled pins in this workspace, latest run_at first, with search and filters. Use to find a schedule's id (search its title with q), see what is queued for a period (status=scheduled, sort=run_at_asc), or list failed schedules to retry. For one known schedule use get_schedule; for pins that already published use list_pins. Returns one page: {items, total, limit, offset, has_more}. items are the schedules (id, pinterest_account_id, run_at, status, payload with board_id, title and media, pin_id once it ran, last_error, created_at, updated_at). total counts every match across all pages, so "how many pins are scheduled for next week?" is one call with status=scheduled, since/until and limit=1. To read further, repeat the call with the same filters, q and sort and offset = offset + limit while has_more is true. Fails with account_not_permitted for an account outside the key's allow-list and validation_error for a bad status, sort or timestamp.
list_webhooks
ChatGPTList every webhook endpoint registered in this workspace. Use before create_webhook to avoid registering the same URL twice, or to find a webhook's id for update_webhook or delete_webhook. Returns id, url, events, is_enabled, created_at per webhook; an empty list means none are registered. Secrets are never returned. Never fails for a valid key.
retry_pin
ChatGPTRe-queue a failed pin, optionally on another board or account. Use only for pins whose status is failed: pass board_id when the original board was deleted or inaccessible (check_board_access says why), or account_id when the original account needs a reconnect. Published pins cannot be edited or retried; for a failed schedule use retry_schedule. Returns the pin re-queued with status "queued"; poll get_pin. The new board is preflighted like create_pin. Fails with not_found for an unknown id and conflict when the pin is not in failed status.
retry_schedule
ChatGPTRe-queue a schedule whose publish failed. Use for schedules in failed status (list_schedules with status="failed"). To change the board or account first, use retry_pin on the linked pin_id; for a failed pin created directly, use retry_pin. Returns the schedule. Its status is usually "queued": a schedule that failed while publishing has a linked pin_id, and that pin is re-published right away. It is "scheduled" only when the schedule failed before any pin was created; the scheduler then runs it at run_at, or on its next tick when run_at has passed. Fails with not_found for an unknown id and bad_request when the schedule is not failed.
server_info
ChatGPTReport this server's version, target PinBridge API and enabled capabilities. Use when a client connects for the first time, or when a call fails unexpectedly, to confirm the server is reachable and whether write tools are on. For the workspace's plan and quota use get_billing_status. Returns server version, pinbridge_base_url, transport and whether write tools are enabled. Needs no PinBridge scope.
update_board
ChatGPTRename a board or change its description or privacy on Pinterest. Use for board housekeeping; pins on the board are untouched. To move a pin that has not published between boards use update_pin; to remove a board use delete_board. Pass at least one of name, description or privacy. Returns the updated board (id, name, description, privacy). Fails with board_not_found for an unknown board, forbidden when sandbox board writes are blocked, and token_expired / scope_missing when the Pinterest connection needs a reconnect (including SECRET on an account connected without boards:write_secret).
update_pin
ChatGPTEdit a pin that has NOT been published yet: title, description, link, alt text or board. Use to fix a typo, link or board before the pin publishes: queued, deferred and failed pins then publish with the new values. Published pins cannot be edited: Pinterest's API does not allow PinBridge to change a pin once it is live, so the call fails with pin_already_published. For a published pin, offer delete_pin plus a new create_pin (confirm first). To change the image use delete_pin then create_pin; for a failed pin on a bad board use retry_pin. Pass at least one field. Returns the updated pin. Fails with pin_already_published for a published pin, not_found for an unknown id, and conflict (pin_publishing) while the pin is mid-publish. A new board is preflighted like create_pin.
update_schedule
ChatGPTEdit a pending schedule in place: time, board, text or media. Use to fix a wrong run_at, board, title or link on a schedule that has not started publishing, instead of cancel_schedule plus create_schedule; the id and history are kept. Once the schedule has run its pin is published and can no longer be edited; for a failed one use retry_schedule. Pass at least one field. Returns the updated schedule, still in status "scheduled". A new board is preflighted like create_schedule. Fails with not_found for an unknown id, schedule_not_editable (409) once publishing started, with a remediation naming the right tool, validation_error for a past or timezone-less run_at, and sandbox_board_fixed when changing the board of a sandbox schedule.
update_webhook
ChatGPTChange a PinBridge webhook's URL, secret, events or enabled flag. Calls PATCH /v1/webhooks/{webhook_id} on the PinBridge API; the fields, event names and signed delivery format are documented at https://www.pinbridge.io/docs/api/webhooks/. Use to pause deliveries (is_enabled=false) or rotate the secret without losing the registration; to stop for good use delete_webhook. Only the fields you pass change. Pass at least one. Returns the updated webhook (id, url, events, is_enabled). Fails with not_found for an unknown id and validation_error for a short secret.
upload_asset
ChatGPTUpload an image or video to PinBridge and get an asset_id for create_pin. Use when the media was generated in this session or Pinterest cannot fetch it from a public URL; otherwise pass image_url to create_pin directly. Provide exactly one of file, content_base64 or source_url. For a file attached to or generated in the conversation use file, never a file path in content_base64. Videos must be uploaded assets. Returns id (use as asset_id), public_url, asset_type, content_type, size_bytes, created_at. Files are capped at 200 MB (plans cap lower). Fails with payment_required on plans without uploaded_media_assets (see get_billing_status), validation_error for unsupported media, and invalid_image when the file is truncated or corrupted (re-encode the exact original bytes; never retype base64 by hand).
cancel_schedule
Claudecheck_board_access
Claudecreate_board
Claudecreate_pin
Claudecreate_pins_batch
Claudecreate_schedule
Claudecreate_webhook
Claudedelete_board
Claudedelete_pin
Claudedelete_schedule
Claudedelete_webhook
Claudeget_account_analytics
Claudeget_billing_status
Claudeget_dashboard_summary
Claudeget_pin
Claudeget_pin_analytics
Claudeget_rate_meter
Claudeget_schedule
Claudelist_activity_logs
Claudelist_boards
Claudelist_pins
Claudelist_pinterest_accounts
Claudelist_related_terms
Claudelist_schedules
Claudelist_webhooks
Clauderetry_pin
Clauderetry_schedule
Claudeserver_info
Claudeupdate_board
Claudeupdate_pin
Claudeupdate_schedule
Claudeupdate_webhook
Claudeupload_asset
Claude
