create_pins_from_url
Creates
In-chat screen
Makes finished Pinterest pins from a web page: a blog post, a product page, an Etsy listing or any public link. Made to Spark reads the page, picks its best photos and writes the pin headlines, then renders the pins in the user's brand colours. Then call get_pin_batch_status with the returned batch_id straight away (it waits for the pins itself; never wait or sleep first). Pins land in the user's My Pins as drafts, nothing is published.
Try: “Make 3 pins from https://myblog.com/lemon-ricotta-pancakes”
Parameters (4)
| Name | Type | Description |
| urlrequired |
string |
The public web page to make pins from: a blog post, recipe, product page, Etsy listing or similar. |
| count |
integer |
How many different pins to make from the page, 1 to 5. Each gets its own photo, layout and headline.1–5 |
| use_credits |
boolean |
Only after the user agreed to spend credits (1 per pin) because their plan's template pins are used up. Never set it on your own. |
| workspace |
string |
Which Made to Spark workspace (name or site) to use, when the user has several. Usually leave it out: the workspace is picked from the link. list_workspaces shows them. |
get_pin_batch_status
Read-only
In-chat screen
Shows how a batch started with create_pins_from_url is doing: each pin's state (queued, processing, completed or failed), its headline, and the image address once it is rendered. Each call waits up to 20 seconds for unfinished pins and answers as soon as they are ready, so call it straight after create_pins_from_url and again right away if some are still being made; never wait or sleep between calls. Ready pins show a pin_id, which schedule_pins takes.
Try: “Are my pins ready?”
Parameters (1)
| Name | Type | Description |
| batch_idrequired |
string |
The batch_id returned by create_pins_from_url. |
find_my_posts
Read-only
Finds the user's own blog posts or product pages about a topic (for example "Peru"), from their site's sitemap, with how many pins each already has. Use it before create_pins_for_posts when the user asks for pins for "all my posts about X".
Try: “Find my posts about Italy”
Parameters (3)
| Name | Type | Description |
| topicrequired |
string |
What the posts are about, for example "Peru" or "budget planner". |
| workspace |
string |
Which workspace (name or site), when the user has several. |
| site |
string |
The site to look on, when the workspace has none connected, for example https://myblog.com. |
create_pins_for_posts
Creates
In-chat screen
Makes template pins for many posts in one go (paid plans): up to 30 post links, 1 to 5 pins each, using the posts' own photos (never AI images). First call without confirm to get the plan (how many pins, what it costs); show it to the user, and only after they agree call again with confirm true. Pins are made in the background; follow them with get_bulk_status.
Try: “Make 3 pins for each of my posts about Italy”
Parameters (5)
| Name | Type | Description |
| urlsrequired |
string[] |
The post links, up to 30 (from find_my_posts or the user).up to 30 items |
| pins_per_post |
integer |
Pins per post, 1 to 5. Defaults to 3.1–5 |
| confirm |
boolean |
Only true after the user agreed to the plan returned by the first call. |
| use_credits |
boolean |
Only after the user agreed to spend credits for pins beyond what the plan covers. |
| workspace |
string |
Which workspace, when the user has several. Usually picked from the links. |
get_bulk_status
Read-only
In-chat screen
Shows how pins for many posts (create_pins_for_posts) are doing: each post's pins, and the pin_ids of every ready pin, which schedule_pins takes.
Try: “How are the pins for my Italy posts coming along?”
Parameters (1)
| Name | Type | Description |
| bulk_idrequired |
string |
The bulk_id returned by create_pins_for_posts. |
get_pin_details
Read-only
Shows what goes to Pinterest with each pin: its Pinterest title, description, alt text and link (the headline drawn on the image is separate). Use it before scheduling so the user can check the words; edit_pin_details changes them.
Try: “Show me the title and description of the second pin”
Parameters (1)
| Name | Type | Description |
| pin_idsrequired |
integer[] |
The pins to show, up to 10.up to 10 items |
edit_pin_details
Changes or removes
Changes what goes to Pinterest with a pin: its Pinterest title, description, alt text or link. Give only what should change. If the pin is already scheduled and has not posted yet, the scheduled pin is updated too. It does not change the headline drawn on the image.
Try: “Make the description of pin 2 shorter and add the word "easy"”
Parameters (5)
| Name | Type | Description |
| pin_idrequired |
integer |
The pin to change. |
| title |
string |
New Pinterest title, up to 100 characters. |
| description |
string |
New Pinterest description, up to 800 characters. |
| alt_text |
string |
New alt text describing the image, up to 500 characters. |
| link |
string |
New page the pin sends people to (https://…). |
list_workspaces
Read-only
Lists the user's Made to Spark workspaces (usually one per blog or shop, each with its own Pinterest account). Other tools take a workspace name when the user has several; most pick it from the link on their own.
Try: “Which workspaces do I have?”
No parameters.
list_boards
Read-only
Lists the Pinterest boards the user can post to, each with the board_id that schedule_pins takes. With several workspaces, boards are grouped by workspace; a pin can only go to a board in its own workspace.
Try: “Which boards can I post to?”
Parameters (1)
| Name | Type | Description |
| workspace |
string |
Only this workspace's boards (name or site). Leave out to see every workspace. |
schedule_pins
Creates
In-chat screen
Schedules ready pins (pin_ids from get_pin_batch_status or add_pin_image) to one of the user's Pinterest boards (board_id from list_boards). The pins post through their own workspace's Pinterest account, so the board must be in that workspace. Made to Spark posts them to Pinterest at those times on its own; the chat does not need to stay open. Either give exact times, or a start_date and pins_per_day to have good posting times picked. Confirm the board and timing with the user before calling.
Try: “Schedule them on my Recipes board from Monday”
Parameters (5)
| Name | Type | Description |
| pin_idsrequired |
integer[] |
The pins to schedule, in posting order. Pins must be ready (finished rendering).up to 50 items |
| board_idrequired |
integer |
The board to post to, from list_boards. |
| start_date |
string |
First day to post, as YYYY-MM-DD in the user's timezone. Defaults to tomorrow. Ignored when times is given. |
| pins_per_day |
integer |
Only for several pins: how many to post per day, 1 to 10. Leave it out for a single pin. Ignored when times is given. Pins for the same page are always placed a week apart, whatever this says.1–10 |
| times |
string[] |
Exact times instead of a spread: one "YYYY-MM-DD HH:MM" per pin, same order as pin_ids, in the user's timezone. A time that clashes with another pin moves 15 minutes later. |
show_schedule
Read-only
In-chat screen
Shows the pins waiting to post to Pinterest over the coming days: when, which board, the pin title, and the scheduled_pin_id that unschedule_pin takes.
Try: “What is going out this week?”
Parameters (2)
| Name | Type | Description |
| days |
integer |
How many days ahead to show, 1 to 45. Defaults to 14.1–45 |
| workspace |
string |
Only this workspace (name or site). Leave out to see every workspace. |
unschedule_pin
Changes or removes
Takes a pin off the schedule before it posts (scheduled_pin_id from schedule_pins or show_schedule). The pin itself stays in My Pins and can be scheduled again.
Try: “Take Thursday's pin off the schedule”
Parameters (1)
| Name | Type | Description |
| scheduled_pin_idrequired |
integer |
The scheduled_pin_id to remove. |
show_auto_pin
Read-only
Shows what Auto Pin does for the user on autopilot: whether new posts get pins by themselves, which posts get a fresh pin every week ("Posts you pick"), the pace, whether pins wait for review or go out automatically, and when the next pins come. Use it when the user asks what is running on autopilot.
Try: “What is Auto Pin doing for me?”
Parameters (1)
| Name | Type | Description |
| workspace |
string |
Only this workspace (name or site). Leave out to see all. |
keep_posts_fresh
Creates
In-chat screen
Puts posts on autopilot: each post gets a brand-new pin (new headline, design and photo) every week, or at the pace chosen, scheduled weeks ahead and topped up by Auto Pin by itself. Template pins from the post's own photos; no credits. Use it when the user says "make new pins every week for these" or "keep these posts fresh". First call without confirm and show the user the plan; only after they agree call again with confirm true. Needs Auto Pin set up once in the app; if it is not, pass on the setup link.
Try: “Make new pins every week for my Peru posts”
Parameters (4)
| Name | Type | Description |
| urlsrequired |
string[] |
The post links to keep fresh (up to 25). find_my_posts lists the user's posts. |
| every_days |
integer |
How often each post gets a new pin: 7 (weekly, the usual), 3, 14 or 28. It applies to all picked posts of that site. Leave out to keep the current pace. |
| confirm |
boolean |
True only after the user agreed to the plan. |
| workspace |
string |
Which workspace (name or site), when the user has several. |
change_posts_fresh
Changes or removes
Changes the posts on autopilot (Auto Pin's Posts you pick): pause or resume the weekly fresh pins, take some posts off, or take all off. Pins already scheduled still go out and nothing is deleted. Check with the user before remove_all.
Try: “Pause the weekly pins for my Peru posts”
Parameters (4)
| Name | Type | Description |
| actionrequired |
string |
pause / resume the weekly pins, remove some posts (give urls), or remove_all.one of: pause, resume, remove, remove_all |
| urls |
string[] |
For remove: the post links to take off. |
| site |
string |
Which site's Auto Pin, when the workspace has several (for pause, resume, remove_all). |
| workspace |
string |
Which workspace (name or site), when the user has several. |
check_pinterest_profile
Read-only
Checks the user's connected Pinterest account with the Profile Checker and gives the top things to fix first (profile, links, pin shapes, timing…), each with what to do, plus a link to the full report. If no recent check exists, one starts in the background; call again in a few minutes.
Try: “What should I fix on my Pinterest profile?”
Parameters (1)
| Name | Type | Description |
| workspace |
string |
Which workspace (name or site), when the user has several Pinterest accounts. |
get_pin_stats
Read-only
Pinterest results for the user's account: totals (views, saves, pin clicks, visits to their site) compared with the period before, the top pins and the top posts by the chosen number. Use it for "which pins got the most clicks this month?", "how is Pinterest doing?" or "which posts get the most visits?".
Try: “Which of my pins did best this month?”
Parameters (3)
| Name | Type | Description |
| days |
integer |
The period: 7, 30 (the usual, "this month") or 90 days.one of: 7, 30, 90 |
| sort_by |
string |
What to rank pins and posts by: outbound_clicks (visits to the site, the usual), saves, impressions or pin_clicks.one of: outbound_clicks, saves, impressions, pin_clicks |
| workspace |
string |
Which workspace (name or site), when the user has several Pinterest accounts. |
get_started
Read-only
Explains what Made to Spark can do for this user, what is set up on their account (workspaces, Pinterest, scheduling, credits), and example requests to try. Call it when the user asks what Made to Spark can do, how to use it, or on their first request if they seem unsure.
Try: “What can Made to Spark do for me?”
No parameters.