Pin & Pop API — Pins (v1)

Read-only access to the Pin & Pop pin catalog.

  • Base URL: https://pinandpop.com/api/v1
  • Docs home: https://pinandpop.com/docs/api/v1-pins

Authentication

All endpoints require a bearer API token (distinct from the in-app Trade Tokens used in the marketplace). Pass it in the Authorization header:

Authorization: Bearer <your-api-token>

API tokens are scoped by ability:

Ability Grants
pins:read Pin metadata (name, series, origin, edition, release year, timestamps).
images:read Adds cover_image URLs to responses.

Requests without a valid API token return 401 Unauthorized. API tokens missing pins:read return 403 Forbidden. API tokens with pins:read but not images:read will receive responses with the cover_image field omitted.

API tokens are issued by the Pin & Pop team — see Getting Access below.

Rate limits

  • 60 requests per minute per authenticated user.
  • Exceeding the limit returns 429 Too Many Requests.

Endpoints

GET /pins

List pins with optional filters.

Query parameters

Param Type Description
added_after date Only return pins added to the catalog strictly after this date (e.g. 2024-06-01).
id_after integer Only return pins with an id greater than this value.
per_page integer Results per page. Default 50, max 200.
cursor string Pagination cursor — pass the next_cursor value from the previous response.

Example

GET /api/v1/pins?added_after=2024-06-01&per_page=100

Response (200 OK)

{
  "data": [
    {
      "id": 12345,
      "name": "Mickey Mouse",
      "series": "Disneyland 50th",
      "origin": "Disneyland Resort",
      "edition": "LE 300",
      "release_year": "2024",
      "cover_image": "https://.../pins/lg/12345.jpg",
      "url": "https://pinandpop.com/pin/12345/mickey-mouse",
      "series_url": "https://pinandpop.com/series/disneyland-50th",
      "self": "https://pinandpop.com/api/v1/pins/12345",
      "added_at": "2024-06-14T10:22:01.000000Z"
    }
  ],
  "links": {
    "first": "...",
    "prev": null,
    "next": "https://pinandpop.com/api/v1/pins?cursor=eyJp..."
  },
  "meta": {
    "path": "https://pinandpop.com/api/v1/pins",
    "per_page": 50,
    "next_cursor": "eyJp...",
    "prev_cursor": null
  }
}

Results are sorted by id ascending. Follow meta.next_cursor (or links.next) until next_cursor is null.

Field notes:

  • edition — short code identifying the edition type: "OE" (Open Edition), "LR" (Limited Release), or "LE" (Limited Edition). For limited editions with a known run size, the size is appended: "LE 300". Limited editions with an unknown or undisclosed run size return just "LE". Returns null if the edition type is unknown.
  • series_url — public URL to the pin's series page on pinandpop.com. Returns null if the pin is not assigned to a series.
  • cover_image — only present when the API token has the images:read ability. With a pins:read-only API token the field is omitted. See License & Attribution below for image-use restrictions.

GET /pins/{id}

Fetch a single pin.

Response (200 OK) — same object shape as a single item in data above.

Returns 404 Not Found if the pin does not exist.

Incremental sync

To keep a local copy in sync without re-downloading the whole catalog:

  1. On the first sync, page through GET /pins following next_cursor until exhausted. Record the highest id you saw.
  2. On subsequent syncs, call GET /pins?id_after=<highest_id> and page through until exhausted. Update your stored highest id.

Alternatively, use added_after=<last_sync_timestamp> if you only care about recently-added pins.

Error responses

Status Meaning
401 Missing or invalid API token.
403 API token does not have the pins:read ability.
404 Pin does not exist (for /pins/{id}).
422 Invalid query parameter (e.g. malformed date, per_page > 200).
429 Rate limit exceeded.

Validation errors (422) return a structured error body:

{
  "message": "The per page field must not be greater than 200.",
  "errors": {
    "per_page": ["The per page field must not be greater than 200."]
  }
}

License & Attribution

Use of this API is governed by the Pin & Pop Data & Image License Agreement. The full agreement is provided when an API token is issued. The key rules in summary:

Attribution (required)

All uses of Pin & Pop data require visible attribution to end users. Use one of:

  • Websites and apps: Pin data provided by Pin & Pop (pinandpop.com)
  • Documents or publications: Data sourced from the Pin & Pop community database at pinandpop.com

Attribution must be visible to end users — not buried in a README or hidden in source.

License tiers

Tier Data Images Commercial use
Community (free) Pin metadata snapshot Not included Not permitted
Developer / Commercial Full metadata via API cover_image URLs (Tier 2) Permitted within agreed scope

The v1 API described here is the Developer / Commercial tier.

Image use (important)

cover_image URLs are provided for internal use only — for example, training reverse image search models, data processing, or research inside your own systems.

You may not:

  • Display cover_image URLs publicly on any website, app, or platform
  • Redistribute, sublicense, or resell image files to third parties
  • Use images in any publicly accessible product or interface

Many pins in the catalog are licensed Disney products. Public image redistribution creates IP risk for you and for us. If you need to show a pin to an end user, link to the pin's page (url field) on pinandpop.com rather than hosting or embedding the image.

Other restrictions (all tiers)

  • No resale, sublicensing, or redistribution of the dataset
  • No using the data to build a product whose primary purpose is to compete with Pin & Pop
  • No removing or obscuring attribution
  • No presenting the data as your own original work

Getting access

API tokens are issued by the Pin & Pop team. To request access, email support@pinandpop.com with:

  • Who you are / your organization
  • A short description of your intended use
  • Whether you need images:read (Tier 2)

We'll send a countersignable copy of the Data & Image License Agreement and, on acceptance, issue your API token.