MCP Tools Reference

Tools are actions that AI assistants can perform on your behalf. The Tailwind MCP Server provides tools for finding accounts, boards, and recommended posting times, for checking an account’s subscription/plan status, for creating, scheduling, listing, reading, or deleting Pinterest Pins, for generating Pin drafts from a URL with Tailwind’s AI, for uploading your own file bytes when the media has no public URL, for reading, editing, and tagging your Saved Keywords list, and for connecting RSS feeds that automatically draft SmartPins from new posts.

Tool permissions

Every tool is classified as a read, a write or a sensitive write, so an AI assistant can decide which calls need the user’s approval:

Read: returns information and changes nothing, in Tailwind or on Pinterest. These are the tools annotated readOnlyHint: true.
Write: creates, changes or deletes data in Tailwind or on Pinterest.
Sensitive write: a write that is consequential or cannot be undone. It publishes to Pinterest or pauses publishing, permanently deletes a board or a Pin, overwrites many Pins at once, rebuilds the whole schedule, spends plan credits, or sends the user’s words to Tailwind’s team. An assistant should show the details and get the user’s approval every time it calls one.

A tool that can both read and write is classified by its write. Credit costs are returned in each metered tool’s response, and get_account_usage reports the credits left. API limits are described in Rate Limits.

Tool	Classification	Effect
`list_accounts`	Read	No changes
`get_account`	Read	No changes
`connect_pinterest_account`	Read	No changes; returns a link the user opens in a browser
`list_boards`	Read	No changes
`list_board_lists`	Read	No changes
`create_board_list`	Write	Saves a board list in Tailwind; nothing changes on Pinterest
`update_board_list`	Write	Replaces a board list in Tailwind
`delete_board_list`	Write	Deletes a board list in Tailwind; its boards are untouched
`create_board`	Write	Creates a board on Pinterest
`update_board`	Write	Renames or edits a board on Pinterest
`delete_board`	Sensitive write	Deletes a Pinterest board and every Pin on it; cannot be undone
`list_board_sections`	Read	No changes
`list_board_pins`	Read	No changes
`get_board_keyword_relevance`	Sensitive write	Reads only, but spends one plan credit per scored call
`get_recommended_pins`	Read	No changes
`save_pins_to_board`	Sensitive write	Saves existing Pins to a Pinterest board straight away (a repin)
`create_board_section`	Write	Creates a board section on Pinterest
`update_board_section`	Write	Renames a board section on Pinterest
`delete_board_section`	Write	Removes a board section on Pinterest; its Pins move back to the board
`list_group_boards`	Read	No changes
`list_timeslots`	Read	No changes
`get_schedule`	Read	No changes
`open_schedule_calendar`	Read	No changes
`create_timeslot`	Write	Adds a posting time to the account’s schedule
`update_timeslot`	Write	Moves a posting time
`delete_timeslot`	Write	Removes a posting time
`rebuild_schedule`	Sensitive write	Deletes every posting time on the account and generates new ones; cannot be undone
`list_pin_spacing_rules`	Read	No changes
`get_pin_spacing_rule`	Read	No changes
`list_subscriptions`	Read	No changes
`get_account_usage`	Read	No changes
`create_post`	Sensitive write	Schedules a Pin to publish to Pinterest when given `sendAt` or `useNextOpenSlot`, and spends a Pin credit; without either it only saves a Tailwind draft
`create_posts`	Sensitive write	Creates up to 175 Pins in one call; each scheduled entry publishes to Pinterest at its time and spends a Pin credit, and drafts only save in Tailwind
`get_post_batch`	Read	No changes
`schedule_post`	Sensitive write	Puts a Pin into the publishing queue, so it publishes to Pinterest at its time; spends a Pin credit
`unschedule_post`	Write	Moves a queued Pin back to drafts and returns its Pin credit
`pause_publishing`	Sensitive write	Stops the whole account’s queue; every Pin due during the pause fails, loses its slot and stays failed after resuming
`resume_publishing`	Sensitive write	Lets every queued Pin on the account publish to Pinterest again
`update_post`	Write	Edits one unpublished Pin’s copy, media or placement; free
`preview_update_posts`	Read	No changes
`update_posts`	Sensitive write	Overwrites the copy and placement of many Pins at once; Tailwind keeps no history of the old copy
`delete_post`	Sensitive write	Permanently deletes one unpublished Pin; cannot be undone. Published Pins cannot be deleted
`list_posts`	Read	No changes
`get_post`	Read	No changes
`get_post_image`	Read	No changes
`get_account_analytics`	Read	No changes
`list_top_pins`	Read	No changes
`list_pins`	Read	No changes
`get_pin_analytics`	Read	No changes
`generate_pins_from_url`	Sensitive write	Spends plan credits (about 1 to 7 per generation)
`get_generation_status`	Read	No changes
`cancel_generation`	Write	Cancels a queued generation, which is then never charged
`get_pin_design`	Read	No changes
`update_pin_design`	Write	Edits a draft’s design text; free
`select_pin_design_variation`	Write	Switches a draft to another generated design; free
`revert_pin_design`	Write	Restores a draft’s earlier design; free
`regenerate_pin_design`	Sensitive write	Spends plan credits (about 7)
`get_design_regeneration_status`	Read	No changes
`generate_pin_copy`	Sensitive write	Spends one plan credit per call
`get_copy_generation_status`	Read	No changes
`create_media_upload`	Write	Stores media bytes in Tailwind for a later `create_post`
`list_saved_keywords`	Read	No changes
`save_keywords`	Write	Adds keywords to the Saved Keywords list
`delete_saved_keyword`	Write	Removes a saved keyword
`delete_saved_keywords`	Write	Removes several saved keywords
`tag_saved_keywords`	Write	Adds tags to saved keywords
`untag_saved_keywords`	Write	Removes tags from saved keywords
`preview_feed`	Read	No changes
`list_feeds`	Read	No changes
`connect_feed`	Sensitive write	Starts a daily automation that drafts Pins from new feed posts and spends credits for each one
`get_feed`	Read	No changes
`update_feed`	Sensitive write	Changes or pauses a connected feed; resuming a paused feed drafts, and charges for, Pins for posts published during the pause, and turning on automatic redesign spends credits on a schedule
`delete_feed`	Write	Disconnects a feed; Pins it already drafted stay
`request_capability`	Sensitive write	Sends the user’s request, in their words, to Tailwind’s team
`report_issue`	Sensitive write	Sends the user’s report, in their words, to Tailwind’s team

record_widget_event also appears in tools/list. It is a write that only records a usage count from Tailwind’s own Pin card and calendar views and changes no account data. It is marked for those views only (_meta.ui.visibility: ["app"]), so hosts that honor the marking do not offer it to the assistant.

list_accounts

List all Pinterest accounts connected to your Tailwind organization. Call this first because every account-scoped tool requires an accountId returned by this tool. The feed tools are the exception: feeds belong to the organization, so only connect_feed (which assigns a feed’s Pins to one account) needs an accountId.

This tool has no parameters.

Example Usage

“List my Pinterest accounts”

Response

Returns each account’s ID, username, display name, domain-verification status, Pinterest-token status, and time zone (the IANA zone Tailwind schedules the account in, set per organization; null when none is set).

get_account

Get one account’s details when you already have its accountId — username, display name, connection status, time zone, and claimed domain — without listing every account. Prefer list_accounts when you don’t have an accountId yet.

A 404 means the account is not yours, or is one of your own accounts that is no longer connected to Tailwind; the message says which.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts

Example Usage

“What’s the connection status of account 123456?”

Response

Returns the account’s ID, username, display name, avatar, domain-verification status, claimed domain (absent when none is set), Pinterest-token status, and connection date.

connect_pinterest_account

Get a link that connects another Pinterest account to your Tailwind organization, or re-authorizes an existing account whose Pinterest token has expired (tokenStatus: "unauthorized" in list_accounts). The call itself changes nothing: you open the link in a browser and finish connecting through Pinterest there, and any billing change is shown in that browser flow.

Before opening the link, sign in on pinterest.com to the Pinterest account you want to connect, because Pinterest connects whichever account is signed in. The browser must also be signed in to the same Tailwind organization; a link opened in another organization is refused.

For a new account, Tailwind first checks that you are an organization admin and that your plan has room for another account. When it doesn’t, no link is returned and the response says why.

Parameters

Parameter	Type	Required	Description
`accountId`	string	No	Numeric Tailwind account ID from list_accounts to re-authorize. Omit to add a new Pinterest account.

Example Usage

“Connect my second Pinterest account to Tailwind”

“My Pinterest account shows as expired, can you help me reconnect it?”

Response

Returns whether the link adds or reconnects an account, the link itself (null when a new account can’t be added), the number of Pinterest accounts the plan allows (null when there is no cap), and, when a new account can’t be added, the reason (not_admin or account_limit) with an explanation.

list_boards

List the Pinterest boards on an account, with each board’s numeric ID, name, description, follower count, Pin count and when its Pins last changed. Use this to find a boardId for create_post or schedule_post — board IDs are numeric, never board names or URLs. A board with no description comes back without a description field at all, so auditing which boards are missing one means looking for where it is absent.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts

Example Usage

“Which boards do I have on account 123456?”

Response

Returns each board’s ID, name, Pin count, and whether it is secret or a collaborator board. The Pin count comes from a cached snapshot and can lag behind Pinterest — treat it as a lower bound, not an exact figure.

pinsModifiedAt is the time Pinterest last recorded a change to the board’s Pins (ISO 8601). Read it as a last-activity date for finding boards that have gone quiet, not as the date of the newest Pin: Pinterest does not say which changes move it. It is absent when unavailable.

list_board_lists

List the account’s board lists — Tailwind’s named groupings of boards, used to publish one Pin to several boards in order. Each list gives its boards in publishing order. A board on the account that appears in no list is not covered by any grouping; a list entry whose board id is absent from list_boards points at a board that no longer exists on the account.

To publish to a list, read its boards here and pass them as create_post’s intervalBoards, keeping this order. The list ID is not itself a publishing target: a list is a saved grouping that can change, so what gets published to is the boards it holds at the time of the call.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts

Example Usage

“How are the boards on account 123456 organized?”

Response

Returns each board list’s ID, name (absent when the list is unnamed), and its boards in publishing order. An account with no board lists is a valid setup, not an error.

create_board_list

Save a new board list: a named, ordered grouping of the account’s boards, used to publish one Pin across them with create_post’s intervalBoards. A board list is Tailwind’s own grouping, so saving one changes nothing on Pinterest, and it does not consume Pin credits.

The order of boards is the publishing order. Calling twice saves two lists, so if a call’s outcome is unclear, check list_board_lists before retrying.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`name`	string	Yes	Board list name, up to 255 characters
`boards`	array	Yes	1 to 100 entries of `{ boardId, boardSectionId? }`, in publishing order. Each board may appear once. Interval Pinning takes at most 20 boards per Pin, so a longer list cannot be passed whole as `intervalBoards`

Example Usage

“Make a board list called Earrings with my Fall Earrings, Everyday Earrings and Gifts boards, in that order”

Response

Returns the new list’s ID, name and boards, plus the boards as a ready intervalBoards value.

update_board_list

Replace a board list’s name and boards with exactly what is sent. Send the whole list every time, in publishing order: a board left out is removed from the list. To rename only, resend the list’s current boards unchanged; to reorder, send the same boards in the new order. Removing a board from a list never changes the board or its Pins on Pinterest, and retrying with the same arguments is safe.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardListId`	number	Yes	Board list ID returned by list_board_lists
`name`	string	Yes	The list’s name after the update, up to 255 characters
`boards`	array	Yes	The list’s full contents after the update, as for `create_board_list`

Example Usage

“Move Gifts to the front of my Earrings board list”

Response

Returns the updated list’s ID, name and boards, plus the boards as a ready intervalBoards value.

delete_board_list

Delete a saved board list. Only Tailwind’s grouping is removed: the boards in it and every Pin on them stay exactly as they are on Pinterest.

The tool refuses the call unless confirm is true, which an agent sets only after the user has agreed in the conversation.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardListId`	number	Yes	Board list ID returned by list_board_lists
`confirm`	boolean	Yes	`true` only after the user has confirmed the deletion

Example Usage

“Delete my old Holiday 2024 board list”

Response

Returns the deleted list’s ID and name.

create_board

Create a Pinterest board on the account and get back its numeric boardId, ready to pass to create_post or schedule_post. Creating a board does not consume Pin credits.

Use the boardId returned here rather than re-listing to find the board: list_boards is served from a cache, so a just-created board may not appear in it yet.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`name`	string	Yes	Board name, up to 180 characters
`description`	string	No	Board description, up to 500 characters
`privacy`	string	No	`public` (default) or `secret`. A secret board is visible only to the account owner and its collaborators

Example Usage

“Create a board called Weeknight dinners on account 123456”

Response

Returns the new board’s ID, name, description, privacy and pin count.

update_board

Rename a Pinterest board or change its description. Supply at least one of name or description; anything omitted is left as it is.

A board’s privacy cannot be changed through this tool — flipping a public board to secret would hide every Pin on it from everyone but the owner.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardId`	string	Yes	Numeric Pinterest board ID returned by list_boards — never a board name or URL
`name`	string	No	New board name, up to 180 characters
`description`	string	No	New board description, up to 500 characters

Example Usage

“Rename board 1106196864631757445 to Quick weeknight meals”

Response

Returns the updated board’s ID, name, description, privacy and pin count.

delete_board

Permanently delete a Pinterest board and every Pin saved to it. This cannot be undone — the Pins are destroyed on Pinterest, not moved or archived, and Tailwind cannot restore them.

Confirm with the user before calling, then pass confirm: true; the server refuses the call and deletes nothing without it. The board’s Pin count from list_boards is a cached figure and the board may hold more Pins than it reports, so quote it as approximate rather than exact.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardId`	string	Yes	Numeric Pinterest board ID returned by list_boards — never a board name or URL
`confirm`	boolean	Yes	Must be `true`, set only after the user has confirmed the board and every Pin on it should be destroyed. Any other value refuses the call.

Example Usage

“Delete board 1106196864631757445 — yes, I’m sure”

Response

Returns the deleted board’s ID, name and the number of Pins deleted with it.

list_board_sections

List the sections on a Pinterest board. Sections are subdivisions within a single board. An empty list means the board has no sections, which is normal.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardId`	string	Yes	Numeric Pinterest board ID returned by list_boards — never a board name or URL

Example Usage

“What sections does board 1106196864631757445 have?”

Response

Returns each section’s ID and name.

list_board_pins

The Pins saved on one of the account’s boards, secret boards included, however each got there. Use it to see what is on a board, what was added recently, or which Pins sit in which section. It is free; get_board_keyword_relevance only scores a board’s Pins against a keyword and spends a credit.

Pins come in Pinterest’s board order, which is mostly newest first but not strictly; to sort by date, sort by createdAt. startDate and endDate filter on when each Pin was saved to the board, and either may be given alone. Because the order is not strictly by date, every Pin is checked: a page can hold fewer Pins than limit, or none, while cursor is still returned. Keep calling with the returned cursor until it is absent; only then has the whole board been read.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardId`	string	Yes	Numeric Pinterest board ID returned by list_boards — never a board name or URL
`startDate`	string	No	Only Pins saved at or after this UTC date-time, e.g. 2026-10-01T00:00:00Z
`endDate`	string	No	Only Pins saved at or before this UTC date-time, e.g. 2026-10-07T23:59:59Z
`limit`	number	No	Pins to read from Pinterest per page, 1 to 250. Defaults to 100.
`cursor`	string	No	The cursor from the previous list_board_pins response

Example Usage

“What did I add to my Products board this week?”

“List every Pin on board 1106196864631757445 with its image and section.”

Response

Returns pins, each with its Pinterest pinId, boardId, boardSectionId, title, description, destinationUrl, Pinterest URL, image URL, createdAt, isRepin and creativeType, plus a cursor while more Pins remain.

boardSectionId matches list_board_sections, and is null for a Pin on the board itself. pinId is the Pinterest Pin id, which get_pin_analytics and save_pins_to_board take. It is not a Tailwind postId. imageUrl links to the image; the image itself is not returned.

get_board_keyword_relevance

Score how well one of your boards covers a keyword, and get back the Pins that earned the score. This reads the board’s real Pins from Pinterest — not just what Tailwind scheduled to it — so it covers Pins you added outside Tailwind too.

Metered: each scored call spends one plan credit. Score a board once and reuse the result rather than re-calling per question.

A response with state: "absent" means the board yielded no readable Pins — it is empty, or the Pinterest connection needs reconnecting. That is unknown coverage, not poor coverage, and it is not charged. Large boards are scored from a capped sample; when truncated is true the score covers part of the board rather than all of it.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardId`	string	Yes	Numeric Pinterest board ID returned by list_boards — never a board name or URL
`keyword`	string	Yes	The keyword or topic to score the board against, up to 255 characters

Example Usage

“How well does board 1106196864631757445 cover coastal decor?”

Response

Returns the board’s relevance tier (excellent, very-good, good, fair or poor), how many of the scored Pins cover the keyword, whether the board was sampled, and the on-topic Pins — strongest first — each with its own relevance tier.

get_recommended_pins

Find Pins from across Pinterest worth adding to one of your boards for a given keyword. Pairs with get_board_keyword_relevance: score a board to find a keyword it covers weakly, then call this to fix the gap. This is the “performance tier” companion to the Board Organization Audit skill.

Free — this spends no plan credits, unlike get_board_keyword_relevance.

Results exclude Pins the board already has — including ones added with save_pins_to_board, which land as a copy under a new Pin ID and are matched back to the Pin they were saved from — plus promoted/ad content and anything that does not clear the relevance threshold. relevance is therefore never poor, and an empty list means nothing on-topic was found for that keyword — not that the board is bad.

These are public Pins from across Pinterest, not your own content. Treat them as suggestions to review, then pass the IDs you want to save_pins_to_board — that saves these existing Pins onto the board. Use create_post only when you want a new Pin of your own instead of saving one of these.

This is the middle step of building a board around a topic: create_board → get_recommended_pins → save_pins_to_board.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardId`	string	Yes	Numeric Pinterest board ID returned by list_boards — never a board name or URL
`keyword`	string	Yes	The keyword or topic to find Pins for, up to 255 characters
`limit`	number	No	How many recommendations to return, 1–25. Defaults to 10. Bounds the response only — every candidate is scored, so the top result is the best of the whole candidate set.

Example Usage

“What Pins should I add to board 1106196864631757445 for coastal decor?”

Response

Returns the recommended Pins, strongest first. Each carries its Pinterest Pin ID, title, description, link, thumbnail URL, and its own relevance tier (excellent, very-good, good or fair) as the reason it fits.

Limits

Repeating the same keyword is served from a short-lived cache. Requesting many different keywords in quick succession can return 429 — that is Tailwind’s own limit protecting the upstream Pinterest search, not Pinterest refusing. A board too large to read completely within one request returns 504; the board has to be read in full, because a partial read would recommend Pins it already holds.

save_pins_to_board

Save existing Pinterest Pins onto one of your boards (a repin). This is the last step of building a board around a topic: create_board → get_recommended_pins for the new board → save_pins_to_board with the IDs you picked.

Saving onto a board create_board made in the last hour is free for up to 50 Pins in total, across calls. Any other save is billed like scheduling a Pin: one credit per saved Pin on credit plans, or one post from the plan’s post allowance. A save the plan cannot cover is refused with nothing saved.

This saves Pins that already exist on Pinterest. Creating a new Pin from your own image is create_post instead.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardId`	string	Yes	Numeric Pinterest board ID returned by list_boards — never a board name or URL
`pinIds`	array	Yes	Pinterest Pin IDs to save, 1–50. Must not contain duplicates — a repeated ID saves the Pin twice.

Example Usage

“Add the first five of those Pins to my Coastal Decor board.”

Response

Returns savedCount and failedCount.

Per-Pin failures are counted, not raised — but not every count in failedCount means the Pin definitely didn’t save. Most often it’s a deleted Pin or a boardId that doesn’t exist, but a save that timed out is also counted as failed even though it may have landed on Pinterest anyway. A boardId that does not exist comes back as a success with every Pin failed, so check savedCount — a result of 0 is a complete failure even though the call succeeded. Which Pins failed is not reported; re-read the board if you need to know.

Limits

Do not retry a failed or unclear result. Pinterest treats a repeat save as a second Pin, and a Pin counted as failed may have actually saved — retrying it (or the whole batch) risks duplicating whatever already landed. Re-check the board instead. Passing the same Pin ID twice in one call saves it twice for the same reason.

Re-running get_recommended_pins after a save is safe: saving stores a copy under a new Pin ID, and the recommendation exclusion matches that copy back to the Pin it was saved from, so a second pass returns what is still missing rather than what you just added.

Saves run four at a time against a 10-second-per-Pin budget, so a large batch of slow saves can exceed the request budget and return 504. Saves already in flight are not cancelled by that timeout, so the same caution applies — an unknown number of Pins may have saved despite the error. Keep batches to a few dozen IDs.

A dead Pinterest connection returns 422 (reconnect the account). A board Pinterest refuses to write to — most often one you collaborate on but do not own — returns 403; reconnecting does not help.

create_board_section

Create a named section on a Pinterest board. Creating a section does not consume Pin credits.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardId`	string	Yes	Numeric Pinterest board ID returned by list_boards — never a board name or URL
`name`	string	Yes	Section name, up to 180 characters

Example Usage

“Add a Pasta section to board 1106196864631757445”

Response

Returns the new section’s ID and name.

update_board_section

