{"openapi":"3.1.0","info":{"title":"Pinterest (BYOK) API","version":"0.1.0","description":"Pinterest (BYOK) lets an AI assistant read your own Pinterest data through the Pinterest API with a key you supply (Pinterest access token (trial or standard access)). Read-only: 11 tools (get_user_account, list_boards, get_board, list_board_sections, list_board_pins, list_pins, get_pin, search_my_pins, get_account_analytics, get_top_pins_analytics, list_trending_keywords). The BYOK key travels...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-pinterest.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-pinterest/docs"},"termsOfService":"https://connectorbay.com/byok-pinterest/terms"},"servers":[{"url":"https://byok-pinterest.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-pinterest/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_user_account":{"post":{"operationId":"get_user_account","summary":"Show the Pinterest account the token belongs to: username, account type, about text, website and counters for boards, Pi","description":"Show the Pinterest account the token belongs to: username, account type, about text, website and counters for boards, Pins, followers, following and monthly views. Use for \"How many Pins, boards and followers does my Pinterest account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_user_accountArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_boards":{"post":{"operationId":"list_boards","summary":"List the boards you own plus group boards you collaborate on, with privacy, Pin and follower counts and dates. Needs the","description":"List the boards you own plus group boards you collaborate on, with privacy, Pin and follower counts and dates. Needs the boards:read scope. Use for \"What Pinterest boards do I have and how many Pins are on each\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"privacy":{"anyOf":[{"enum":["ALL","PUBLIC","PROTECTED","SECRET","PUBLIC_AND_SECRET"],"type":"string"},{"type":"null"}],"default":null,"description":"Only boards with this privacy: ALL, PUBLIC, PROTECTED, SECRET or PUBLIC_AND_SECRET.","title":"Privacy"},"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items per page (1 to 250).","title":"Page Size"},"bookmark":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's 'bookmark' field to fetch the next page.","title":"Bookmark"}},"title":"list_boardsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_board":{"post":{"operationId":"get_board","summary":"Get one board: name, description, privacy, Pin, follower and collaborator counts and dates. Use for \"How many Pins are o","description":"Get one board: name, description, privacy, Pin, follower and collaborator counts and dates. Use for \"How many Pins are on my Pinterest board 549755885175\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"board_id":{"description":"Pinterest board id (digits), from list_boards.","maxLength":200,"title":"Board Id","type":"string"}},"required":["board_id"],"title":"get_boardArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_board_sections":{"post":{"operationId":"list_board_sections","summary":"List the sections of a board with their names and ids. Use for \"What sections does my Pinterest board 549755885175 have\"","description":"List the sections of a board with their names and ids. Use for \"What sections does my Pinterest board 549755885175 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"board_id":{"description":"Pinterest board id (digits), from list_boards.","maxLength":200,"title":"Board Id","type":"string"},"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items per page (1 to 250).","title":"Page Size"},"bookmark":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's 'bookmark' field to fetch the next page.","title":"Bookmark"}},"required":["board_id"],"title":"list_board_sectionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_board_pins":{"post":{"operationId":"list_board_pins","summary":"List the Pins on a board with title, description, link, creation date and the 600px image URL. Needs the pins:read scope","description":"List the Pins on a board with title, description, link, creation date and the 600px image URL. Needs the pins:read scope. Use for \"Which Pins are on my Pinterest board 549755885175\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"board_id":{"description":"Pinterest board id (digits), from list_boards.","maxLength":200,"title":"Board Id","type":"string"},"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items per page (1 to 250).","title":"Page Size"},"bookmark":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's 'bookmark' field to fetch the next page.","title":"Bookmark"}},"required":["board_id"],"title":"list_board_pinsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_pins":{"post":{"operationId":"list_pins","summary":"List the Pins you own, newest first, with title, description, link, board and the 600px image URL. Can filter out repins","description":"List the Pins you own, newest first, with title, description, link, board and the 600px image URL. Can filter out repins or native Pins. Use for \"What Pins did I create on Pinterest recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"pin_filter":{"anyOf":[{"enum":["exclude_native","exclude_repins","has_been_promoted"],"type":"string"},{"type":"null"}],"default":null,"description":"Optional filter: exclude_native, exclude_repins or has_been_promoted.","title":"Pin Filter"},"domain":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only Pins whose link is on exactly this domain, without 'www.', for example 'example.com'.","title":"Domain"},"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items per page (1 to 250).","title":"Page Size"},"bookmark":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's 'bookmark' field to fetch the next page.","title":"Bookmark"}},"title":"list_pinsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_pin":{"post":{"operationId":"get_pin","summary":"Get one Pin: title, description, link, board, creation date and image URL. Use for \"What is the Pinterest Pin 8137442264","description":"Get one Pin: title, description, link, board, creation date and image URL. Use for \"What is the Pinterest Pin 813744226420795884 about\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"pin_id":{"description":"Pinterest Pin id (digits), from list_pins or list_board_pins.","maxLength":200,"title":"Pin Id","type":"string"}},"required":["pin_id"],"title":"get_pinArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_my_pins":{"post":{"operationId":"search_my_pins","summary":"Search your own Pins by description keywords (or a comma-separated list of Pin ids). Use for \"Find my Pinterest Pins abo","description":"Search your own Pins by description keywords (or a comma-separated list of Pin ids). Use for \"Find my Pinterest Pins about salad\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search text matched against Pin descriptions, or comma-separated Pin ids.","maxLength":200,"title":"Query","type":"string"},"bookmark":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's 'bookmark' field to fetch the next page.","title":"Bookmark"}},"required":["query"],"title":"search_my_pinsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_account_analytics":{"post":{"operationId":"get_account_analytics","summary":"Get your account's summary metrics (impressions, saves, Pin clicks, outbound clicks, engagement and rates) for a date ra","description":"Get your account's summary metrics (impressions, saves, Pin clicks, outbound clicks, engagement and rates) for a date range of at most 90 days that starts at most 90 days ago. Needs the user_accounts:read scope. Use for \"How many impressions and saves did my Pinterest account get in September 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First day of the report, UTC, YYYY-MM-DD; not more than 90 days ago.","maxLength":200,"title":"Start Date","type":"string"},"end_date":{"description":"Last day of the report, UTC, YYYY-MM-DD; at most 90 days after start_date.","maxLength":200,"title":"End Date","type":"string"},"content_type":{"anyOf":[{"enum":["ALL","PAID","ORGANIC"],"type":"string"},{"type":"null"}],"default":"ALL","description":"Paid or organic data: ALL, PAID or ORGANIC.","title":"Content Type"},"pin_format":{"anyOf":[{"enum":["ALL","ORGANIC_IMAGE","ORGANIC_PRODUCT","ORGANIC_VIDEO"],"type":"string"},{"type":"null"}],"default":"ALL","description":"Pin format to include.","title":"Pin Format"}},"required":["start_date","end_date"],"title":"get_account_analyticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_top_pins_analytics":{"post":{"operationId":"get_top_pins_analytics","summary":"Get your best-performing Pins (up to 50) for a date range, ranked by engagement, saves, impressions or clicks, with thei","description":"Get your best-performing Pins (up to 50) for a date range, ranked by engagement, saves, impressions or clicks, with their metrics. Use for \"Which of my Pinterest Pins had the most impressions in September 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First day of the report, UTC, YYYY-MM-DD; not more than 90 days ago.","maxLength":200,"title":"Start Date","type":"string"},"end_date":{"description":"Last day of the report, UTC, YYYY-MM-DD; at most 90 days after start_date.","maxLength":200,"title":"End Date","type":"string"},"sort_by":{"description":"Ranking metric: ENGAGEMENT, SAVE, IMPRESSION, OUTBOUND_CLICK or PIN_CLICK.","enum":["ENGAGEMENT","SAVE","IMPRESSION","OUTBOUND_CLICK","PIN_CLICK"],"title":"Sort By","type":"string"},"num_of_pins":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many Pins to return (1 to 50).","title":"Num Of Pins"}},"required":["start_date","end_date","sort_by"],"title":"get_top_pins_analyticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_trending_keywords":{"post":{"operationId":"list_trending_keywords","summary":"List the top trending Pinterest search keywords for a country, ranked by one of four trend types, with week, month and y","description":"List the top trending Pinterest search keywords for a country, ranked by one of four trend types, with week, month and year growth percentages. Not specific to your account. Use for \"What are the fastest growing Pinterest search keywords in the US\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Region code: US, CA, DE, FR, ES, IT, AR, BR, CO or MX.","enum":["US","CA","DE","FR","ES","IT","AR","BR","CO","MX"],"title":"Region","type":"string"},"trend_type":{"description":"How trendiness is ranked: growing, monthly, yearly or seasonal.","enum":["growing","monthly","yearly","seasonal"],"title":"Trend Type","type":"string"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many keywords to return (1 to 50).","title":"Limit"}},"required":["region","trend_type"],"title":"list_trending_keywordsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}