{ "openapi": "3.1.0", "info": { "title": "PinData API — Pinterest Visual Discovery, Dominant Hex Palettes & Boutique Stays API", "version": "1.0.0", "summary": "Real-time Pinterest Pins, Creator Boards, Dominant Hex Color Swatches & Airbnb Boutique Stays REST + MCP API — Zero Pinterest OAuth App Review Waiting.", "description": "PinData API (`https://api.pindataapi.com`) delivers normalized JSON for Pinterest visual search, single-pin shop-the-look metadata, 5-swatch dominant hex color palettes, creator moodboards, verified merchant profiles, and short-term boutique stay pricing & availability — with zero OAuth approval queue. Instant `pn_live_` API key on signup with 12,000 free credits ($1.20) + up to $2.00 Sandbox Streak bonus.", "contact": { "name": "PinData API Engineering", "url": "https://pindataapi.com", "email": "support@pindataapi.com" }, "license": { "name": "Commercial Terms of Service", "url": "https://pindataapi.com/terms" } }, "servers": [ { "url": "https://api.pindataapi.com", "description": "Production Global Edge & Multi-Rail Visual Gateway" } ], "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "tags": [ { "name": "Pinterest Visual Pins & Palette", "description": "Search Pinterest pins with aspect ratios, 5-swatch dominant hex palettes, save velocity, and shop-the-look outbound links." }, { "name": "Creator Boards & Profiles", "description": "Search curated Pinterest moodboards and inspect creator or verified merchant profiles." }, { "name": "Airbnb Boutique Stays & Markets", "description": "Search boutique short-term stays, nightly USD pricing, Superhost ratings, and global rental market benchmarks." }, { "name": "System & Telemetry", "description": "Zero-cost gateway health and 7-day rolling SLA latency telemetry." } ], "paths": { "/v1/pins/search": { "get": { "operationId": "searchPins", "tags": [ "Pinterest Visual Pins & Palette" ], "summary": "Search Pinterest pins with 5-swatch hex palettes & shop-the-look domains", "description": "Searches real-time Pinterest pins by aesthetic or product keyword. Returns HD image URLs, exact pixel dimensions & aspect ratio (`2:3`, `3:4`), extracted dominant hex color + 5-swatch palette, save velocity, creator metadata, and outbound e-commerce merchant domain. **Cost:** 2 Credits / pin returned (min 4 Credits; 0 Credits if empty).", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Visual aesthetic, interior style, or product keyword (also accepts alias `q` or `keyword`).", "schema": { "type": "string", "example": "ceramic mug" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum pins to return per page (1–50, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination bookmark cursor from `data.next_cursor`.", "schema": { "type": "string" } }, { "name": "color", "in": "query", "required": false, "description": "Optional 6-digit hex color filter (e.g. `#C9B096` or `C9B096`).", "schema": { "type": "string", "example": "#C9B096" } } ], "responses": { "200": { "description": "Normalized Pinterest visual pins & dominant palette summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinsSearchResponse" }, "example": { "code": 0, "provider": "https://pindataapi.com", "status": "ok", "msg": "success", "data": { "query": "ceramic mug", "count": 2, "next_cursor": "Y2JVSG81V2sxcmNHRlpWM1J5VFVad1YxWllhRlJXTVVZMldWVlZOV0pIUlhsa00zQlhVbXhhVkZWWGMzaGphemxXVm14U1dGTkZTbEZXYlhSWFkyMVdWMVZzYkdwU2JIQlFWV3hvVTJWV1pISlhhM1JYVm10V05sVldVbE5XVlRGWFUyNUdZVlpXVlRGVmJGcEhWbFpPY2s5WGJGZGlSbXQ0Vm10amVHUXhWbkpPVmxwUFZtMW9WMVpyV21GVlJuQllUVlpPYW1KR1JqUldWM1JMWVRBeFdWRnNXbFpXYldnelYxWmtSMk50UmpaUmJHaFhUVEJLZUZkclVrSk5SMVpYVjJ4c2FGSlViSE5aYkZVd1pXeGFSVkZzVGxkTmEzQlhWRlpTWVdGRk1IbGhSVGxYWVRGd2FGcEZXbE5qTVhCSFdrZHNVMVpGVlhsV01uUnJUVVpTYzFOWWFGTlhSMUpXVm14a1UxSXhVbk5YYm1SWFZtdGFNRmxWWkVkVk1VbDNUVlJXVjFKc1duWlVhMXBTWlVaT2MxcEhSbE5TTWswMVdtdGFWMU5YU2paVmJYaFRWMGRvUmxkc1ZsZGhNV1J6VjFod2FGSkdjRmxaYTJSdVpXeHdWbFpVUms5aVJUVmFWMnRWTVZVeFNsWldhbFpYVWtWS1ZGVXlNVmRqYXpWWFZteFNWMUpZUWxCWGJHUTBWbXN4UjFSWWJHdFNNMUpYV1d0YVMxSldhM2RWYlRsV1VtdHNNMVpzYUhkV1YwWnlZMFZrVlZaRlducFViWGhIVjFad1JrOVdaRk5XTTFFd1ZtdGplR1F4V1hsU2JrNXBVMFZhVTFZd1pHOVZSbkJZWkVWMGFsSnNTbFpWTW5Rd1lWWktWV0pGYkZkU2VrWXpWa1JLUjJSR2JEWlJiR2hwVWpGS1NWZFdXbUZrTVdSSFUyNVNhVkp1UW05WldIQlhUVVpaZUZWcmRGWmlWbHA1VkZab1IxVnNXa2RYYlVaWFlXdEtNMWt3V210WFJURldaRWRzVTJKWWFGcFdiRnBUVkRGc1dGSnVTbWhOTWxKV1ZteGtVMWRHYkhOV1ZFWlBZa2hCTWxWdGN6RmhWMHAwWVVaR1YxWXphR2haVkVFMVVXeENWVTFVYUU1V1IwNDFWRlZTUW1Rd05YRmFNMnhPWld4V05WUnRjRTVOVlRsRVkwVm9WbFpZWkhoYWExSkdaV3N4V0ZWWVpGcFdSMUp2VjFod1NrNUZOVlZSVkVKYVZrWldORlJZY0dwbFZuQkZWMjB4VUZKR2NIRlVWbVJXWldzeFdGZFVTazlpVldzd1YxaHdXbVZzY0VWU1ZFcFFWa2Q0YjFSVlpFWk9WbkIwVTFob1QyRnRVbkpVVmxKQ1RrWnNjV0pIYkU5V1JrWTFWMnhTVDA5R1VuSldiR2h0VVZRd09XWkVSVE5OYWtGM1RVUlpORTFxVFRGTmFsbDZUbFJuY1ZJeFJrMUxibmhyV2xkS2FFMTZXVE5hVjAwd1dsUlNhazFYUlRKWmFtc3hUMFJTYkU1SFdUQmFWR2N4V2xkTk1VNHlWbXRQUkdzeVQxZFpNazVYUlhkWlZFRjZUWHBuZWsxVVpHdE9hbFpzV2tkT2FscFVUbTFaYlZKb1prVTFSbFl6ZHowPXxVSG80ZGxveWFESlVSelUxWlVkMFdWSlVNV1pOYWtKbVRGUkdPRTFVWTNsTlJFRjNUbXBuZVUxNlZYbE9hazB4VDBOd1NGVlZkM0ZtUjFFeFRrZFZNMWxYUlRGWmVsazBXV3BaTlU1RVRtMVpWRWt3VGxSQ2FscEVWWHBaYWtab1RtcFZkMDE2UVRWTk1razBUMGRaTUUxVWJHeE5hbFY0V2tSa2FWcHFRbXROUkdzMVdrUkJOVTlIVlRWTlIwbzRWR3RXV0daQlBUMD18Tm9uZXwxNzIwMDA2ODIzNTI2MzU4KkdRTCp8YmZkMjJiN2Y1Yzk1NmY3NGZhYjZjYzk1YzBmNWJhYjlkYzNiNmZlYzE0ZDgwYzk1YzI5YTNiODI2YmNjNjYxMXxORVd8", "dominant_palette_summary": [ "#C9B096", "#D0CDC1", "#C5C4C4", "#B2B2B0" ], "pins": [ { "pin_id": "e1_AfqPShwhDXqkIA5FsIxyvJT-zZSIZUd-KpOe2rI_meOHpzVVwnCd", "numeric_id": null, "title": "LEMON COFFEE MUG", "description": "Elevate your coffee or tea experience with the Casa Amarosa Lemon Coffee Mug. Made from high-quality stoneware, this mug is sleek and durableperfect for any modern home or office. The wide opening and ergonomic handle make it easy and comfortable to use. Material: Stoneware Size: 3.5 Inch x 3 Inch Capacity: 250 ml Color: Yellow Handmade by artisans. Perfect cup for coffee and tea.", "alt_text": "a blue and white coffee cup with an orange design on the inside, sitting on a table", "dominant_color": "#C9B096", "palette_hex": [ "#C9B096", "#FFFFFF", "#EAEAEB", "#EAEAEC", "#3A7FC2" ], "image_url": "https://i.pinimg.com/originals/69/ba/88/69ba885b9ab40879c14b8979873039c1.jpg", "thumbnail_url": "https://i.pinimg.com/236x/69/ba/88/69ba885b9ab40879c14b8979873039c1.jpg", "width": 1080, "height": 1620, "aspect_ratio": "2:3", "saves_count": 1, "comments_count": 0, "reactions_count": 1, "is_shoppable": true, "price_value": null, "price_currency": null, "merchant_domain": "garmentory.com", "outbound_url": "https://garmentory.com/sale/casa-amarosa/drinkware-coffee-tea/2651956-casa-amarosa-lemon-coffee-mug", "pin_url": "https://www.pinterest.com/pin/e1_AfqPShwhDXqkIA5FsIxyvJT-zZSIZUd-KpOe2rI_meOHpzVVwnCd/", "creator": { "username": "preview_garmentory_com", "full_name": "Pinterest Preview Garmentory", "followers": 327, "verified_merchant": false, "avatar_url": "https://s.pinimg.com/images/user/default_140.png" }, "board": { "board_id": "872783671476146896", "name": "Coffee & Tea Cups", "url": "https://www.pinterest.com/preview_garmentory_com/_products_coffee-tea-cups/", "pin_count": 2707 }, "created_at": "Wed, 01 Oct 2025 22:22:19 +0000", "search_query": "ceramic mug" }, { "pin_id": "e1_AfqPShzMmtz4EFK2Zr9GN_fmBkt2Sqs9QZqNR-ydvNKMsuvZqqj7", "numeric_id": null, "title": "Whimsical Frog Mug, Handmade Ceramic Art Cup, Collectible Frog Sculpture, Funny Animal Coffee Mug, Unique Gift for Frog Lovers, Pottery Art - Etsy", "description": "Whimsical Ceramic Art Mug – Handmade Frog Cup – Collectible Pottery Sculpture – Funny Animal Coffee Mug - Etsy", "alt_text": "a ceramic mug with eyes and legs sitting next to coffee beans", "dominant_color": "#D0CDC1", "palette_hex": [ "#D0CDC1", "#E5DFD3", "#F6F0E5", "#755E57", "#817C72" ], "image_url": "https://i.pinimg.com/originals/57/77/d6/5777d6b70b2c473b8c420eefef932d04.webp", "thumbnail_url": "https://i.pinimg.com/236x/57/77/d6/5777d6b70b2c473b8c420eefef932d04.jpg", "width": 1024, "height": 1536, "aspect_ratio": "2:3", "saves_count": 18, "comments_count": 0, "reactions_count": 18, "is_shoppable": true, "price_value": null, "price_currency": null, "merchant_domain": "etsy.com", "outbound_url": "https://www.etsy.com/listing/4313873589/whimsical-ceramic-art-mug-handmade-frog?ref=share_ios_native_control", "pin_url": "https://www.pinterest.com/pin/e1_AfqPShzMmtz4EFK2Zr9GN_fmBkt2Sqs9QZqNR-ydvNKMsuvZqqj7/", "creator": { "username": "cbsoules", "full_name": "Carol Soules", "followers": 174, "verified_merchant": false, "avatar_url": "https://i.pinimg.com/140x140_RS/3b/e3/69/3be3690ce7424bdcc04b4c104aa0dff5.jpg" }, "board": { "board_id": "218213613134357670", "name": "Hand built pottery ideas", "url": "https://www.pinterest.com/cbsoules/hand-built-pottery-ideas/", "pin_count": 248 }, "created_at": "Fri, 06 Mar 2026 04:05:59 +0000", "search_query": "ceramic mug" } ] }, "meta": { "request_id": "11d407c7-a85d-499e-b37a-5b8d34ff5841", "endpoint": "/v1/pins/search", "credits_charged": 4, "cached": true, "took_ms": 1 } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/InsufficientCreditsError" }, "429": { "$ref": "#/components/responses/RateLimitedError" } } } }, "/v1/pins/details": { "get": { "operationId": "getPinDetails", "tags": [ "Pinterest Visual Pins & Palette" ], "summary": "Inspect single Pinterest pin metadata, color swatches & outbound product URL", "description": "Fetches full normalized metadata for a single Pinterest pin by numeric `pin_id`, Pin token, or full `https://www.pinterest.com/pin/{id}/` URL. **Cost:** 5 Credits (0 Credits if not found).", "parameters": [ { "name": "pin_id", "in": "query", "required": true, "description": "Pinterest Pin ID, token, or full Pinterest Pin URL (also accepts `id` or `url`).", "schema": { "type": "string", "example": "e1_AfqPShwhDXqkIA5FsIxyvJT-zZSIZUd-KpOe2rI_meOHpzVVwnCd" } } ], "responses": { "200": { "description": "Normalized single Pinterest pin object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinDetailsResponse" }, "example": { "code": 0, "provider": "https://pindataapi.com", "status": "ok", "msg": "success", "data": { "pin": { "board": { "url": "https://www.pinterest.com/preview_garmentory_com/_products_coffee-tea-cups/", "name": "Coffee & Tea Cups", "board_id": "872783671476146896", "pin_count": 2707 }, "title": "LEMON COFFEE MUG", "width": 1080, "height": 1620, "pin_id": "e1_AfqPShwhDXqkIA5FsIxyvJT-zZSIZUd-KpOe2rI_meOHpzVVwnCd", "creator": { "username": "preview_garmentory_com", "followers": 327, "full_name": "Pinterest Preview Garmentory", "avatar_url": "https://s.pinimg.com/images/user/default_140.png", "verified_merchant": false }, "pin_url": "https://www.pinterest.com/pin/e1_AfqPShwhDXqkIA5FsIxyvJT-zZSIZUd-KpOe2rI_meOHpzVVwnCd/", "alt_text": "a blue and white coffee cup with an orange design on the inside, sitting on a table", "image_url": "https://i.pinimg.com/originals/69/ba/88/69ba885b9ab40879c14b8979873039c1.jpg", "created_at": "Wed, 01 Oct 2025 22:22:19 +0000", "numeric_id": null, "description": "Elevate your coffee or tea experience with the Casa Amarosa Lemon Coffee Mug. Made from high-quality stoneware, this mug is sleek and durableperfect for any modern home or office. The wide opening and ergonomic handle make it easy and comfortable to use. Material: Stoneware Size: 3.5 Inch x 3 Inch Capacity: 250 ml Color: Yellow Handmade by artisans. Perfect cup for coffee and tea.", "palette_hex": [ "#C9B096", "#FFFFFF", "#EAEAEB", "#EAEAEC", "#3A7FC2" ], "price_value": null, "saves_count": 1, "aspect_ratio": "2:3", "is_shoppable": true, "outbound_url": "https://garmentory.com/sale/casa-amarosa/drinkware-coffee-tea/2651956-casa-amarosa-lemon-coffee-mug", "search_query": "ceramic mug", "thumbnail_url": "https://i.pinimg.com/236x/69/ba/88/69ba885b9ab40879c14b8979873039c1.jpg", "comments_count": 0, "dominant_color": "#C9B096", "price_currency": null, "merchant_domain": "garmentory.com", "reactions_count": 1 } }, "meta": { "request_id": "dfebd84b-2cc9-4d5b-a817-7750c16134e0", "endpoint": "/v1/pins/details", "credits_charged": 5, "cached": true, "took_ms": 3 } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/boards/search": { "get": { "operationId": "searchBoards", "tags": [ "Creator Boards & Profiles" ], "summary": "Search curated Pinterest moodboards & aesthetic collections", "description": "Searches public Pinterest boards by aesthetic, interior design movement, fashion season, or brand topic. Returns cover & collage preview URLs, pin counts, palette swatches, and owner metadata. **Cost:** 2 Credits / board returned (min 4 Credits; 0 Credits if empty).", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Moodboard or collection keyword (also accepts `q`).", "schema": { "type": "string", "example": "mid century interior" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum boards to return (1–50, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from `data.next_cursor`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Normalized Pinterest moodboard list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardsSearchResponse" }, "example": { "code": 0, "provider": "https://pindataapi.com", "status": "ok", "msg": "success", "data": { "query": "mid century interior", "count": 2, "next_cursor": "b281MHwxNTgwNjgzODE4ODk1MjEwKkdRTCp8ZmM4ZWM5YjM2MDg4NzNkZWMzY2E0ZjQwZmQ1MTFiY2IwZjMxYmYyMmFiZGFjNjBkN2U5MjAyM2YzYjBlYTMxN3xORVd8", "boards": [ { "board_id": "237916861503727168", "name": "Mid Century Interiors", "description": null, "url": "https://www.pinterest.com/jared1964/mid-century-interiors/", "pin_count": 1018, "follower_count": 0, "section_count": 0, "collaborator_count": 0, "is_collaborative": false, "cover_image_url": "https://i.pinimg.com/474x/91/23/ac/9123ac9493190e09e40ff8b9f254cc42.jpg", "sample_thumbnails": [ "https://i.pinimg.com/150x150/e2/c3/1d/e2c31dcb7c7fbf45cc907c9023c06428.jpg", "https://i.pinimg.com/150x150/8c/6d/b6/8c6db6db1efe5ee410a3135ec6f04e72.jpg", "https://i.pinimg.com/150x150/08/bc/fc/08bcfc4678e5b9347320d1a979779cf4.jpg", "https://i.pinimg.com/150x150/bc/85/0a/bc850a6058d655e3805db0001ab44d7e.jpg", "https://i.pinimg.com/150x150/5d/73/ef/5d73ef72f766a6a311348385e3c03ffe.jpg" ], "palette_hex": [ "#D4A373", "#F0B985", "#B2875B", "#C6BB93" ], "owner": { "username": "jared1964", "full_name": "Jared Neisler", "verified_merchant": false, "avatar_url": "https://i.pinimg.com/75x75_RS/4a/f4/b4/4af4b4877372e2decf36de5bcee7f4a4.jpg" }, "updated_at": "Thu, 12 Nov 2026 04:14:31 +0000", "search_query": "mid century interior" }, { "board_id": "161496405327035782", "name": "Mid-Century Interior Design", "description": "Mid Century modern kitchens, living rooms, and interiors.", "url": "https://www.pinterest.com/light_factory/mid-century-interior-design/", "pin_count": 348, "follower_count": 0, "section_count": 0, "collaborator_count": 0, "is_collaborative": false, "cover_image_url": "https://i.pinimg.com/474x/67/65/f0/6765f0af9a4c1856f62f4eab1124875e.jpg", "sample_thumbnails": [ "https://i.pinimg.com/150x150/f6/b4/79/f6b47935ee1d10089ebfe987e95728ae.jpg", "https://i.pinimg.com/150x150/56/6b/ed/566bed70afa0e6bb63213f668df47e7e.jpg", "https://i.pinimg.com/150x150/69/2b/02/692b02557edc3708e4c41282a1477d0a.jpg", "https://i.pinimg.com/150x150/3c/9b/92/3c9b92431947181f9736423ee6da6d3e.jpg", "https://i.pinimg.com/150x150/f0/56/1d/f0561d9a6db5b42accfd25592dfbab80.jpg" ], "palette_hex": [ "#D4A373", "#F0B985", "#B2875B", "#C6BB93" ], "owner": { "username": "light_factory", "full_name": "The Light Factory | Bubble Chandelier Lighting & Light Fixtures", "verified_merchant": true, "avatar_url": "https://i.pinimg.com/75x75_RS/80/86/4d/80864d8da01504939c50c028155140c8.jpg" }, "updated_at": "Thu, 12 Nov 2026 05:39:57 +0000", "search_query": "mid century interior" } ] }, "meta": { "request_id": "5af799fe-5840-4fd7-97f9-05055597e028", "endpoint": "/v1/boards/search", "credits_charged": 4, "cached": false, "took_ms": 1916 } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/v1/users/profile": { "get": { "operationId": "getUserProfile", "tags": [ "Creator Boards & Profiles" ], "summary": "Inspect Pinterest creator or verified merchant profile", "description": "Returns follower count, verified merchant status, website URL, signature 5-swatch color palette, and sample pins for any public Pinterest creator or brand handle. **Cost:** 10 Credits (0 Credits if not found).", "parameters": [ { "name": "username", "in": "query", "required": true, "description": "Pinterest handle (without `@`) or full profile URL.", "schema": { "type": "string", "example": "archdigest" } } ], "responses": { "200": { "description": "Normalized Pinterest creator / merchant profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponse" }, "example": { "code": 0, "provider": "https://pindataapi.com", "status": "ok", "msg": "success", "data": { "profile": { "username": "archdigest", "user_id": "VXNlcjoyNTYyODMxNzI0NTM0ODM1ODI=", "full_name": "Architectural Digest", "bio": null, "website_url": null, "avatar_url": null, "verified_merchant": false, "follower_count": 3729260, "following_count": null, "pin_count": 25, "board_count": null, "monthly_views": null, "dominant_palette": [ "#867F73", "#8F8D27", "#54493C", "#756036", "#8E7242" ], "sample_pins": [ { "pin_id": "256283035040940616", "title": "Nickey Kehoe’s New Collection With The Lacquer Company Takes Its Cues From Beloved Antiques", "image_url": "https://i.pinimg.com/736x/f4/fc/08/f4fc0819ea766aeb00841b05ce4650e3.jpg", "width": 736, "height": 1104, "dominant_color": "#867F73", "saves_count": 1 }, { "pin_id": "256283035040940256", "title": "Bunny Williams Never Set Out to Collect Birdhouses—Now a Village of Them Stands in Her Garden", "image_url": "https://i.pinimg.com/736x/1f/9e/de/1f9ede22857acf96733ab7ec6d58399a.jpg", "width": 736, "height": 1104, "dominant_color": "#8F8D27", "saves_count": 0 }, { "pin_id": "256283035040940067", "title": "How One Designer Brought a Discerning Eye to Her Deeply Personal Manhattan Apartment", "image_url": "https://i.pinimg.com/736x/a2/ca/1b/a2ca1bbf02a89ba4165fe0ee65d87ac8.jpg", "width": 736, "height": 1104, "dominant_color": "#54493C", "saves_count": 0 }, { "pin_id": "256283035040938062", "title": "How One Creative Couple Found Harmony in Their 1920s Los Angeles Craftsman", "image_url": "https://i.pinimg.com/736x/f7/9b/a9/f79ba990f134d5581068d93b2cf1d136.jpg", "width": 736, "height": 1104, "dominant_color": "#756036", "saves_count": 0 }, { "pin_id": "256283035040937808", "title": "Artists Helen Marden and the Late Brice Marden Refashioned a Decommissioned Ferry Terminal", "image_url": "https://i.pinimg.com/736x/44/84/c9/4484c9803f8c4855dbd3f90905bca93c.jpg", "width": 736, "height": 1104, "dominant_color": "#8E7242", "saves_count": 0 }, { "pin_id": "256283035040935240", "title": "Joseph Dirand Joins with Peter Brant and Stephanie Seymour Brant to Reimagine a Historic Mansion", "image_url": "https://i.pinimg.com/736x/a6/02/b5/a602b53b79a93749d2bf978d806ae358.jpg", "width": 736, "height": 1104, "dominant_color": "#BEA87B", "saves_count": 0 }, { "pin_id": "256283035040933508", "title": "How a Society Photographer Fell in Love With an Unexpected Upstate Victorian Home", "image_url": "https://i.pinimg.com/736x/f3/9d/82/f39d82b3386280077e979f879601989d.jpg", "width": 736, "height": 1104, "dominant_color": "#292C39", "saves_count": 1 }, { "pin_id": "256283035040933098", "title": "The 17 Most Beautiful Ski Resorts to Visit This Winter—Including Three in the US", "image_url": "https://i.pinimg.com/736x/2e/09/ff/2e09ff8ec187bcfc4fbe8d96683e0d4f.jpg", "width": 736, "height": 1104, "dominant_color": "#0F7A87", "saves_count": 0 } ], "profile_url": "https://www.pinterest.com/archdigest/" } }, "meta": { "request_id": "33e9445b-b7d5-440d-9b40-a1d9d9921b50", "endpoint": "/v1/users/profile", "credits_charged": 10, "cached": false, "took_ms": 2374 } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/stays/search": { "get": { "operationId": "searchBoutiqueStays", "tags": [ "Airbnb Boutique Stays & Markets" ], "summary": "Search boutique short-term stays with nightly USD rates, Superhost badges & HD photos", "description": "Searches short-term rental & boutique stay listings by city/destination and optional check-in/out dates. Returns nightly & total USD pricing, Superhost status, guest rating, review count, coordinates, interior photo gallery, and aesthetic color swatches. **Cost:** 5 Credits / stay returned (min 10 Credits; 0 Credits if empty).", "parameters": [ { "name": "location", "in": "query", "required": true, "description": "Destination city, neighborhood, or region (also accepts `query` or `city`).", "schema": { "type": "string", "example": "Paris" } }, { "name": "checkin", "in": "query", "required": false, "description": "Check-in date `YYYY-MM-DD` (defaults to +30 days if omitted).", "schema": { "type": "string", "example": "2026-12-10" } }, { "name": "checkout", "in": "query", "required": false, "description": "Check-out date `YYYY-MM-DD` (defaults to +33 days if omitted).", "schema": { "type": "string", "example": "2026-12-13" } }, { "name": "adults", "in": "query", "required": false, "description": "Number of adult guests (1–16, default 2).", "schema": { "type": "integer", "minimum": 1, "maximum": 16, "default": 2 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO-4217 currency code (default `USD`).", "schema": { "type": "string", "default": "USD" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum listings to return (1–40, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 40, "default": 20 } } ], "responses": { "200": { "description": "Normalized boutique stay search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaysSearchResponse" }, "example": { "code": 0, "provider": "https://pindataapi.com", "status": "ok", "msg": "success", "data": { "location": "Paris", "checkin": "2026-12-14", "checkout": "2026-12-17", "adults": 2, "currency": "USD", "count": 2, "stays": [ { "stay_id": "41507144", "name": "Cosy studio near Eiffel Tower", "property_type": "Apartment", "room_type": "Entire home/apt", "city": "Paris", "neighborhood": null, "market": "Paris", "country_code": null, "lat": 48.8473, "lng": 2.2951, "nightly_rate_usd": 510, "total_price_usd": 509.44, "currency": "USD", "rating": 4.84, "reviews_count": 473, "is_superhost": false, "rare_find": true, "max_guests": null, "bedrooms": 0, "beds": 1, "bathrooms": 1, "min_nights": null, "cancel_policy": null, "images": [ "https://a0.muscache.com/im/pictures/ddae76b6-26ec-4652-be2d-9f6b97aa536d.jpg", "https://a0.muscache.com/im/pictures/c7c73a1e-a0e7-4621-bb85-3bcf7bb2f047.jpg", "https://a0.muscache.com/im/pictures/7f4ede03-1b6e-4a45-a189-36825d82fc25.jpg", "https://a0.muscache.com/im/pictures/135d9109-37d8-4f59-b47e-eece7ec95ee8.jpg", "https://a0.muscache.com/im/pictures/b27f47cf-8fdf-4140-8d4e-9887fa97211f.jpg", "https://a0.muscache.com/im/pictures/9b174ce3-4c61-4797-82d5-c652b80ad571.jpg" ], "dominant_color": "#6B705C", "palette_hex": [ "#6B705C", "#CB997E", "#FFE8D6", "#A5A58D" ], "amenities": [], "listing_url": "https://www.airbnb.com/rooms/41507144", "last_updated": "2026-11-14T17:23:40.607Z" }, { "stay_id": "1333842490138337108", "name": "Bed and breakfast near the Jardin des Plantes", "property_type": "Room", "room_type": "Entire home/apt", "city": "Paris", "neighborhood": null, "market": "Paris", "country_code": null, "lat": 48.8442, "lng": 2.3537, "nightly_rate_usd": 333, "total_price_usd": 332.63, "currency": "USD", "rating": 4.8, "reviews_count": 30, "is_superhost": true, "rare_find": false, "max_guests": null, "bedrooms": 0, "beds": 1, "bathrooms": 1, "min_nights": null, "cancel_policy": null, "images": [ "https://a0.muscache.com/im/pictures/hosting/Hosting-1333842490138337108/original/875df1ce-c36c-41ba-9b7d-b23df58d48dc.jpeg", "https://a0.muscache.com/im/pictures/hosting/Hosting-1333842490138337108/original/107a5019-076c-4d77-8363-e3640c9d14f2.jpeg", "https://a0.muscache.com/im/pictures/hosting/Hosting-1333842490138337108/original/009be4a6-a366-47de-bcfd-5815e890b3ee.jpeg", "https://a0.muscache.com/im/pictures/hosting/Hosting-1333842490138337108/original/41efae49-5381-4893-a88b-f15755b12804.jpeg", "https://a0.muscache.com/im/pictures/hosting/Hosting-1333842490138337108/original/3d1940ca-8ddf-44f2-b76d-47b83df18473.jpeg", "https://a0.muscache.com/im/pictures/hosting/Hosting-1333842490138337108/original/9c8fed20-366c-48e8-bdc0-4f2974cc2cae.jpeg" ], "dominant_color": "#B5838D", "palette_hex": [ "#B5838D", "#FFCDB2", "#DDBEA9", "#6D6875" ], "amenities": [], "listing_url": "https://www.airbnb.com/rooms/1333842490138337108", "last_updated": "2026-11-14T17:23:40.607Z" } ] }, "meta": { "request_id": "bf1061f7-3195-4d39-a601-1ebbc6fe12c4", "endpoint": "/v1/stays/search", "credits_charged": 10, "cached": false, "took_ms": 1796 } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/v1/stays/market": { "get": { "operationId": "getStaysMarket", "tags": [ "Airbnb Boutique Stays & Markets" ], "summary": "Fetch short-term rental market supply, average nightly ADR & Superhost share", "description": "Retrieves market-level short-term rental listings and summary metrics (average nightly USD rate, average guest rating, Superhost share) for any global city or destination. **Cost:** 3 Credits / listing returned (min 6 Credits; 0 Credits if empty).", "parameters": [ { "name": "market", "in": "query", "required": true, "description": "City or travel market name (also accepts `location` or `city`).", "schema": { "type": "string", "example": "Paris" } }, { "name": "limit", "in": "query", "required": false, "description": "Listings to return (1–50, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset (default 0).", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Market-level rental summary & listings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaysMarketResponse" }, "example": { "code": 0, "provider": "https://pindataapi.com", "status": "ok", "msg": "success", "data": { "market": "Paris", "count": 2, "market_summary": { "average_rating": null, "superhost_share_pct": 0 }, "listings": [ { "stay_id": "643293547304025326", "name": "Paris Curated Stay #643293547304025326", "property_type": "Boutique Apartment", "room_type": null, "city": "Paris", "neighborhood": null, "market": "Paris", "country_code": null, "lat": null, "lng": null, "nightly_rate_usd": null, "total_price_usd": null, "currency": "USD", "rating": null, "reviews_count": 0, "is_superhost": false, "rare_find": false, "max_guests": null, "bedrooms": null, "beds": null, "bathrooms": null, "min_nights": null, "cancel_policy": null, "images": [], "dominant_color": "#2A9D8F", "palette_hex": [ "#2A9D8F", "#E9C46A", "#264653", "#F4A261" ], "amenities": [], "listing_url": "https://www.airbnb.com/rooms/643293547304025326", "last_updated": "2026-11-01 07:57:06" }, { "stay_id": "54376622", "name": "Paris Curated Stay #54376622", "property_type": "Boutique Apartment", "room_type": null, "city": "Paris", "neighborhood": null, "market": "Paris", "country_code": null, "lat": null, "lng": null, "nightly_rate_usd": null, "total_price_usd": null, "currency": "USD", "rating": null, "reviews_count": 0, "is_superhost": false, "rare_find": false, "max_guests": null, "bedrooms": null, "beds": null, "bathrooms": null, "min_nights": null, "cancel_policy": null, "images": [], "dominant_color": "#E76F51", "palette_hex": [ "#E76F51", "#F4A261", "#E9ECEF", "#4A4E69" ], "amenities": [], "listing_url": "https://www.airbnb.com/rooms/54376622", "last_updated": "2026-10-29 02:46:38" } ] }, "meta": { "request_id": "b4465cd2-d9ab-4807-91e8-24b629615db9", "endpoint": "/v1/stays/market", "credits_charged": 6, "cached": true, "took_ms": 1 } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/v1/stays/destinations": { "get": { "operationId": "searchStayDestinations", "tags": [ "Airbnb Boutique Stays & Markets" ], "summary": "Autocomplete travel destinations, cities & neighborhoods", "description": "Resolves partial city, island, or neighborhood strings into structured destination place IDs, display labels, and ISO country codes. **Cost:** 2 Credits / request.", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Destination prefix or city name (also accepts `q`).", "schema": { "type": "string", "example": "Paris" } } ], "responses": { "200": { "description": "Normalized travel destination predictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaysDestinationsResponse" }, "example": { "code": 0, "provider": "https://pindataapi.com", "status": "ok", "msg": "success", "data": { "query": "Paris", "count": 3, "destinations": [ { "destination_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ", "query_key": "paris", "location_name": "Paris, France", "display_name": "Paris, France", "country_code": "FR", "terms": [ "[object Object]", "[object Object]" ] }, { "destination_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ", "query_key": "paris", "location_name": "Paris, France", "display_name": "Paris, France stays", "country_code": "FR", "terms": [ "[object Object]", "[object Object]" ] }, { "destination_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ", "query_key": "paris", "location_name": "Paris, France", "display_name": "Paris, France experiences", "country_code": "FR", "terms": [ "[object Object]", "[object Object]" ] } ] }, "meta": { "request_id": "8b557174-ff35-4ded-9ede-3e24ef579140", "endpoint": "/v1/stays/destinations", "credits_charged": 2, "cached": true, "took_ms": 0 } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/v1/health": { "get": { "operationId": "getGatewayHealth", "tags": [ "System & Telemetry" ], "summary": "Zero-cost gateway health probe", "security": [], "responses": { "200": { "description": "Gateway healthy (0 Credits).", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": 0, "provider": "https://pindataapi.com", "status": "ok", "msg": "success", "data": { "service": "pindataapi-gateway", "status": "healthy", "engine": "postgresql-16-jsonb-fts + redis-db7-pd + multi-rail-visual-gateway", "timestamp": "2026-11-15T00:00:00.000Z" } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your PinData API key (`pn_live_...`). Claim 12,000 free credits ($1.20) at https://pindataapi.com/signup" }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Pass `Authorization: Bearer pn_live_...` or an OAuth 2.1 access token issued by `https://mcp.pindataapi.com`." } }, "schemas": { "ResponseMeta": { "type": "object", "required": [ "request_id", "endpoint", "credits_charged", "cached", "took_ms" ], "properties": { "request_id": { "type": "string" }, "endpoint": { "type": "string" }, "credits_charged": { "type": "integer" }, "cached": { "type": "boolean" }, "took_ms": { "type": "integer" } } }, "NormalizedPin": { "type": "object", "required": [ "pin_id", "title", "dominant_color", "palette_hex", "image_url", "width", "height", "aspect_ratio", "saves_count", "pin_url" ], "properties": { "pin_id": { "type": "string" }, "numeric_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "alt_text": { "type": [ "string", "null" ] }, "dominant_color": { "type": "string", "example": "#C9B096" }, "palette_hex": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": "string", "format": "uri" }, "thumbnail_url": { "type": [ "string", "null" ] }, "width": { "type": "integer", "example": 1080 }, "height": { "type": "integer", "example": 1620 }, "aspect_ratio": { "type": "string", "example": "2:3" }, "saves_count": { "type": "integer" }, "comments_count": { "type": "integer" }, "reactions_count": { "type": "integer" }, "is_shoppable": { "type": "boolean" }, "merchant_domain": { "type": [ "string", "null" ], "example": "garmentory.com" }, "outbound_url": { "type": [ "string", "null" ] }, "pin_url": { "type": "string", "format": "uri" }, "creator": { "type": "object", "properties": { "username": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "followers": { "type": [ "integer", "null" ] }, "verified_merchant": { "type": "boolean" }, "avatar_url": { "type": [ "string", "null" ] } } }, "board": { "type": "object", "properties": { "board_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "pin_count": { "type": [ "integer", "null" ] } } } } }, "NormalizedBoard": { "type": "object", "required": [ "board_id", "name", "pin_count", "palette_hex" ], "properties": { "board_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "pin_count": { "type": "integer" }, "follower_count": { "type": [ "integer", "null" ] }, "cover_image_url": { "type": [ "string", "null" ] }, "sample_images": { "type": "array", "items": { "type": "string" } }, "dominant_color": { "type": "string" }, "palette_hex": { "type": "array", "items": { "type": "string" } } } }, "NormalizedProfile": { "type": "object", "required": [ "username", "full_name", "follower_count", "dominant_palette", "profile_url" ], "properties": { "username": { "type": "string" }, "user_id": { "type": [ "string", "null" ] }, "full_name": { "type": "string" }, "bio": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "verified_merchant": { "type": "boolean" }, "follower_count": { "type": "integer" }, "pin_count": { "type": [ "integer", "null" ] }, "board_count": { "type": [ "integer", "null" ] }, "dominant_palette": { "type": "array", "items": { "type": "string" } }, "sample_pins": { "type": "array", "items": { "type": "object" } }, "profile_url": { "type": "string" } } }, "NormalizedStay": { "type": "object", "required": [ "stay_id", "name", "city", "currency", "is_superhost", "images", "dominant_color", "palette_hex", "listing_url" ], "properties": { "stay_id": { "type": "string" }, "name": { "type": "string" }, "property_type": { "type": "string" }, "room_type": { "type": "string" }, "city": { "type": "string" }, "nightly_rate_usd": { "type": [ "number", "null" ] }, "total_price_usd": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "rating": { "type": [ "number", "null" ] }, "reviews_count": { "type": "integer" }, "is_superhost": { "type": "boolean" }, "bedrooms": { "type": [ "number", "null" ] }, "beds": { "type": [ "number", "null" ] }, "bathrooms": { "type": [ "number", "null" ] }, "images": { "type": "array", "items": { "type": "string" } }, "dominant_color": { "type": "string" }, "palette_hex": { "type": "array", "items": { "type": "string" } }, "listing_url": { "type": "string" } } }, "PinsSearchResponse": { "type": "object", "required": [ "code", "status", "data", "meta" ], "properties": { "code": { "type": "integer", "example": 0 }, "provider": { "type": "string", "example": "https://pindataapi.com" }, "status": { "type": "string", "example": "ok" }, "msg": { "type": "string", "example": "success" }, "data": { "type": "object", "required": [ "query", "count", "pins" ], "properties": { "query": { "type": "string" }, "count": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "dominant_palette_summary": { "type": "array", "items": { "type": "string" } }, "pins": { "type": "array", "items": { "$ref": "#/components/schemas/NormalizedPin" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "PinDetailsResponse": { "type": "object", "required": [ "code", "status", "data", "meta" ], "properties": { "code": { "type": "integer", "example": 0 }, "provider": { "type": "string" }, "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "required": [ "pin" ], "properties": { "pin": { "$ref": "#/components/schemas/NormalizedPin" } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "BoardsSearchResponse": { "type": "object", "required": [ "code", "status", "data", "meta" ], "properties": { "code": { "type": "integer", "example": 0 }, "provider": { "type": "string" }, "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "required": [ "query", "count", "boards" ], "properties": { "query": { "type": "string" }, "count": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "boards": { "type": "array", "items": { "$ref": "#/components/schemas/NormalizedBoard" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "UserProfileResponse": { "type": "object", "required": [ "code", "status", "data", "meta" ], "properties": { "code": { "type": "integer", "example": 0 }, "provider": { "type": "string" }, "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "required": [ "profile" ], "properties": { "profile": { "$ref": "#/components/schemas/NormalizedProfile" } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "StaysSearchResponse": { "type": "object", "required": [ "code", "status", "data", "meta" ], "properties": { "code": { "type": "integer", "example": 0 }, "provider": { "type": "string" }, "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "required": [ "location", "count", "stays" ], "properties": { "location": { "type": "string" }, "checkin": { "type": "string" }, "checkout": { "type": "string" }, "adults": { "type": "integer" }, "currency": { "type": "string" }, "count": { "type": "integer" }, "stays": { "type": "array", "items": { "$ref": "#/components/schemas/NormalizedStay" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "StaysMarketResponse": { "type": "object", "required": [ "code", "status", "data", "meta" ], "properties": { "code": { "type": "integer", "example": 0 }, "provider": { "type": "string" }, "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "required": [ "market", "count", "listings" ], "properties": { "market": { "type": "string" }, "count": { "type": "integer" }, "market_summary": { "type": "object" }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/NormalizedStay" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "StaysDestinationsResponse": { "type": "object", "required": [ "code", "status", "data", "meta" ], "properties": { "code": { "type": "integer", "example": 0 }, "provider": { "type": "string" }, "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "required": [ "query", "count", "destinations" ], "properties": { "query": { "type": "string" }, "count": { "type": "integer" }, "destinations": { "type": "array", "items": { "type": "object", "required": [ "destination_id", "display_name" ], "properties": { "destination_id": { "type": "string" }, "location_name": { "type": "string" }, "display_name": { "type": "string" }, "country_code": { "type": [ "string", "null" ] }, "terms": { "type": "array", "items": { "type": "string" } } } } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } }, "responses": { "UnauthorizedError": { "description": "Missing or invalid API key (`pn_live_...`).", "content": { "application/json": { "example": { "code": -1, "provider": "https://pindataapi.com", "status": "error", "msg": "Invalid or missing API key. Pass x-api-key: pn_live_... or claim 12,000 free credits at https://pindataapi.com/signup" } } } }, "InsufficientCreditsError": { "description": "Account credit balance depleted (0 Credits charged).", "content": { "application/json": { "example": { "code": -1, "provider": "https://pindataapi.com", "status": "error", "msg": "Insufficient credits. Reload starting at $9 PAYG at https://pindataapi.com/dashboard/billing" } } } }, "RateLimitedError": { "description": "Per-minute concurrency limit exceeded.", "content": { "application/json": { "example": { "code": -1, "provider": "https://pindataapi.com", "status": "error", "msg": "Rate limit exceeded. Upgrade to Starter (120 RPM), Pro (300 RPM), or Business (600 RPM)." } } } }, "NotFoundError": { "description": "Requested pin or profile was not found (0 Credits charged).", "content": { "application/json": { "example": { "code": -1, "provider": "https://pindataapi.com", "status": "error", "msg": "Resource was not found. Zero credits charged." } } } } } } }