Blog/Developer Tools/

Pinterest Public Data API | SandBase

Read public Pinterest search results, boards, and pins with one REST API. No Pinterest login, no SDK — one SandBase key, built for agent workflows.

By Sophie Lin
Dark cinematic render of Pinterest search pins, boards, and a pin card flowing through one API conduit into an agent core

Pinterest is a visual discovery engine — a place where people plan home renovations, wardrobes, recipes, and trips. That makes it a rich signal for trend research, e-commerce inspiration, and creative planning. Getting at it programmatically usually means fighting a headless browser and rebuilding a scraper every time the site shifts.

The SandBase Pinterest public data API trades that setup tax for plain REST. It reads Pinterest’s public search results, user boards, and board pins through simple endpoints — one SandBase API key, no Pinterest login and no SDK. The endpoint API reference is the source of truth for each parameter and the response shape; the field names below come from calls I ran (tested on 2026-09-27, UTC) and are shown as one observed shape — confirm them against a live response, since payloads change over time.

This is not Pinterest’s official API. Use Pinterest’s official developer platform when you need authenticated member actions or a licensed data agreement. Use SandBase when your workflow needs public, read-only data for research and monitoring. Ready to try it? Get a SandBase API key and browse the Pinterest endpoints.

Key takeaway

  • One API reads Pinterest’s public search results, user boards, and board pins.
  • Each endpoint is POST /v1/api/pinterest/<path> — pass only that endpoint’s params, no SDK, one SANDBASE_API_KEY.
  • Endpoints key off natural inputs: a query for search, a handle for a user’s boards, and a url for a board or pin.
  • Read-only public data only. There is no posting, no platform login on your side, and no private data; authenticate with a SandBase API key.

A note on this endpoint’s response shape

Most SandBase endpoints return an outputs array. This Pinterest surface instead returns a single output object (note the singular) alongside id, model, and status. On a completed run I saw an output with a success boolean, a result list (pins or boards), and a cursor for paging. Because shapes differ across the catalog, always confirm the exact envelope for the endpoint you call against its live reference before you build.

Which Pinterest API do you need?

Your needChooseWhy
Post, save pins, or act as a memberPinterest’s official platformMember and account operations run through Pinterest directly.
Read public search, boards, or pinsSandBase Pinterest public-data APIPlain REST, one SandBase key, structured JSON for read-only workflows.
Private or account-only dataNeither public workflowThat data is out of scope for this public-data guide.

What you can get from the Pinterest API

Grouped by job:

  • Search — keyword search returning public pins.
  • User boards — the public boards for a given handle.
  • Board — the pins on a board, addressed by its url.
  • Pin — a single pin’s data, addressed by its url.

Check each endpoint’s live API reference for the exact parameters before you build; availability differs by endpoint.

SandBase Pinterest API page: description, capability tags, and the endpoint list The Pinterest API page on SandBase — a tagged overview and the endpoint list, each with its path.

What Pinterest provides vs. what SandBase adds

Public data comes from Pinterest. SandBase does not own or operate Pinterest; it provides a uniform API layer for eligible public-data workflows. Each capability becomes one stable endpoint, auth collapses to a single key, and responses come back as predictable JSON — so an agent can walk from a keyword to a set of pins, or from a handle to its boards, along one convention instead of maintaining a scraper.

Quick start: your first call

SandBase exposes more than one API surface. The catalog may show GET paths under /apis/v1/...; this guide uses the vendor-qualified Model API path on each endpoint’s API reference. Do not swap the HTTP method or URL — follow the reference for the endpoint you choose.

