create_post
Use this when the user wants to create a Pinterest Pin from an image or video — as a draft (omit both sendAt and useNextOpenSlot), or published on a schedule. A draft is saved in Tailwind only: nothing is created on Pinterest, so it does not appear in Pinterest's own drafts or on the user's profile, and it stays unpublished until it is scheduled with schedule_post. To schedule, pass title, description, url, EITHER boardId (numeric ID from list_boards) or intervalBoards, and ONE of: useNextOpenSlot: true, which places the Pin in the account's next open smart schedule slot, or sendAt, an explicit ISO 8601 time. To publish the SAME Pin to several Boards spaced over time — Tailwind's interval Pinning, and what a saved Board list describes — pass intervalBoards instead of boardId, with intervalType for the spacing; do that rather than calling create_post once per Board, which would publish them all at once. Prefer useNextOpenSlot whenever the user has not named a specific time ("schedule this", "post it at a good time", "add it to my queue") — Tailwind's smart schedule is the product, and it applies the account's Pin Spacing rules for the destination URL, which an invented timestamp cannot. Reserve sendAt for a time the user actually asked for. Scheduling is the charged step — drafts are free, and what a scheduled Pin costs depends on the account's billing: modular-billing accounts with Publishing access, whether subscribed or granted, spend one Pin credit per Pin, except on winback plans, which schedule without charge; modular accounts without Publishing draw on a limited free-trial allowance; and legacy and Shopify accounts spend no credits at all, bounded by their plan's post limit for the billing period instead. To put the Pin in a Board section, pass boardSectionId alongside boardId (from list_board_sections). The media comes from exactly one of two sources: mediaUrl for anything with a public URL, or uploadId for the user's own file bytes, staged first with create_media_upload. To create a multi-image carousel Pin instead of a single image, pass carouselItems: two to five images total, the cover in mediaUrl/uploadId and the rest as carouselItems, each with its own mediaUrl or uploadId — images only, no product tags, and every image must share the same width-to-height ratio. Returns the new Pin's postId. To change an existing Pin's title, description, link, Board, Board section, alt text or product tags, use update_post rather than deleting and recreating it — only a change of image needs delete_post plus a fresh create_post. To schedule an existing draft, use schedule_post. Neither this tool nor a Pinterest Pin has a keyword field: 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; that list is what 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. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Destination URL when the pin is clicked. Required when scheduling — it is also what Pin Spacing rules are keyed on, so useNextOpenSlot needs it. | |
| title | No | Pin title (max 100 characters). Required when scheduling. | |
| sendAt | No | Explicit publish time (ISO 8601, e.g. 2025-01-15T10:00:00Z), in the future. Use only when the user named a specific time — otherwise use useNextOpenSlot. Cannot be combined with useNextOpenSlot. Omit both for a draft. Requires title, description, url, and either boardId or intervalBoards. It sets only the initial time and is not an exemption from Pin Spacing: a later respace or schedule shuffle can still move the Pin. | |
| altText | No | Alt text for accessibility (max 500 characters) | |
| boardId | No | Target Pinterest board ID. Must be the numeric board ID (e.g. "1106196864631757445") from list_boards — not a board name or URL. Required when scheduling. | |
| mediaUrl | No | 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 | No | The uploadId from create_media_upload, once its bytes are staged: during that call when it carried an attached file, otherwise by a PUT to its uploadUrl. This is how a file with no public URL gets pinned. 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. | |
| accountId | Yes | Numeric Tailwind account ID returned by list_accounts | |
| mediaType | No | Type of media (default: image). Ignored when uploadId is provided — the upload's own extension already determined its type. | |
| description | No | Pin description (max 800 characters). Required when scheduling. | |
| intervalDays | No | Exact number of days between Boards, overriding intervalType's preset. Use for a gap the presets do not cover — e.g. intervalType "weekly" with intervalDays 14 for a fortnight. | |
| intervalMode | No | How each Board's time is chosen. "slots" (the default) lands every Board on a real smart schedule slot, so the gap may stretch when slots are full — prefer it. "exact" lands each Board exactly the interval after the previous one, keeping the first Pin's time of day, and ignores the schedule. | |
| intervalType | No | How far apart the Boards publish. Required with intervalBoards, and only valid with it. | |
| carouselItems | No | Turns this into a carousel Pin: further images in order after the cover in mediaUrl/uploadId, one to four entries so the carousel holds two to five images total (Pinterest's limit). Images only — a video carousel is rejected, as are product tags, and every image (cover included) must share the same width-to-height ratio. Each entry takes a mediaUrl or an uploadId, and the two forms can be mixed across entries. | |
| boardSectionId | No | Section of boardId to publish into. Requires boardId, and is rejected if it is not a section of that board. Omit to publish to the board root. Use list_board_sections to look up section IDs. | |
| intervalBoards | No | Publish this one Pin across several Boards, spaced out over time — Tailwind's interval Pinning. Give the Boards in the order they should publish; the first is the Board the Pin itself lands on and the rest follow one interval apart. Use this instead of boardId whenever the user wants one image on several Boards ("pin this to all my recipe boards", "spread this across my boards weekly"), rather than calling create_post once per Board — that would publish them all at the same time, for the same cost. Requires intervalType, and sendAt or useNextOpenSlot. Cannot be combined with boardId. Each Board becomes its own scheduled Pin and is 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. | |
| isSimplifiedPin | No | Whether to create a simplified pin (default: true). Set to false for a standard pin. | |
| useNextOpenSlot | No | Schedule into the account's next open smart schedule slot, honoring its Pin Spacing rules for this Pin's url. Use this instead of computing a time yourself whenever the user has not named one. Cannot be combined with sendAt. Omit both for a draft. Requires title, description, url, and either boardId or intervalBoards. | |
| productTagPinIds | No | Pinterest product-catalog pin IDs to tag on the pin (business accounts only; max 24). Providing any forces a simplified pin, since Pinterest rejects tags on standard pins. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| post | Yes | ||
| intervalPosts | No | Every Pin an intervalBoards create produced, in Board order and including `post` itself. Absent for a single-Board Pin. This is the only place the grouping appears — each Pin is stored as an ordinary single-Board Pin, so a later get_post or list_posts cannot tell they belong together. Keep these IDs if the user may want to change or delete the set. |