Rename a section on a Pinterest board.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardId`	string	Yes	Numeric Pinterest board ID returned by list_boards — never a board name or URL
`sectionId`	string	Yes	Board section ID returned by list_board_sections
`name`	string	Yes	New section name, up to 180 characters

Example Usage

“Rename the Pasta section on board 1106196864631757445 to Fresh pasta”

Response

Returns the section’s ID and its new name.

delete_board_section

Remove a section from a Pinterest board. The Pins in the section are not deleted — they move back to the board itself. This is not the same as delete_board, which destroys the board and every Pin on it.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`boardId`	string	Yes	Numeric Pinterest board ID returned by list_boards — never a board name or URL
`sectionId`	string	Yes	Board section ID returned by list_board_sections

Example Usage

“Delete the Pasta section from board 1106196864631757445”

Response

Confirms the section was deleted and names the section ID that was removed.

list_group_boards

Find public Pinterest group boards for a keyword, from Tailwind’s Group Board Finder. These are other people’s public boards — benchmark context for how boards in a niche are named and sized, not the user’s own boards, and their board IDs cannot be passed to create_post or schedule_post.

Group boards are not Tailwind Communities. Communities (formerly Tribes) has no MCP tool; Tailwind is replacing it with Turbo Groups, which also has no tool and lives in the Tailwind app under Turbo, on the My Groups tab. A request for either is a missing capability for request_capability.

Results are cached and refreshed in the background, so check status before reporting: ready means the boards returned are what we have (an empty list means a completed search genuinely found none), warming means a search is still running and the user should check back rather than being told there are no results, and unavailable means the search failed and no benchmark data can be given for that keyword.

Parameters

Parameter	Type	Required	Description
`keyword`	string	Yes	Topic to search for, e.g. “home decor”. Trimmed, whitespace-collapsed and lowercased before lookup; 100 characters maximum

Example Usage

“What group boards exist for home decor?”

Response

Returns the normalized keyword, the search status, and the matching public boards — each with its Pinterest board ID, name, description, URL, owner username, cover image, pin count, owner follower count, and whether it is collaborative or joinable.

list_timeslots

List the account’s smart schedule timeslots — Tailwind’s recommended posting times. Each slot is a recurring weekly time (day of week + time of day + timezone), not a concrete date, and this read carries no occupancy information: it does not say which upcoming occurrences are already taken.

This is a read for showing or explaining the schedule, not the way to schedule a Pin into it. To place a Pin on the schedule, pass useNextOpenSlot: true to create_post or schedule_post, which resolves the next genuinely open slot and applies the account’s Pin Spacing rules. Computing an occurrence from this list and passing it as sendAt ignores both, so Pins stack on the same slot and land off-schedule.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts

Example Usage

“What does my posting schedule look like on account 123456?”

Response

Returns each timeslot’s ID, day of week, time of day (24-hour HH:MM), timezone, and how it was added to the schedule.

get_schedule

The account’s schedule over a date window, as concrete dated entries: which smart schedule slots are open, and what occupies the rest. This is the companion to list_timeslots, which returns the recurring weekly rules and no occupancy.

Entries come back earliest first. open marks an unused smart schedule slot; scheduled, publishing and published each name the Pin holding that time. timeslotId is absent on a Pin that sits on no slot at all — scheduled at an arbitrary time, or left behind by a slot that has since moved.

Read it to answer questions and to reason about the queue. It is not a placement primitive: a slot that reads as open can be taken before a later write lands. To put a Pin on the schedule, pass useNextOpenSlot: true to create_post or schedule_post — do not copy a time from this response into sendAt.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`from`	string	No	Start of the window (ISO 8601). Defaults to now.
`to`	string	No	End of the window (ISO 8601). Defaults to 14 days after the start, and cannot be more than 60 days after it.

Example Usage

“What’s on my Pinterest schedule for account 123456 this week?”

“When is my next free posting slot on account 123456?”

Response

Returns schedule — each entry’s sendAt (Unix seconds), state, optional timeslotId, and the post holding it when the entry is not open — alongside the window actually read.

A 503 means building the schedule timed out; retry, or ask for a shorter window.

open_schedule_calendar

Opens an interactive calendar of an account’s scheduled, publishing, published, failed and missed Pins, in the account’s time zone, with weekly, 3-day and monthly views and a switcher between your Pinterest accounts. It renders in clients that show MCP Apps interfaces, such as ChatGPT (which also lists it in the sidebar) and Claude. In other clients it returns the accounts as plain data.

This tool has no parameters.

Example Usage

“Show my Pinterest schedule as a calendar”

Response

Returns the same account list as list_accounts. The calendar reads each account’s Pins through list_posts, including failed and missed Pins for past dates, and shows days and times in the account’s time zone (or the viewer’s, when the account has none). A failed Pin’s card explains why it failed.

create_timeslot

Adds one recurring weekly posting time to the account’s smart schedule. Free: managing the schedule costs no credits, here or in the dashboard.

This changes when future Pins publish; it does not schedule a Pin. To place a specific Pin, use create_post or schedule_post with useNextOpenSlot.

There is no duplicate check, matching the dashboard: calling twice with the same day and time leaves two slots at that time. Read list_timeslots first when adding to an existing schedule. Each call adds exactly one slot, so spreading a clustered schedule across mornings takes one call per slot.

Omit timezone to use the account’s own, which is almost always what the user means. An account with no timezone set returns a 400 asking for one explicitly.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`dayPreference`	number	Yes	Day of week: 0 = Sunday through 6 = Saturday
`time`	string	Yes	Time of day as 24-hour `HH:MM`, zero-padded (e.g. `09:30`)
`timezone`	string	No	IANA timezone the time is expressed in. Defaults to the account’s own.

Example Usage

“Add a Monday 9am posting time to account 123456.”

“My schedule is all evenings — add slots at 8am and noon on weekdays.”

Response

Returns the created timeslot, including its id for later edits, plus time as HH:MM and the timezone it was stored in.

update_timeslot

Moves an existing posting time to another day, time or timezone. Pass the timeslotId from list_timeslots and only the fields that change; anything omitted keeps its current value. At least one of dayPreference, time or timezone is required. Free.

This is the right tool for fixing a badly spread schedule: move the clustered slots rather than regenerating everything with rebuild_schedule, which discards the whole schedule.

Pins already scheduled onto the slot keep the times they were given. Moving a slot changes where future Pins land, so Pins may still publish at the old time until they clear.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`timeslotId`	string	Yes	Timeslot ID returned by list_timeslots
`dayPreference`	number	No	New day of week: 0 = Sunday through 6 = Saturday
`time`	string	No	New time of day as 24-hour `HH:MM`
`timezone`	string	No	New IANA timezone for the slot

Example Usage

“Move my Tuesday 10:32pm slot on account 123456 to 8am.”

“Shift every evening slot on account 123456 into the morning.”

Response

Returns the updated timeslot. Any edit marks the slot manual, matching what the dashboard does when someone moves a time by hand.

delete_timeslot

Removes a single recurring posting time by timeslotId. Free. Confirm with the user first and say which day and time is going away.

Pins already scheduled onto the slot are not unscheduled and not deleted — they keep their times and simply no longer sit on a recurring slot. Removing a slot only stops future Pins from being placed there.

If the user wants fewer posting times, deleting the specific slots they dislike is safer than rebuild_schedule, which discards every slot and regenerates the lot.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`timeslotId`	string	Yes	Timeslot ID returned by list_timeslots

Example Usage

“Remove the 2am posting slot from account 123456.”

Response

Returns the deleted timeslot as it was, so the caller can report exactly what was removed.

rebuild_schedule

Deletes every SmartSchedule timeslot the account has and generates slotsPerDay new ones on each of the 7 days, spread between 5am and 11pm in the account’s timezone. This is the dashboard’s “Generate new SmartSchedule” button. Free, but it cannot be undone: the user’s existing times are gone, including any set by hand. Evergreen (SmartLoop) slots are the one exception and survive untouched.

Use it only when the user has explicitly asked to regenerate the whole schedule. To spread a clustered schedule or change specific times, use update_timeslot, delete_timeslot and create_timeslot, which leave the rest alone.

There is no day-part preference: the generator spreads slots across the whole 5am–11pm window, so it cannot satisfy “mornings only”.

Rebuilds are serialized per account. A second rebuild arriving while one is still running is refused with a 409 rather than racing it, so a client that retries after a timeout cannot end up with a doubled schedule.

If a rebuild fails outright, read list_timeslots before deciding what to do. The delete and the insert are separate writes, so a failure between them can leave the account with no posting times, and re-running the rebuild is what restores them.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`slotsPerDay`	number	Yes	Posting times to generate per day, 1 to 50. The total is this times 7. The dashboard’s own default is 5.

Example Usage

“Regenerate my whole posting schedule for account 123456 with 3 times a day.”

Response

Returns rebuilt, the slotsPerDay used, the resulting timeslotCount, and timezoneSource — fallback means the account has no timezone set and America/New_York was used, which is worth surfacing to the user.

list_pin_spacing_rules

List the account’s Pin Spacing rules: the account-wide default, every URL-specific custom rule, the linked URLs that follow another URL’s rule, and any Board rules. Pin Spacing is the minimum number of days Tailwind keeps between scheduled Pins that share a destination URL, so a high daily cadence needs enough distinct URLs to fill it. A Board rule keeps Pins on one Board apart whatever their URL; a Pin follows both rules, and where they overlap the longer gap applies.

To find the rule one URL gets, use get_pin_spacing_rule instead of matching URLs against this list: matching ignores http/https and trailing slashes, and a linked URL inherits its base URL’s rule. Rules are read-only here; they can only be changed in the Tailwind dashboard.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts

Example Usage

“What Pin Spacing rules does account 123456 have?”

Response

Returns defaultRule (spacing and spacingUnits, or null when the account has no default), customRules (each with url, spacing, spacingUnits), linkedUrls (each url with the baseUrl whose rule it follows), boardDefaultRule (spacing and spacingUnits, or null), and boardCustomRules (each with boardId, spacing, spacingUnits). The Board fields are empty when Board spacing is not enabled for the account.

get_pin_spacing_rule

The Pin Spacing rule Tailwind applies to Pins linking to one destination url, resolved the same way useNextOpenSlot resolves it: a linked URL follows its base URL’s rule, a custom rule for the URL beats the account default, and URLs match regardless of http/https and trailing slashes. A null rule means Pin Spacing does not constrain that URL.

useNextOpenSlot on create_post and schedule_post honors this rule. An explicit sendAt sets only a Pin’s initial time and is not an exemption: a later Pin Spacing respace or schedule shuffle can still move that Pin, and no tool can lock it in place. Rules are read-only here; they can only be changed in the Tailwind dashboard.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`url`	string	Yes	The Pin destination URL to look up, the same value `create_post` takes as `url`
`boardId`	string	No	Numeric Board ID from list_boards; returns that Board’s rule as `boardRule`

Example Usage

“How far apart will Pins to https://shop.example.com/mug be scheduled?”

Response

Returns the url looked up, linkedToUrl (the base URL when url is a linked URL, otherwise null), and rule: ruleType (DEFAULT or CUSTOM), spacing, spacingUnits, and for a custom rule the url it is set for. rule is null when no rule applies. With boardId, it also returns boardId and boardRule: ruleType (DEFAULT or CUSTOM), spacing, spacingUnits, and for a custom rule the boardId. boardRule is null when the Board has no rule or Board spacing is not enabled for the account.

list_subscriptions

Check whether a Pinterest account has active, paying access — useful before relying on it for a paid capability, or when someone asks what plan they are on. Works the same whether the organization is on Tailwind’s legacy or modular billing; the caller never needs to know which. An account with no paying access is a normal answer, not an error.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts

Example Usage

“Does account 123456 have an active subscription?”

Response

Returns entitled — a single boolean answering whether the account can use paid features right now — alongside billingSystem and a subscriptions list explaining what is backing that access.

An account on legacy billing always reports exactly one entry describing its organization-wide plan. An account on modular billing reports one entry per current entitlement, which may be several (for example, separate Publishing and SEO entitlements) or none. Each entry names its source — the organization’s plan, a paid subscription, or a Tailwind-issued grant — plus its billing state, whether a cancellation is pending, when the paid period ends (when known), and, for modular entitlements, the product and billing cycle.

Only current entitlements are listed: subscriptions that have ended and grants that have expired are omitted rather than returned as inactive.

get_account_usage

Check how many credits and posts an account has left, and when they refill, before a credit- or post-consuming action such as a bulk generation, connecting an RSS feed, or scheduling many Pins. Works the same on every billing system. This read is free.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts

Example Usage

“How many credits does account 123456 have left this month?”

Response

Returns billingSystem, scope, credits (remaining, monthlyAllowance, and resetsAt, a Unix timestamp or null when no reliable upcoming reset is known), postLimit and unlimitedScheduling.

When unlimitedScheduling is true, the account is on the modular winback plan: it reports zero monthly credits but schedules Pins without spending any. Credits still pay for AI generation. It is always false on legacy and Shopify billing, where postLimit governs scheduling for the current usage period only.

On modular billing, scope is account: credits belong to this account and pay for scheduling (one credit per Pin, unless unlimitedScheduling is true) as well as AI generation, and postLimit is null. On legacy and Shopify billing, scope is organization: one credit pool and one post allowance are shared by every account in the organization, so every account reports the same numbers. That pool pays for credit-priced features such as AI generation (including SmartPins from a connected feed) and Turbo. Ordinary scheduling spends postLimit instead: used counts published plus scheduled posts across the organization’s Pinterest, Instagram and Facebook accounts in the current usage period, and a null limit means unlimited.

This is a planning snapshot, not permission. Trial allowances are tracked separately, so an action can succeed at zero credits or be refused with credits remaining.

create_post

Create a new Pinterest Pin from an image or video. With neither useNextOpenSlot nor sendAt it is saved as a draft in Tailwind; with either one it is scheduled to publish, which also requires title, description, url, and boardId. To change an existing Pin’s copy, Board or product tags, use update_post; only a new image needs delete_post plus a fresh create_post. To schedule an existing draft, use schedule_post.

A draft is a Tailwind draft, not a Pinterest one. Nothing is created on Pinterest, so the Pin does not appear in Pinterest’s own drafts or on the profile, and it stays unpublished until it is scheduled with schedule_post.

useNextOpenSlot: true places the Pin in the account’s next genuinely open smart schedule slot, honoring the account’s Pin Spacing rules for the Pin’s destination url — the same calculation the Pin Scheduler runs. Prefer it whenever the user has not named a specific time; reserve sendAt for a time they actually asked for. Computing an occurrence from list_timeslots and passing it as sendAt is not equivalent: it ignores which slots are already taken and ignores Pin Spacing.

An explicit sendAt sets only the Pin’s initial time. It is not an exemption from Pin Spacing: a later respace or schedule shuffle can still move the Pin. get_pin_spacing_rule shows which rule applies to a URL.

The media comes from exactly one of two sources: mediaUrl for anything with a publicly accessible URL, or uploadId for the user’s own file bytes, staged first with create_media_upload. Providing both, or neither, is rejected.

To create a carousel Pin (two to five images), pass carouselItems: the cover image stays in mediaUrl/uploadId, and carouselItems carries one to four further images, each with its own mediaUrl or uploadId. Carousels are images only — a video is rejected, as are product tags — and every image, cover included, must share the same width-to-height ratio.

To publish one Pin across several Boards spaced out over time — Tailwind’s interval Pinning, and what a saved Board list describes — pass intervalBoards in place of boardId, along with intervalType. Read a Board list’s boards with list_board_lists and pass them in that order; the list itself is not a target you can pass, because a list is a mutable grouping and what you publish to is the Boards it holds at the time of the call.

Each Board becomes its own Pin, charged accordingly — one Pin credit each on modular billing with Publishing access (winback plans excepted), and no credits on legacy and Shopify accounts, where they count against the plan’s post limit instead. The whole fan-out is atomic: if any Board fails, the Pins already written are deleted and the call fails, so a retry cannot duplicate them. The Pins carry no link back to each other — the create response’s intervalPosts is the only place the grouping appears, so keep those IDs if the set may need editing later.

Pins have no keyword field, here or on Pinterest: a keyword reaches Pinterest only as words in the Pin’s title or description. Tailwind keeps keywords in the organization’s Saved Keywords list, where each term can be tied to destination URLs — the list the Pin Scheduler’s Add keywords control shows for a Pin’s link. list_saved_keywords with url returns the keywords saved for a Pin’s link, and save_keywords with urls adds terms to that list.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`mediaUrl`	string	Conditional	Publicly accessible URL of the image or video to pin. Exactly one of `mediaUrl` or `uploadId` is required; must be omitted when `uploadId` is provided.
`uploadId`	string	Conditional	An upload from `create_media_upload` whose bytes have already been PUT to its `uploadUrl`. Single-use — it can be attached to exactly one Pin. Exactly one of `mediaUrl` or `uploadId` is required; must be omitted when `mediaUrl` is provided.
`mediaType`	string	No	Type of media: `image` (default) or `video`. Ignored when `uploadId` is provided — the upload’s own extension already determined its type.
`carouselItems`	array	No	One to four further images to make this a carousel Pin, each an object with `mediaUrl` or `uploadId`. Combined with the cover, a carousel holds two to five images total — images only, no product tags, and every image must share the same width-to-height ratio.
`title`	string	Conditional	Pin title (max 100 characters). Required when scheduling.
`description`	string	Conditional	Pin description (max 500 characters). Required when scheduling.
`url`	string	Conditional	Destination URL when the pin is clicked. Required when scheduling — it is also what Pin Spacing rules are keyed on.
`boardId`	string	Conditional	Target Pinterest board ID — the numeric board ID from `list_boards`, not a board name or URL. Required when scheduling to a single Board; use `intervalBoards` instead to publish across several.
`boardSectionId`	string	No	Section of `boardId` to publish into, from `list_board_sections`. Requires `boardId`, and is rejected if it is not a section of that board. Omit to publish to the board root.
`intervalBoards`	array	No	Two to twenty Boards to publish this Pin across, in publishing order — each an object with `boardId` and optional `boardSectionId`. The first Board is the one the Pin itself lands on; the rest follow one interval apart. Requires `intervalType` and either `sendAt` or `useNextOpenSlot`. Cannot be combined with `boardId`, and cannot be used on a draft.
`intervalType`	string	Conditional	Spacing between Boards: `daily`, `2_days`, `3_days`, `4_days`, `5_days`, `6_days`, `weekly`, or `monthly`. Required with `intervalBoards`, and rejected without it.
`intervalDays`	integer	No	Exact number of days between Boards (1–365), overriding `intervalType`’s preset — e.g. `weekly` with `intervalDays: 14` for a fortnight. Only valid with `intervalBoards`.
`intervalMode`	string	No	How each Board’s time is chosen: `slots` (default) lands every Board on a real smart schedule slot, so the gap may stretch when slots are full; `exact` lands each Board exactly the interval after the previous one, keeping the first Pin’s time of day and ignoring the schedule.
`altText`	string	No	Alt text for accessibility (max 500 characters)
`isSimplifiedPin`	boolean	No	Whether to create a simplified pin (default: `true`). Set to `false` for a standard pin.
`sendAt`	string	No	Explicit publish time (ISO 8601), in the future. Use only when the user named a specific time. Cannot be combined with `useNextOpenSlot`; omit both for a draft. Requires `title`, `description`, `url`, and a Board. Sets only the initial time, not an exemption from Pin Spacing: a later respace or schedule shuffle can still move the Pin.
`useNextOpenSlot`	boolean	No	Schedule into the account’s next open smart schedule slot, honoring its Pin Spacing rules for this Pin’s `url`. Cannot be combined with `sendAt`; omit both for a draft. Requires `title`, `description`, `url`, and a Board.
`productTagPinIds`	array	No	Pinterest product-catalog pin IDs to tag on the pin (business accounts only; max 24). Providing any forces a simplified pin.

Example Usage

“Create a pin on account 123456 with this image https://example.com/photo.jpg, title it ‘Summer Recipes’, and schedule it for January 20th at 2pm UTC”

“Pin this image to every board in my Home Decor board list, a week apart”

“Save this image as a draft on account 123456 — I’ll decide when to post it later”

Response

The tool returns a confirmation with:

Post ID
Status (draft, saved in Tailwind only, or queued)
Scheduled time (if applicable)
Board information

For an intervalBoards create it instead lists every Pin produced — one per Board, with its own post ID, Board and send time — under intervalPosts.

create_posts

Create up to 175 Pins in one call, each entry with its own image, title, description, link, Board and schedule, such as a spreadsheet import. Each entry takes the same fields as create_post except intervalBoards and carouselItems, which a batch refuses per entry; create those Pins with create_post one at a time. The call returns a batchId straight away, and the Pins are created in the background, one at a time in the order given. get_post_batch reports each entry as created, failed or pending.

A draft entry, one with neither sendAt nor useNextOpenSlot, may leave out mediaUrl and uploadId if it has a title, description or url. It is saved with Tailwind’s placeholder image and cannot be scheduled until the user replaces the image with Change media in Tailwind’s Pin Scheduler; these tools cannot change a Pin’s image. An entry that schedules needs an image.

Billing matches create_post: drafts are free, and each scheduled entry is charged when it is created. A batch the account cannot pay for is refused whole, with nothing created; credits that run out part way through fail only the entries after that point. Submitting the identical batch again within 7 days returns the original batch instead of creating its Pins twice; the order of fields within an entry does not matter. To retry, send only the failed entries in a new call with retryOfBatchId set to the batch they failed in, which lets a batch whose every entry failed be tried again.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`posts`	array	Yes	One to 175 entries, each with the fields of `create_post` except `intervalBoards` and `carouselItems`. Results come back in this order.
`retryOfBatchId`	string	No	When resending entries that failed, the `batchId` they failed in

Example Usage

“Import these 140 Pins from my spreadsheet, each to its own board at its own time”

“Make drafts for all of these titles and descriptions; I’ll add the images later”

get_post_batch

Check on a create_posts batch. Every entry is reported in the order submitted as created with its postId and postStatus, failed with the same error create_post would give, or pending. The batch is completed once nothing is pending; a full batch takes a few minutes. An entry that failed with a note that the Pin may exist should be checked with list_posts before it is sent again. Results are kept for 7 days. The tool is read-only.

Parameters

Parameter	Type	Required	Description
`batchId`	string	Yes	The batch id `create_posts` returned

Example Usage

“How is that import going?”

“Which of those Pins failed?”

schedule_post

Schedule or reschedule an existing draft or queued Pin, by postId (from create_post or list_posts), passing exactly one of useNextOpenSlot or sendAt. The Pin must already have title, description, and url set; a draft without a board also needs boardId. Does not work on published Pins. A draft exists only in Tailwind, not on Pinterest, until this step: scheduling is what puts it into Tailwind’s publishing flow. To create and schedule a new Pin in one step, use create_post instead.

useNextOpenSlot: true resolves the account’s next open smart schedule slot and applies its Pin Spacing rules for the Pin’s destination url. Prefer it whenever the user has not named a specific time.

A draft saved with multiple interval Boards can’t be scheduled this way. The call is refused, and retrying it fails the same way. To publish one Pin across several Boards, create it with intervalBoards on create_post.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`postId`	string	Yes	Post ID to schedule
`sendAt`	string	Conditional	Explicit publish time (ISO 8601), in the future. Exactly one of `sendAt` or `useNextOpenSlot` is required. Sets only the initial time, not an exemption from Pin Spacing: a later respace or schedule shuffle can still move the Pin.
`useNextOpenSlot`	boolean	Conditional	Schedule into the account’s next open smart schedule slot, honoring its Pin Spacing rules for the Pin’s `url`. Exactly one of `sendAt` or `useNextOpenSlot` is required.
`boardId`	string	Conditional	Target Pinterest board ID — the numeric board ID from `list_boards`, not a board name or URL. Required when scheduling a draft that doesn’t already have a board.
`boardSectionId`	string	No	Section to publish into, validated against the board this Pin ends up on. Send `""` to publish to the board root. Sending `boardId` without this field clears any section the Pin already had, because a section is only valid on its own board.

Example Usage

“Schedule post post_abc123 on account 123456 for tomorrow at 9am”

Response

Returns the updated post with:

Post ID
New status (queued)
Scheduled time

unschedule_post

Move a scheduled (queued) Pin back to draft, by postId (from list_posts), without losing it. Use it to hold back a time-sensitive Pin or revise one before it publishes, instead of deleting the Pin and creating a new one.

The Pin keeps its postId, image, title, description, link, board, board section, alt text, product tags and carousel images. Only its status and scheduled time change. It works on any queued Pin on the account, whether it was created in the Tailwind dashboard, through the API or over MCP, including a missed Pin whose scheduled time has already passed.

Any Pin credit charged for scheduling it is returned, the same as unscheduling in the Tailwind dashboard. A Pin scheduled on a free-trial allowance or in an earlier billing period, or on a legacy or Shopify plan, has nothing to return. Scheduling the draft again with schedule_post charges again.

Only queued Pins can be unscheduled. A published Pin, or one publishing right now, is rejected with post_already_published and has to be changed in the Pinterest app; a draft, failed or deleted Pin is rejected with post_not_queued.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`postId`	string	Yes	Post ID of the scheduled (queued) Pin to move back to draft, from list_posts

Example Usage

“The flash sale got pushed back. Take tomorrow’s sale Pin off the schedule so I can fix the dates.”

Response

Returns the Pin in the same shape get_post serves, now with status draft and no scheduled time.

pause_publishing

Stop every scheduled Pin on an account from publishing, for example to correct copy across many queued Pins before any of them goes out. Nothing about the Pins changes: queued Pins keep their scheduled times and drafts stay drafts.

While publishing is paused, any Pin whose scheduled time arrives fails instead of publishing, and it stays failed after resume_publishing: it has lost its slot and needs rescheduling with schedule_post. The rest of the schedule does not shift forward to fill the gap, so keep pauses short.

This is a switch for the whole account, not an edit to any Pin. To change Pins, call update_post on each one; to take one Pin off the schedule, use unschedule_post. The pause applies to the Pinterest account itself, so it also covers any other Tailwind account connected to the same Pinterest account. Pausing an account that is already paused changes nothing.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts

Example Usage

“Every Pin in my queue says the mug is dishwasher safe and it isn’t. Pause my queue while I fix them.”

Response

Returns publishing.status, now paused.

resume_publishing

Let an account’s scheduled Pins publish again after pause_publishing. Queued Pins whose scheduled time is still ahead publish at that time, unchanged.

Pins whose time arrived during the pause have already failed and are not retried. Find them with list_posts using status failed, and reschedule the ones that should still go out with schedule_post. A Pin failed by a pause reports failure reason publishing_paused. One failed by a pause before October 15, 2026 reports max_pin_limit instead; its failure time falls inside the pause, and it does not mean the account hit a limit. Resuming an account that is not paused changes nothing.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts

Example Usage

“I’ve fixed the copy. Turn my queue back on.”

Response

Returns publishing.status, now active.

update_post

Edit an existing Pin’s copy — title, description, destination link, board, alt text, product tags, or whether it is a simplified or standard Pin — on a draft or a scheduled (queued) Pin. Only the fields you send are changed; everything else is left as it is. Editing is free and does not consume a credit. This edits one Pin per call; the same edit across several Pins goes through preview_update_posts and then update_posts, which take up to 50 Pins at once and show each Pin’s before-and-after before anything is saved.

This does not schedule, reschedule or unschedule — use schedule_post or unschedule_post for that. A Pin’s image cannot be changed at all; that needs delete_post plus a fresh create_post. A Pin already published to Pinterest cannot be edited through Tailwind.

title and description cannot be set to empty. Moving a Pin to a different board clears any board section it was in, because a section belongs to one board. productTagPinIds is the way to tag catalog products on a Pin that was created without them, change which products it tags, or remove its tags — there is no need to delete and recreate the Pin for any of that. isSimplifiedPin switches a Pin between simplified and standard in place, too.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`postId`	string	Yes	Post ID of the draft or scheduled Pin to edit, from create_post or list_posts
`title`	string	No	New Pin title, up to 100 characters
`description`	string	No	New Pin description, up to 500 characters
`url`	string	No	New destination URL for the Pin
`boardId`	string	No	Move the Pin to this board. Numeric Pinterest board ID from list_boards — never a board name or URL
`boardSectionId`	string	No	Move the Pin into this section, validated against the board it ends up on. Send `""` to move it to the board root. Sending `boardId` without this field clears any section the Pin already had, because a section is only valid on its own board.
`altText`	string	No	New accessibility alt text, up to 500 characters
`productTagPinIds`	array	No	Pinterest product-catalog pin IDs to tag on the Pin, replacing whatever tags it has now (business accounts only, max 24). Send an empty array to remove every tag; omit the field to leave the Pin’s tags alone. Tagging forces a simplified Pin, and tags are refused on a carousel Pin — though an empty array is still accepted on one, so tags can be cleared off it.
`isSimplifiedPin`	boolean	No	`true` makes the Pin a simplified Pin, `false` a standard Pin; omit it to leave the Pin’s design as it is. `false` is refused while the Pin has product tags, since Pinterest rejects tags on standard Pins — send `productTagPinIds: []` in the same call to remove them.

Example Usage

“Change the description on that draft to mention the recipe takes 20 minutes”

“Tag the blue mug from my catalog on those three scheduled Pins”

“Make that SmartPin draft a simplified Pin instead of a standard one”

Response

Returns the updated Pin in the same shape get_post serves.

preview_update_posts

The first of the two calls a bulk edit takes. It changes nothing. It takes up to 50 entries, each naming a postId and the fields to change on that Pin, with the same fields and rules as update_post, and returns for every entry, in order, either will_update with the Pin’s previous and proposed values or failed with the reason the save would refuse it. When every entry would update, it also returns a previewToken, which update_posts requires to save this exact batch within 30 minutes. A batch with refused or unchecked entries gets no token: remove or fix those entries and preview again.

The tool does not search or match text: a find-and-replace across many Pins is reading them with list_posts, computing each Pin’s new value, and previewing them together. Tailwind keeps no history of Pin copy, so the preview is where the user sees the before-and-after for each Pin before anything is overwritten. The tool is read-only.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`posts`	array	Yes	One to 50 entries, each with `postId` and at least one of `title`, `description`, `url`, `boardId`, `boardSectionId`, `altText`, `productTagPinIds` or `isSimplifiedPin`, as documented on `update_post`. A `postId` may appear only once.

Example Usage

“Every scheduled Pin says 350F; change it to 180C in each description”

“Point all of my queued Pins for the old recipe page at the new URL”

update_posts

The second of the two calls a bulk edit takes: it saves a batch that preview_update_posts returned, once the user has agreed to it. It takes the same accountId and posts that were previewed and the previewToken the preview returned. A batch that differs from the preview in any way, an expired token, or no token at all is rejected with nothing changed. The tool carries destructiveHint: true.

The whole request is also rejected with nothing changed when it has more than 50 entries, repeats a postId, or has an invalid entry. Otherwise each Pin is saved on its own, and results lists every entry in request order:

updated: the edit was saved. previous holds the edited fields’ values from before the edit, and current the values as saved. A board move also reports boardSectionId, and a product-tag edit also reports isSimplifiedPin, since each changes the other.
failed: the Pin was not changed. error gives the same code and message update_post would.
not_attempted: the call ran out of time before reaching this Pin. It is unchanged; preview and save it again.

To undo a batch, preview and save each updated Pin’s previous as an entry with its postId. An empty title, description or url is absent from previous, since it cannot be emptied again; an empty alt text is reported as "", which clears it. Editing is free and never changes when a Pin publishes.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`posts`	array	Yes	The same entries that were previewed
`previewToken`	string	Yes	The `previewToken` from `preview_update_posts` for exactly these posts, within 30 minutes

Example Usage

“Yes, save those changes”

“Undo that last bulk edit”

delete_post

Permanently delete a Pin that has not been published to Pinterest. Published Pins cannot be deleted through Tailwind. To change a Pin’s title, description, link, Board, Board section, alt text or product tags, use update_post rather than deleting it — only a change of image needs a delete and a fresh create_post. To take a scheduled Pin off the schedule but keep it, use unschedule_post.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`postId`	string	Yes	Post ID to delete

Example Usage

“Delete post post_abc123 from account 123456”

Response

Confirms the post was deleted with the post ID.

list_posts

List an account’s Pins — drafts, scheduled (queued), published (sent), failed, or missed — with optional filtering by status. Returns each Pin’s postId for use with get_post, schedule_post and delete_post.

status: "draft" omits drafts not yet assigned to any Pinterest account (such as some Made For You drafts), which the Pin Scheduler counts in its “drafts that aren’t assigned to a Pinterest account yet” banner. The draft count can be lower than the dashboard’s by that number: that gap is expected, not missing drafts, but a larger one is worth reporting. Assigning them to the account from that banner makes them list.

A draft carrying a generationId was generated by Tailwind’s AI, from generate_pins_from_url or a connected feed, and is waiting for review: it never publishes on its own until someone schedules it. The reviewing generated drafts guide walks through reading those drafts, approving them with schedule_post, revising them with update_post or get_pin_design, and discarding them with delete_post.

Queued Pins come back in schedule order, soonest first, and without a startDate start from now, so overdue ones are listed only as missed. Every other status comes back newest first.

A missed Pin is a queued Pin whose scheduled time passed without it publishing. It is listed with status missed, while get_post reports it as queued. Failed, missed and uploading Pins match the date window by their scheduled time, except a failed Pin that had already published, which matches by when it published.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`status`	string	No	Filter by status: `draft`, `queued`, `sent`, `uploading`, `failed`, or `missed`. Default: `queued`
`limit`	number	No	Number of posts to return (1-100). Default: 50
`cursor`	string	No	Pagination cursor from previous response
`startDate`	string	No	Filter posts after this date (ISO 8601). Required for `sent`, `uploading` and `missed` status; for `queued` and `failed`, pass both dates or neither.
`endDate`	string	No	Filter posts before this date (ISO 8601). Required for `sent`, `uploading` and `missed` status; for `queued` and `failed`, pass both dates or neither. For `missed`, a date after now counts as now.

Example Usage

“Show me all draft posts on account 123456”

“List the last 10 sent posts from January 2024”

Response

Returns a list of posts with:

Post ID
Status
Board ID and section ID (if set), and the Board’s name once Tailwind has listed that Board
Scheduled time, and published time for sent Pins
Title (if set)
For a failed Pin, why it failed: a failureReason code such as board_not_found, and a failureMessage explaining it to the user, the same copy the Tailwind dashboard shows. Both are absent when Tailwind recorded no reason, and new codes are added over time.
Pagination cursor for next page

get_post

Read one Pin by its postId — status, media, title, description, destination URL, board, and scheduled or published time. Use this to confirm a single Pin’s current state instead of paging list_posts to find it. It is also how a user sees a Pin’s image again: clients that show Tailwind’s Pin card render the result with the image, which exists only in Tailwind, so a web or image search does not find it.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`postId`	string	Yes	Post ID of the Pin to read, from `create_post` or `list_posts`

Example Usage

“What’s the status of post post_abc123 on account 123456?”

“Show me the board and scheduled time for post post_abc123”

Response

Returns the single post, in the same shape list_posts returns for each entry, including failureReason and failureMessage on a failed Pin.

get_post_image

Return one Pin’s actual picture as an MCP image content block, not just a URL, so a client whose model accepts tool-result images can read the words in a graphic or match drafts to the copy prepared for them before scheduling. It is the cover image of an image or carousel Pin, or a video Pin’s cover. It never returns the video itself.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`postId`	string	Yes	Post ID of the Pin whose image to return, from `list_posts` or `get_post`

Example Usage

“Look at my draft Pins and tell me which one says ‘Fall wreath ideas’”

“Check that the image on post post_abc123 is the right one before you schedule it”

Response

A short text line plus an image content block (JPEG, PNG, GIF or WebP). Images hosted by Tailwind come back resized to 1000px wide.

get_account_analytics

How the whole Pinterest account is performing: impressions, engagement, saves and clicks as totals, plus a per-day series for trends. Covers claimed and unclaimed content alike — the same numbers Pinterest Insights shows inside Tailwind. Totals combine paid (promoted) and organic activity unless contentType says otherwise: ORGANIC reports how unpromoted Pins are doing, PAID promoted only. get_pin_analytics figures are always organic-only, so compare them against ORGANIC totals, not the default blend.

This is the account-wide rollup. For the best-performing Pins use list_top_pins; for one Pin use get_pin_analytics.

Omit both dates for the last 30 days. Supply both to choose a window — supplying one is an error, because the two plausible completions return materially different data. Pinterest reports at most 90 days back and at most a 90-day span. Reading analytics is free and consumes no credits.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`contentType`	string	No	Which activity to count: ORGANIC (unpromoted only), PAID (promoted only) or ALL (default, both blended)
`startDate`	string	No	First day of the window, UTC YYYY-MM-DD. Requires endDate. Omit both for 30 days.
`endDate`	string	No	Last day of the window (inclusive), UTC YYYY-MM-DD. Requires startDate.

Example Usage

“How did my Pinterest account 123456 do last month?”

“Are my impressions trending up on account 123456?”

Response

Returns summaryMetrics and dailyMetrics alongside the startDate, endDate and contentType actually used — always report that period and filter, since they may be the server-resolved defaults rather than ones you asked for.

A metric value of null means Pinterest has not finished computing it for that day; the day’s dataStatus says why. Do not read a null as a zero — a PROCESSING day is not a drop in performance.

list_top_pins

The account’s best-performing Pins over a window, in Pinterest’s own ranked order. Metrics and ranking combine paid (promoted) and organic activity unless contentType says otherwise, so by default ad spend can crowd organic Pins out of the list and a promoted Pin can rank far higher than its organic-only get_pin_analytics numbers suggest. Pass contentType ORGANIC to rank on unpromoted performance alone, or PAID for promoted only.

Ranks by ENGAGEMENT unless sortBy says otherwise, and the response echoes the metric used — say which one when reporting results, since “top” means nothing without it. Only five metrics rank: ENGAGEMENT, SAVE, IMPRESSION, OUTBOUND_CLICK and PIN_CLICK.

Keep the order returned; it is the ranking. This is also the usual way to obtain a Pinterest pinId for get_pin_analytics. Reading analytics is free and consumes no credits.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`sortBy`	string	No	Metric to rank by: ENGAGEMENT (default), SAVE, IMPRESSION, OUTBOUND_CLICK or PIN_CLICK
`contentType`	string	No	Which activity to count: ORGANIC (unpromoted only), PAID (promoted only) or ALL (default, both blended)
`startDate`	string	No	First day of the window, UTC YYYY-MM-DD. Requires endDate. Omit both for 30 days.
`endDate`	string	No	Last day of the window (inclusive), UTC YYYY-MM-DD. Requires startDate.

Example Usage

“Which of my Pins performed best on account 123456 this month?”

“Show me my most-saved Pins on account 123456.”

Response

Returns pins — each with its Pinterest pinId, title, description, destination and Pinterest URLs, image URL, boardId, creativeType and metrics — alongside the resolved startDate, endDate, and the sortBy and contentType actually applied.

boardId is the Pinterest board the Pin is saved to — the same id list_boards returns. Group by it to compare performance across boards.

creativeType is Pinterest’s creative format for the Pin, passed through verbatim: REGULAR, VIDEO, CAROUSEL, IDEA, COLLAGE and others Pinterest may add. Group or filter by it to compare performance across formats. It is null when Pinterest did not report one.

isPartial is true when some Pins Pinterest ranked could not be loaded because Pinterest limited the lookups. Their ids are in omittedPinIds, in ranking order, and they are missing from pins, so the list is incomplete and a Pin’s position in it may be higher than its true rank. Retrying shortly should return the full list. Pins Pinterest reports as deleted or no longer visible are left out without setting isPartial, since a retry would not bring them back.

An empty pins array with isPartial false is a real answer: either nothing was published in the window, or Pinterest has not reported on it yet. A wider window may help, up to the 90-day limit.

list_pins

Every Pin on the account, newest first, however it was published: through Tailwind, directly on Pinterest, or by another tool. Pins on secret boards are included. This is the complete inventory: list_posts covers only Pins Tailwind scheduled, and list_top_pins only ranked winners.

startDate and endDate filter on when the Pin was created (or saved, for a repin), and either may be given alone. pinType ORIGINAL keeps Pins the account created; SAVED keeps saves of other people’s Pins. A save of the account’s own Pin to another board (isRepin true) is in neither, so ORIGINAL and SAVED can sum to less than ALL: to count every save, use ALL and isRepin. There is no search filter, so to find a Pin by its link, UTM parameters or title, page through and match destinationUrl or title.

A page can hold fewer Pins than limit, or none, while cursor is still returned, because Pinterest has no date filter and Pins newer than endDate are skipped server-side. Keep calling with the returned cursor until it is absent; only then is the inventory, or the window, complete. Reading Pins is free and consumes no credits.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`startDate`	string	No	Only Pins created at or after this UTC date-time, e.g. 2026-10-01T00:00:00Z
`endDate`	string	No	Only Pins created at or before this UTC date-time, e.g. 2026-10-07T23:59:59Z
`pinType`	string	No	ORIGINAL (Pins the account created), SAVED (saves of other people’s Pins) or ALL (default)
`limit`	number	No	Pins to read from Pinterest per page, 1 to 250. Defaults to 100.
`cursor`	string	No	The cursor from the previous list_pins response

Example Usage

“How many original Pins did account 123456 publish last week?”

“Find the Pin on account 123456 that links to example.com/spring.”

Response

Returns pins, each with its Pinterest pinId, boardId, title, description, destinationUrl, Pinterest URL, image URL, createdAt, isRepin and creativeType, plus the pinType applied and a cursor while more Pins remain.

pinId is the Pinterest Pin id, which get_pin_analytics takes. It is not a Tailwind postId.

creativeType is Pinterest’s creative format, verbatim (REGULAR, VIDEO, SHOPPING and others), or null when Pinterest did not report one.

get_pin_analytics

One Pin’s performance: totals over a window, a per-day series, and lifetime totals that ignore the window entirely. Figures are organic-only: Pinterest’s per-Pin analytics exclude paid (promoted) distribution, so a promoted Pin reads far lower here than in list_top_pins or get_account_analytics. That gap is expected, not an error.

pinId is the Pinterest Pin id — not the Tailwind postId that list_posts and get_post return as id; a published post carries the Pinterest id in its own pinId field, so pass that. list_pins and list_top_pins return it too. Passing a Tailwind postId returns a 404.

A Pin this account owns can be read, including one it saved to a group board owned by someone else. A Pin someone else saved to a shared group board can return 403. Anything else returns the same 404: missing, someone else’s, or unreadable. A 403 means Pinterest permanently forbids analytics for that Pin — it will never report, so do not retry. Reading analytics is free and consumes no credits.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`pinId`	string	Yes	The Pinterest Pin id (a numeric string): the `pinId` field on a published post from list_posts or get_post, or a pinId from list_pins or list_top_pins. NOT the Tailwind postId (the post’s `id`).
`startDate`	string	No	First day of the window, UTC YYYY-MM-DD. Requires endDate. Omit both for 30 days.
`endDate`	string	No	Last day of the window (inclusive), UTC YYYY-MM-DD. Requires startDate.

Example Usage

“How is Pin 987654321012345678 doing on account 123456?”

“Show me the daily impressions for my top Pin on account 123456.”

Response

Returns summaryMetrics for the window, dailyMetrics per day, and lifetimeMetrics covering the Pin’s whole life — report the two totals distinctly, since they cover different periods and otherwise read as contradictory. Also returns boardId, the Pinterest board the Pin is saved to.

Comment and reaction counts (totalComments, totalReactions) come back only in lifetimeMetrics, not in the windowed totals, and are absent when Pinterest reports none. This is the only analytics tool that reports comments and reactions; get_account_analytics and list_top_pins do not.

generate_pins_from_url

Have Tailwind’s AI generate Pin drafts in Tailwind from a web page — a blog post, product page, or article URL. Asynchronous and metered: each generation spends plan credits by design tier (approximately 3 for basic, 7 for premium, 1 for no-template — resolved server-side) and typically completes in 1–3 minutes. Returns a generation ID to poll with get_generation_status; the finished drafts appear in list_posts (status draft) carrying a matching generationId.

Calling this again for the same URL while a generation is in flight returns the same generation with deduplicated: true and charges nothing. Repeating the call after it completes starts — and charges — a new generation, so poll before retrying. If the URL already has a SmartPin on this account, that record is reused as-is (its stored design configuration applies and tier parameters are ignored); a SmartPin for the URL on a different account is a conflict.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`url`	string	Yes	The web page to generate Pins from (http/https, max 2048 characters). Query parameters and fragments are ignored — variants of one page count as the same URL.
`title`	string	No	Display name for this generation source in the Tailwind dashboard (max 256 characters). Defaults to the URL.
`designTier`	string	No	`basic` (default), `premium`, or `no-template`. Determines the credit cost.
`premiumStyle`	string	Conditional	Visual style for premium designs: `image-highlight`, `text-highlight`, `minimalist`, `artistic`, `professional`, or `natural`. Required when `designTier` is `premium`; must be omitted otherwise.
`keywords`	array	No	Up to 10 keywords to guide the generated Pin copy

Example Usage

“Generate some Pins from my latest blog post https://example.com/blog/summer-recipes on account 123456”

Response

Returns the generation with:

Generation ID (poll it with get_generation_status)
Status (processing)
Design tier and nominal credit cost
Whether an existing SmartPin was reused, and whether the call deduplicated onto an in-flight generation

get_generation_status

Poll a Pin generation started by generate_pins_from_url. Generation typically completes in 1–3 minutes: poll every ~15 seconds and don’t give up before ~30 minutes — a hung generation can stay processing for ~25 minutes before the terminal generation-request-timed-out status appears. A “not found” response within ~10 seconds of starting the generation is a transient indexing artifact — retry it.

Parameters

Parameter	Type	Required	Description
`generationId`	string	Yes	Generation ID returned by generate_pins_from_url

Example Usage

“Is my Pin generation done yet?”

Response

Returns the generation’s status (processing, success, or failed), the source URL, timestamps, and — on failure — a stable failureCode (for example scrape-failed, no-images-on-page, not-enough-credits, generation-request-timed-out, or generation-cancelled). A scrape-failed generation also carries a failureDetail when the cause is known: blocked (the site’s firewall refuses Tailwind’s scraper; retrying won’t help until the site allows it), no-content (the page had no readable text, often because it was just published; retry once after a minute or two, and stop if it fails again), or fetch-failed (the page couldn’t be loaded; retry later). On success, list the account’s draft posts and filter by the matching generationId to find the generated Pins.

cancel_generation

Stop a Pin generation started by generate_pins_from_url before it runs. Cancelling only works while the generation is still queued: a cancelled generation is never charged, and it reads back as failed with failureCode generation-cancelled. Most generations start within seconds. After that their credits are committed and the cancel is refused, so poll get_generation_status until the generation finishes and use delete_post on any resulting drafts you don’t want. A “not found” response within ~10 seconds of starting the generation is a transient indexing artifact: retry the cancel.

Parameters

Parameter	Type	Required	Description
`generationId`	string	Yes	Generation ID returned by generate_pins_from_url

Example Usage

“Actually, cancel that Pin generation.”

Response

Returns the cancelled generation, in the same shape as get_generation_status: status failed, failureCode generation-cancelled, and the time it was cancelled as completedAt. A generation that has already started or finished returns an error and is left unchanged.

get_pin_design

Read the design of a Pin that Tailwind’s AI generated, before changing it. Returns the tier, every variation already rendered, and supportedOperations — the design tools that actually work on this Pin. Call this first and follow that list: the available operations differ by tier, and calling one the Pin does not support is rejected.

workspaceStatus reports whether the design metadata and the Pin agree. pending_apply means the workspace holds a design the Pin is not using: a finished regeneration always lands in this state, and so does an edit interrupted before it reached the Pin. Pass the returned pendingMediaUrl to select_pin_design_variation to apply it; no re-render is needed. The two cases are indistinguishable here, so treat pending_apply as a design awaiting a choice rather than an error to repair.

sourceImageCandidates lists the source photos stored on the SmartPin that generated the Pin, kept apart from the rendered variations because they are photos, not designs. userPicked holds the images the user chose for that SmartPin (empty when Tailwind picks images itself); ranked holds the images Tailwind scraped from the source page and scored great, good or poor at its latest ranking, each with its aspect ratio. Both reflect the SmartPin as it stands now, not when this draft was generated. To rebuild the design around one, pass its URL as mediaUrl to update_pin_design, or to regenerate_pin_design on a premium Pin, which spends credits. status is unavailable with reason: smart_pin_not_found when the SmartPin was deleted or the Pin predates the link, and reason: lookup_failed when the read failed and is worth retrying.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`postId`	string	Yes	Pin ID from list_posts

Example Usage

“What does the design on that generated Pin look like?”

Response

Returns the design’s tier, active image, original photo, overlay title and colors, every rendered variation, supportedOperations, workspaceStatus, and sourceImageCandidates.

update_pin_design

Re-render a template-designed Pin with a new overlay title, new colors, or a new image. Free, but it renders server-side and can take several seconds. Only works when get_pin_design lists update in supportedOperations — AI-generated (premium) Pins change through regenerate_pin_design instead.

Send everything you want changed in one call: each call is a separate render, and omitted fields keep their current values. For a new image, pass a publicly reachable mediaUrl, or an uploadId from create_media_upload. Video uploads are rejected; design editing is image-only.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`postId`	string	Yes	Pin ID from list_posts
`title`	string	No	Text overlaid on the design. This is not the Pin’s title.
`colors`	array	No	Up to 12 design colors as hex values
`mediaUrl`	string	No	Publicly reachable image to rebuild the design around, such as a URL from `get_pin_design`’s `sourceImageCandidates`
`uploadId`	string	No	Image staged with create_media_upload. Use instead of `mediaUrl`, not with it.

Example Usage

“Make the text on that Pin’s design say ‘Summer Recipes’ and use warmer colors”

Response

Returns the updated design in the same shape get_pin_design serves.

select_pin_design_variation

Make one of a Pin’s existing design variations the active one. Free and instant — no rendering, no credits. Pass a templateImageUrl from get_pin_design, the variationUrl a finished regeneration produced, or the pendingMediaUrl reported when workspaceStatus is pending_apply. When the target came from a regeneration the user has not chosen yet, confirm with them first rather than applying it to tidy the state.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`postId`	string	Yes	Pin ID from list_posts
`templateImageUrl`	string	Yes	A variation URL belonging to this Pin

Example Usage

“Use the second design instead”

Response

Returns the updated design.

revert_pin_design

Put a Pin back to the original photo its design was built from, discarding the generated design. Free and instant. Only works when get_pin_design lists revert in supportedOperations, which requires the Pin to still carry its original photo. The generated variations remain listed, so this is reversible with select_pin_design_variation.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`postId`	string	Yes	Pin ID from list_posts

Example Usage

“Just use the original photo for that Pin”

Response

Returns the updated design.

regenerate_pin_design

Have Tailwind’s AI generate a new design for an AI-designed (premium) Pin. Asynchronous and metered: it spends approximately 7 plan credits, takes a few minutes, and returns an ID to poll with get_design_regeneration_status. Only works when get_pin_design lists regenerate in supportedOperations.

Because it spends credits, confirm with the user before calling it and say what it will cost. Calling it again after one finishes starts — and charges — another regeneration, so poll before retrying.

The result does not replace the Pin’s design on its own. A finished regeneration returns a variationUrl that you pass to select_pin_design_variation to apply.

To revise the design a Pin already has rather than replace it, pass selectedVariationUrl. The generator only enters its edit path when that URL matches an existing premium variation; without it there is nothing to revise, so the same credits buy an unrelated design.

Regeneration is charged to the account in the request path. If that account has no active subscription the call fails with a payment-required message naming it, even when another account in the organization could have paid.

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Numeric Tailwind account ID returned by list_accounts
`postId`	string	Yes	Pin ID from list_posts
`title`	string	No	Text to overlay on the new design
`premiumStyle`	string	No	`image-highlight`, `text-highlight`, `minimalist`, `artistic`, `professional`, or `natural`. Defaults to the Pin’s existing style.
`userFeedback`	string	No	What to change, in the user’s own words (max 2000 characters)
`selectedVariationUrl`	string	No	The design to revise — the active variation’s `templateImageUrl` from `get_pin_design`. Pass it to adjust the current design; omit it to generate a fresh, unrelated one.
`mediaUrl`	string	No	Publicly reachable image to generate the new design from, such as a URL from `get_pin_design`’s `sourceImageCandidates`
`uploadId`	string	No	Image staged with create_media_upload. Use instead of `mediaUrl`, not with it.

Example Usage

“Regenerate that Pin’s design — make it more minimalist”

Response

Returns the regeneration ID to poll and the credit cost.

get_design_regeneration_status

Poll a design regeneration started by regenerate_pin_design. It usually completes in a few minutes: poll every ~15 seconds.

On success the response carries a variationUrl — the new design, which is not applied to the Pin. Pass it to select_pin_design_variation to make it the active design. On failure the charge is refunded; billing.refund reports whether the refund has landed yet.

Parameters

Parameter	Type	Required	Description
`regenerationId`	string	Yes	The ID returned by regenerate_pin_design

Example Usage

“Is the new design ready?”

Response

Returns the regeneration’s status (processing, success, or failed), the Pin it belongs to, the new variationUrl on success, and a billing object reporting what was charged and the refund state.

generate_pin_copy

Have Tailwind’s Ghostwriter write Pinterest Pin titles and descriptions against the organization’s saved brand context — the tone, style and audience captured from the account’s own content — and file the result in the account’s Ghostwriter history. Asynchronous and metered: each call spends a plan credit and usually completes in under a minute. Returns a generation ID to poll with get_copy_generation_status.

Org-scoped: no accountId is needed. Every call generates and charges again — there is no in-flight deduplication, so poll the ID you already have rather than repeating the call. This tool writes Pinterest Pin copy only; Tailwind’s other Ghostwriter generators are not exposed through MCP.

Parameters

Parameter	Type	Required	Description
`contentType`	string	Yes	The angle the copy should take: `lifestyle_content`, `featured_product`, `seasonal_promotion`, `behind_the_scenes`, or `education_content`.
`topic`	string	Yes	What the Pin is about — the product, post, or idea, in the user’s own words (max 500 characters).
`keywords`	array	No	Up to 10 keywords to work into the copy
`cta`	string	No	Call to action to end each Pin with (max 200 characters)
`priorOutputs`	array	No	Up to 10 `{ title, description }` pairs the user already has, so this generation varies from them instead of repeating them

Example Usage

“Write me some Pin titles and descriptions for my autumn table settings post”

Response

Returns the generation with:

Generation ID (poll it with get_copy_generation_status)
Status (processing)
The credits the generation cost

get_copy_generation_status

Poll a Pin copy generation started by generate_pin_copy. It usually completes in under a minute: poll every ~5 seconds.

Parameters

Parameter	Type	Required	Description
`jobId`	string	Yes	Copy generation ID returned by generate_pin_copy

Example Usage

“Is my Pin copy ready?”

Response

Returns the generation’s status (processing, success, or failed) and timestamps. On success, result.pins holds the generated title and description pairs — pass one to create_post, or offer them to the user to choose from.

create_media_upload

Stage your own file bytes for a Pin — a Canva export, a photo or a video on disk, anything that has no publicly accessible URL.

There are two ways to use it.

Attached file (ChatGPT). When the user attaches a file in the composer, ChatGPT passes it as file and the server fetches the bytes and uploads them itself. The returned uploadId is ready immediately — call create_post with it instead of mediaUrl. No PUT is needed, and the assistant never handles the bytes. Files up to 100 MB are relayed this way. ChatGPT occasionally drops the attachment from a call, which then arrives as a signed-URL call; a repeat call usually carries it.

Signed URL (everyone else). Called without file, the tool returns a short-lived, write-only uploadUrl. The bytes go straight to storage and never pass through the API:

Call this tool with the file’s extension to get an uploadUrl, a contentType, and an uploadId.
PUT the raw file bytes to uploadUrl with a Content-Type header exactly matching the returned contentType. The URL’s signature covers that header, so any other value is rejected.
Call create_post with that uploadId instead of mediaUrl.

uploadUrl expires much sooner than uploadId does — both deadlines come back on the response, so PUT the bytes promptly. The uploadId itself is single-use: it can be attached to exactly one Pin, so a second Pin needs a second upload. Staging bytes is free; only scheduling a Pin is billed.

Parameters

Parameter	Type	Required	Description
`extension`	string	Yes	The file’s extension, with or without a leading dot and in any case (`jpg`, `.PNG`, `mp4`). It determines both the upload’s media type and the `Content-Type` the signed URL is issued for. Accepted: `jpg`, `jpeg`, `png`, `svg`, `gif`, `webp`, `heic`, `mp4`, `mov`, `qt`. When `file` is also present, its `mime_type`/`file_name` take precedence.
`file`	object	No	A file attached in the ChatGPT composer, supplied by the ChatGPT platform rather than by the assistant. Carries `download_url` and `file_id` (always) plus `mime_type` and `file_name` (optional). When present, the server fetches the file and uploads it, and no PUT is required.

Example Usage

“Pin this photo from my desktop to my Recipes board”

Response

Returns the upload slot with:

uploadId — pass it to create_post in place of mediaUrl
uploadUrl — PUT the raw bytes here (already spent when the call carried a file)
contentType — the exact Content-Type header the PUT must send
mediaType (image or video), derived from the extension
uploadUrlExpiresAt and expiresAt — the PUT deadline and the attach deadline, as Unix timestamps

list_saved_keywords

Read your Saved Keywords list — the terms you have already chosen to track in Tailwind. This is not keyword research: it reads back your own list rather than discovering new keywords or reporting how a term is trending. Results are newest-first and paginated.

Pass url to read only the keywords saved for one destination URL — for example, to check what a Pin’s link already has before saving more with save_keywords.

Parameters

Parameter	Type	Required	Description
`search`	string	No	Only return saved keywords containing this text. Cannot be combined with `url`
`url`	string	No	Only return saved keywords associated with this destination URL. Cannot be combined with `search`
`limit`	number	No	Keywords per page, 1–100. Defaults to 50
`cursor`	string	No	`nextCursor` from a previous call, to read the next page

url must be a full http or https URL. It is matched exactly against the URL the keyword was saved with, trailing slash and query string included, except that http and https are treated as the same. A bare domain such as https://example.com also matches keywords saved for any page on that domain.

Example Usage

“What keywords do I have saved?”

“Which of my saved keywords are attached to https://example.com/blog/spring-decor?”

Response

Returns each keyword’s ID, term, when it was saved, any associated URLs and tags. Estimated monthly Pinterest search volume, commercial-intent score and detected language are included when Tailwind has data for the term and omitted when it does not — an omitted value means unknown, not zero.

save_keywords

Add keywords to your Saved Keywords list. Matching is case-insensitive, so re-sending a term already on the list returns the stored one instead of creating a duplicate. Saving keywords does not consume credits.

Parameters

Parameter	Type	Required	Description
`keywords`	array	Yes	Up to 50 keywords, each with a `term` (255 characters max) and optional `urls` (up to 25 of your own URLs to associate with it)

Example Usage

“Save ‘winter home decor’ and ‘cozy living room’ to my keywords”

Response

Returns the saved state of every term sent, whether newly created or already present.

delete_saved_keyword

Remove one keyword from your Saved Keywords list, by the id from list_saved_keywords — not the keyword text.

Parameters

Parameter	Type	Required	Description
`keywordId`	string	Yes	The `id` of a keyword returned by list_saved_keywords

Example Usage

“Remove ‘winter home decor’ from my saved keywords”

Response

Confirms the keyword was removed. An id that is not on your list returns a not-found error rather than a silent success, so a successful response always means the keyword really was deleted.

delete_saved_keywords

Remove several keywords from your Saved Keywords list at once, by their ids from list_saved_keywords.

This is all-or-nothing: if any id is not on your list, nothing is deleted and the error names the unknown ids. Re-sending a batch that already succeeded therefore returns a not-found error, not a second success.

Parameters

Parameter	Type	Required	Description
`keywordIds`	array	Yes	Up to 100 keyword `id`s returned by list_saved_keywords

Example Usage

“Clear out the five keywords I saved yesterday”

Response

Confirms how many keywords were removed.

tag_saved_keywords

Apply tags, by name, to keywords on your Saved Keywords list — for example, to mark the keywords that match your own site content. Takes keyword ids from list_saved_keywords. A tag name you haven’t used before is created; an existing tag is reused, never duplicated. Every keyword gets every tag you send, and re-applying a tag a keyword already has changes nothing. Tagging does not consume credits.

If any keyword id is not on your list, nothing is changed and the error names the unknown ids.

Parameters

Parameter	Type	Required	Description
`keywordIds`	array	Yes	Up to 100 keyword `id`s returned by list_saved_keywords
`tags`	array	Yes	Up to 10 tag names, 100 characters each

Example Usage

“Tag the keywords that match my blog posts as ‘owned content’”

Response

Returns every keyword you sent, with its tags after the change.

untag_saved_keywords

Remove tags, by name, from keywords on your Saved Keywords list. Takes keyword ids from list_saved_keywords, where each keyword’s tags field shows the tag names it carries. The tag itself is kept for reuse, even if no keyword carries it any more. Removing a tag a keyword doesn’t have changes nothing.

If any keyword id or tag name doesn’t exist on your account, nothing is changed and the error names what was not found.

Parameters

Parameter	Type	Required	Description
`keywordIds`	array	Yes	Up to 100 keyword `id`s returned by list_saved_keywords
`tags`	array	Yes	Up to 10 tag names to remove

Example Usage

“Take the ‘seasonal’ tag off my winter keywords”

Response

Returns every keyword you sent, with its tags after the change.

preview_feed

Resolve a website or feed URL and report what would be subscribed to, before connecting it. Given a plain site URL, this discovers its feed. Returns kind: "feed" with the resolved feed URL and a sample of its newest entries when there is one answer, or kind: "candidates" when the site exposes several feeds — pick one and pass its feedUrl to connect_feed. Nothing is saved and no credits are spent. Feeds belong to your organization, so no accountId is needed.

Parameters

Parameter	Type	Required	Description
`url`	string	Yes	A website URL or a feed URL, using http or https

Example Usage

“What would Tailwind pick up from myblog.com?”

Response

Returns either the resolved feed (its URL, host, title, entry and section counts, and up to 10 of the newest entries) or the list of candidate feeds the site exposes.

list_feeds

List the RSS feeds connected to your Tailwind organization, newest first, with the Pinterest account each one’s Pins go to, its status, and how many SmartPins it has generated. Feeds are org-scoped rather than per-account: omit accountId to see every feed, or pass one to see only the feeds assigning Pins to that account. Results are paginated.

Parameters

Parameter	Type	Required	Description
`accountId`	string	No	Only feeds whose Pins are assigned to this account, from `list_accounts`. Omit for every feed in the organization
`limit`	number	No	Feeds per page, 1–100. Defaults to 50
`cursor`	string	No	`nextCursor` from a previous call, to read the next page

Example Usage

“Which blogs are connected to Tailwind?”

Response

Returns each feed’s ID, URL, title, assigned account, status (active or paused), generation defaults, when it was last checked and why that failed if it did, and its SmartPin count. An empty page reports which of these it means: the organization has no feeds, none are assigned to the given account, or the cursor is past the last one.

connect_feed

Subscribe to an RSS feed so Tailwind automatically creates Pins from it. This is an ongoing automation, not a one-time import: once a day Tailwind checks the feed and drafts a SmartPin for each new post, and every generated Pin consumes SmartPin credits by its design tier, the same as a manual generation — so a busy feed drives ongoing credit use. Pins are created as drafts for review; nothing is scheduled or published automatically. The feed’s current posts are snapshotted as the baseline, so only posts published after connecting generate Pins.

feedUrl must be an actual feed URL — use preview_feed first when you only have a site URL. accountId must be a currently connected Pinterest account, since a feed assigned to a disconnected one would be skipped every day without any error. A feed URL that is already connected returns a conflict rather than a duplicate. Connecting itself spends no credits.

Parameters

Parameter	Type	Required	Description
`feedUrl`	string	Yes	The RSS feed URL to watch, using http or https
`accountId`	string	Yes	Numeric Tailwind account ID from `list_accounts`. Generated Pins are assigned to this account and it cannot be changed later
`keywords`	array	No	Keywords applied to every Pin this feed generates, up to 50
`designTier`	string	No	`basic` (default), `premium` or `no-template`. Sets what each generated Pin costs in credits; `premium` requires `premiumStyle`
`premiumStyle`	string or null	No	One of `image-highlight`, `text-highlight`, `minimalist`, `artistic`, `professional` or `natural`. Required on the premium tier and must be null or absent otherwise
`generationFrequency`	string	No	`every-3-days`, `weekly`, `every-2-weeks` or `monthly`: how often each generated Pin is redesigned when `autoRegenerate` is on. Not how often the feed is checked — that is daily
`autoRegenerate`	boolean	No	Whether each generated Pin keeps being periodically redesigned, each redesign a generation of its own

Example Usage

“Connect my blog’s RSS feed so new posts become Pins on my main account”

Response

Returns the new feed subscription, including the id to use with get_feed, update_feed and delete_feed.

get_feed

Read one feed subscription by its id from list_feeds or connect_feed: whether it is active or paused, when it was last checked, why that failed if it did, and how many SmartPins it has generated. No accountId is needed.

Parameters

Parameter	Type	Required	Description
`feedId`	string	Yes	The `id` of a feed returned by list_feeds, connect_feed or get_feed

Example Usage

“Is my blog feed still working?”

Response

Returns the feed. A feed that is not your organization’s, or has been removed, returns a not-found error.

update_feed

Pause or resume a feed, or change the defaults applied to the Pins it generates. Send only the fields to change, and at least one.

Pausing (status: "paused") keeps the subscription but stops the daily check, so the feed’s record of already-seen posts stops advancing: everything the site publishes during the pause counts as new on resume and will generate Pins — and spend credits — until the backlog clears, up to 25 per feed per day. To stop generation for good without that catch-up, use delete_feed instead. Resuming (status: "active") re-checks the feed’s Pinterest account and is refused if it is no longer connected. The account a feed is assigned to cannot be changed. Editing spends no credits.

Parameters

Parameter	Type	Required	Description
`feedId`	string	Yes	The `id` of a feed returned by list_feeds, connect_feed or get_feed
`status`	string	No	`paused` to stop the daily check, `active` to resume it
`keywords`	array	No	Keywords applied to every Pin this feed generates, up to 50
`designTier`	string	No	`basic`, `premium` or `no-template`; `premium` requires `premiumStyle`. Omitting this keeps the feed’s current tier rather than resetting it to `basic`
`premiumStyle`	string or null	No	Required on the premium tier; send null when moving off it so the stored style is cleared
`generationFrequency`	string	No	`every-3-days`, `weekly`, `every-2-weeks` or `monthly`
`autoRegenerate`	boolean	No	Whether generated Pins are periodically redesigned

Example Usage

“Pause my blog feed until after the holidays”

Response

Returns the updated feed. When pausing or resuming, the text explains the catch-up behaviour so the assistant can pass it on.

delete_feed

Stop watching a feed for good. The daily check stops and no further Pins are generated from it; SmartPins it already generated are left alone. To stop generation temporarily instead, pause it with update_feed.

Parameters

Parameter	Type	Required	Description
`feedId`	string	Yes	The `id` of a feed returned by list_feeds, connect_feed or get_feed

Example Usage

“Disconnect the old recipes blog from Tailwind”

Response

Confirms the subscription was removed. A feed that is not your organization’s returns a not-found error rather than a silent success, so a successful response always means it really was removed.

request_capability

Tell Tailwind about something the MCP server cannot do yet — a tool you expected and could not find, a missing field or filter, or a step you had to work around. The assistant sends one when the user asks it to pass feedback or a feature request to Tailwind, or after the user agrees to its offer to do so.

Requests go to Tailwind’s product team, who use them to decide what to build next. Your description is recorded in Tailwind’s internal analytics and posted to an internal Tailwind channel for staff to read, so send only what you would be comfortable sharing with Tailwind — don’t include credentials or personal data. No request resource is created: there is nothing to read back, no ticket to follow up on, and no timeline, so the response is only an acknowledgement. This is not for reporting errors — a rejected argument, an expired connection, or an out-of-credits message are not missing capabilities.

Parameters

Parameter	Type	Required	Description
`description`	string	Yes	What you were trying to do and what was missing, up to 1000 characters

Example Usage

“There’s no way to change a scheduled Pin’s board — let Tailwind know that’s missing”

Response

Confirms the request was passed along. Sending the same request twice reports it twice; nothing deduplicates them.

report_issue

Tell Tailwind that a tool gave you a wrong answer rather than an error — a result that contradicts another result, a result you had to work around, or an output the user says is wrong. The assistant sends one when the user asks it to report a problem to Tailwind, or after the user agrees to its offer to do so.

Reports go to the people who maintain these tools, who read them to find what is broken. Your description and tool are recorded in Tailwind’s internal analytics and posted to an internal Tailwind channel for staff to read, so send only what you would be comfortable sharing with Tailwind — describe the problem rather than quoting the user’s content, and don’t include credentials or personal data. No report resource is created: there is nothing to read back and no ticket to follow up on, so the response is only an acknowledgement, and nothing about the result that prompted it changes. This is not for reporting errors — a rejected argument, an expired connection, or an out-of-credits message are errors to handle, not wrong answers. If Tailwind has no tool for what you need at all, use request_capability instead.

Parameters

Parameter	Type	Required	Description
`description`	string	Yes	What you asked for, what came back, and why it is wrong, up to 1000 characters
`tool`	string	No	The tool you believe returned the wrong result. Recorded as your claim and never checked against the tool list

Example Usage

“That board count doesn’t match what you told me a minute ago — flag that to Tailwind”

Response

Confirms the report was passed along. Reporting the same issue twice reports it twice; nothing deduplicates them.

Tool Availability

All tools require an authenticated Tailwind connection, using OAuth or an API key. Tools are automatically available to the AI assistant once the server is connected.

Error Handling

When a tool encounters an error, the AI assistant will explain what went wrong. Common errors include:

Error	Description	Solution
Account not found	The account ID doesn’t exist	Verify the account ID with `list_accounts`
Post not found	The post ID doesn’t exist	Check the post ID is correct
Cannot delete sent post	Post has already been published	Only posts not yet published can be deleted
Invalid sendAt	Schedule time is in the past	Use a future date/time
Account not connected to Pinterest	`list_boards` found no linked Pinterest user for the account	Reconnect the account in Tailwind, then retry
Could not read this account’s Boards	`list_boards` was refused because the account’s Pinterest connection is no longer valid	Reconnect the Pinterest account in Tailwind, then retry. If it still fails after reconnecting, contact Tailwind support
Pinterest is limiting requests	Pinterest rate-limited the `list_boards` read	Retry in a few minutes
Pinterest did not respond in time	The `list_boards` read timed out. Nothing was changed	Retry the request
Boards could not be loaded	Pinterest failed to return Boards for `list_boards`	Retry in a few minutes, and contact Tailwind support if it keeps happening

Best Practices

Always verify account IDs first - Use list_accounts to get valid IDs
Provide complete information - Include title, description, and URL for best results
Use clear scheduling language - Say “January 20th at 2pm EST” rather than “next week”
Review before publishing - Create drafts first if you want to review before scheduling