Search public pins by keyword:

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/pinterest/search",
    headers={
        "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"query": "home office setup"},
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "completed":
    error = body.get("error", {})
    raise RuntimeError(error.get("message", "Pinterest request did not complete"))

# This surface returns a single `output` object (not an `outputs` array).
output = body.get("output", {})
if output.get("success"):
    pins = output.get("pins", [])
    print(len(pins), "pins, cursor:", bool(output.get("cursor")))
curl -X POST https://api.sandbase.ai/v1/api/pinterest/search \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "home office setup"}'

The response carries an id, a status, the model name, and — on a completed run — a single output object with a success flag, a result list, and a cursor. A failed or timeout run instead carries error, so branch on status before reading output. The block below is a trimmed real response from my search call (search run id bb49ff54-271a-403b-82c7-ca510922c580, tested on 2026-09-27, UTC) — the values move over time, so treat the field names as observed and confirm them against a live response:

{
  "id": "bb49ff54-271a-403b-82c7-ca510922c580",
  "model": "pinterest/search",
  "status": "completed",
  "output": {
    "success": true,
    "pins": [ { "id": "…", "title": {}, "url": "https://www.pinterest.com/pin/…" } ],
    "cursor": "…"
  }
}

Response shapes differ by endpoint — inspect one real response and map the exact path per endpoint.

SandBase API reference for a Pinterest endpoint, showing the vendor-qualified URL and the response schema The endpoint API reference is the source of truth for each parameter name and response path.

Capability map

CapabilityEndpointInputTypical use
Searchpinterest/searchqueryKeyword pin discovery
User boardspinterest/user-boardshandleA user’s public boards
Boardpinterest/boardurlPins on a board
Pinpinterest/pinurlA single pin’s data

Paging uses the cursor returned in output; pass it back on the next request. Read each endpoint’s schema for the exact parameter name.

SandBase Pinterest endpoint list showing search, board, pin, and user-boards endpoints A slice of the Pinterest endpoint list.

Chaining calls in an agent workflow

Because every endpoint shares the same auth and a consistent output envelope, an agent can walk from a handle to its boards to a board’s pins without special-casing each surface. A common research pattern looks like this:

  1. List a user’s boards. Call pinterest/user-boards with a handle; read output.boards, each carrying a url.
  2. Open a board. Call pinterest/board with a board url to read output.pins.
  3. Search for more. Call pinterest/search with a query to widen the set, paging with output.cursor.

Each step returns the same { id, status, model, output } shape, so your agent branches on status once and reuses the same JSON-reading code across every step.

Common use cases

Pinterest search API for trend discovery

Run pinterest/search with a query to survey pins around a theme, then page with the returned cursor. Input: a query. Output: output.pins plus a cursor. Endpoint: search.

Pinterest boards API for creator research

Read a user’s public boards with pinterest/user-boards by handle, then open a board with pinterest/board by its url. Input: a handle, then a board url. Output: output.boards, then output.pins. Endpoints: user-boards, board.

Pinterest pin API for asset lookups

Read a single pin with pinterest/pin by its url. Input: a valid pin url. Output: the pin’s data. Endpoint: pin. Note that a pin url must reference an existing public pin.

Why run this at the API layer

You could point a headless browser at Pinterest and parse its payloads, but that path is fragile: the site changes, sessions rotate, and you maintain a scraper instead of shipping features. Reading through one uniform API means your code depends on named JSON fields and a single response envelope rather than a page internal. Auth is one key, and because every endpoint returns the same { id, status, model, output } shape, retries, logging, and error handling live in one helper you write once and reuse everywhere.

That uniformity is what makes the workflow composable for an agent. Swap one query for another, swap one handle for the next, and the code path is identical. Add a board read behind the same helper and it slots right in. The practical payoff is that your time goes to what the data means for your research, not to keeping a scraper alive against a moving target. When you need more than single reads, check the live listing for the endpoint that fits and confirm its parameters before wiring it in.

Limitations and boundaries

  • Public, read-only data only. No posting, saving, or private/account-only data.
  • Single output envelope. This surface returns one output object with a success flag — not an outputs array. Check success and branch on status.
  • Pin and board need a valid url. A pin url must reference an existing public pin; a board url comes from a user-boards result.
  • Rate and volume. Treat responses as best-effort reads; as a client-side resilience measure, retry with backoff on transient errors such as HTTP 429.
  • Verify endpoints against the live reference. Availability and fields can change; confirm before building on a specific endpoint.
  • This is not an official Pinterest partnership. SandBase provides uniform access to public data; respect Pinterest’s terms and applicable rules for your use case.

FAQ

Do I need a Pinterest developer app or login? No. You authenticate to SandBase with your SANDBASE_API_KEY. These read endpoints do not require a Pinterest account or OAuth on your side.

Why does this endpoint return output instead of outputs? This Pinterest surface returns a single output object with a success flag, a result list, and a cursor. Other SandBase endpoints may return an outputs array — always confirm the envelope against the live reference for the endpoint you call.

What identifies a search, a user’s boards, a board, or a pin? A query drives search, a handle drives user-boards, and a url addresses a board or a pin.

Can I read private or account-only data? No. The API returns public data only. Private and account-authorized content are out of scope.

Create a SandBase API key, call search with a query, and inspect the returned output before you expand to boards and pins. When you are ready: