Pinterest API: Pins, Boards und die Freigabe, die du zuerst brauchst

Die Pinterest API v5 lebt auf https://api.pinterest.com/v5. Boards und Pins kannst du ab Tag eins anlegen, aber mit Trial Access sehen sie nur du, und Pinterest will ein Demo-Video mit dem OAuth-Flow, bevor es Standard freigibt. Hier ist der ganze Weg, gelesen am 11. November 2026.

Was die API dir gibt, und in welcher Reihenfolge

Pinterest zeigt hinter einer Base-URL zwei Welten: organische Inhalte (Boards, Pins, Nutzerkonten, Medien-Uploads) und Ads (Kampagnen, Zielgruppen, Kataloge, Reporting). Beide nutzen dasselbe Bearer-Token, über Scopes gefiltert, und beide werden über die Access-Stufe rationiert, in der deine App sitzt.

Die Reihenfolge zählt, weil sie fast niemand vorher liest. Du bekommst keinen API-Key, schreibst Code und lieferst aus. Du bekommst eine für Trial freigegebene App, baust gegen Limits, die pro Tag statt pro Minute zählen, und beweist dann im Video, dass es läuft, bevor jemand außer dir sieht, was du anlegst.

Trial Access gegen Standard Access

Zwei Stufen, keine weiteren. Aus Pinterests Guide zu den Access-Stufen, heute gelesen:

Lies die Sichtbarkeitszeile zweimal. Im Trial ist ein Pin, den deine Integration anlegt, ein Pin, den nur du siehst. Jedes „es läuft, aber es ist nichts erschienen“-Ticket beginnt dort.

Zum Aufstieg: die App muss schon für Trial freigegeben sein und die Developer Guidelines erfüllen, und du schickst ein Video, in dem deine App eine Aktion mit der Pinterest API abschließt und den OAuth-Flow zeigt. Das gilt auch, wenn du der einzige Nutzer bist, und Terminal- oder Postman-Bildschirmaufnahmen werden akzeptiert. Pinterest prüft bei der Einreichung deinen Use Case und den Link zur Datenschutzerklärung. Du gehst in My apps, wählst Upgrade auf der App-Karte, bestätigst die Angaben, lädst das Video hoch, schickst ab. Es gibt keine veröffentlichte Frist: Anträge werden „regelmäßig geprüft“, und du bekommst die Entscheidung per E-Mail. Bei einer Ablehnung und Einspruch über ein Help-Center-Ticket rechne mit „ein paar Tagen“.

Erst mal die App bekommen

Vor allem anderen: ein Pinterest-Unternehmenskonto anlegen oder einloggen, E-Mail bestätigen, in My apps die Developer Terms of Service annehmen, dann das App-Antragsformular abschicken. Pinterest prüft es und schickt dir per E-Mail eine Zusage oder eine Ablehnung. Die Trial-Zusage bringt dir außerdem produktbeschränkte Test-Tokens, die nach 24 Stunden ablaufen und zum Antesten von Endpoints taugen, nicht für etwas, das dauerhaft läuft.

Es gibt auch eine Sandbox, der ehrliche Ort, um die Request-Formen zu lernen, ohne 300 Writes am Tag zu verbrennen.

OAuth, Scopes und das Token, das nach 60 Tagen stirbt

Drei Grants, und nur einer gibt dir die ganze API:

• Authorization Code, um im Namen eines Nutzers zu handeln. Der Nutzer bestätigt die Scopes auf https://www.pinterest.com/oauth/, landet wieder auf deiner redirect_uri mit einem Code, und dein Server tauscht ihn auf oauth/token. Das ist der einzige Grant mit vollem API-Zugang.
• Client Credentials, für dein eigenes Entwicklerkonto. Er erfordert Zwei-Faktor-Authentifizierung und erreicht manche sensiblen Endpoints nicht.
• Refresh Token, um ein Refresh-Token gegen ein frisches Access-Token zu tauschen, ohne den Nutzer einzubeziehen.

Der Authorize-Call will client_id, redirect_uri, response_type=code und scope. state ist optional, und du solltest es trotzdem mitschicken, weil es den Callback vor Cross-Site Request Forgery schützt.

Scopes schreiben sich {entity}:read und {entity}:write, durch Komma oder Leerzeichen getrennt, über die Entitäten ads, billing, biz_access, boards, catalogs, pins und user_accounts. Für private Inhalte gibt es geheime Varianten: boards:read_secret, pins:write_secret. Pinterest rät selbst dazu, „von deinen Nutzern so wenige Scopes wie möglich anzufordern, wie ihr Geschäftsbedarf es erfordert“, und das ist auch der Rat, der dein App-Review kurz hält.

Jetzt der Teil, der Integrationen Monate später zerlegt. Das Access-Token trägt expires_in: 2592000, also 30 Tage. Das alte Refresh-Token hatte refresh_token_expires_in: 31536000, ein Jahr mit harter Grenze, und Pinterest unterstützt das nicht mehr. Das kontinuierliche Refresh-Token läuft nach 60 Tagen ab, lässt sich aber unbegrenzt erneuern, du musst es also wirklich innerhalb dieses Fensters erneuern, damit es am Leben bleibt. Apps, die vor dem 25. September 2025 angelegt wurden, müssen continuous_refresh=true mitgeben, um es zu bekommen; Apps ab diesem Datum bekommen es automatisch. Verpasst du das Fenster, gibt es keinen Reparatur-Call, nur den ganzen Authorization-Code-Flow von vorn, mit dem Nutzer vor dem Bildschirm. Ein abgelaufenes oder ungültiges Token antwortet HTTP 401 mit API-Fehlercode 2.

Wenn dir das Muster bekannt vorkommt: es ist dieselbe Form wie auf jeder anderen Plattform, kurzes Token, langes Token, stiller Ablauf. Die allgemeine Fassung habe ich in Social-Media-Access-Tokens aufgeschrieben.

Ein Board und einen Pin anlegen

Boards kommen zuerst, weil ein Pin einen Ort zum Leben braucht. Die Create-Calls sind boards/create und pins/create, und die Scopes, die du brauchst, sind boards:read, boards:write, pins:read und pins:write. Die Lese-Scopes sind keine Deko: für einen Pin brauchst du die ID des Boards oder der Board-Section, und diese ID kommt aus einem Read.

Ein media_source-Objekt trägt das Bild oder das Video. Die dokumentierten Source Types sind image_url und video_id. Für einen Bild-Pin ist image_url plus board_id, title und description der ganze Body. Eine gültige Bild-URL ist nicht optional: Pinterest warnt, dass „eine gültige Bild-URL angegeben werden muss, um einen 400 Bad Request zu vermeiden“.

Video sind drei Calls plus ein Warten:

1. POST https://api.pinterest.com/v5/media mit {"media_type": "video"}. Du bekommst eine media_id, eine upload_url und einen upload_parameters-Block zurück.
2. POST der Datei an upload_url als multipart/form-data, wobei du jeden Key aus upload_parameters als Formularfeld neben die .mp4, .mov oder .m4v legst. Hier kein Authorization-Header. Erfolg ist 204 No Content.
3. GET /v5/media/{media_id}, bis der Status succeeded zeigt. Die Verarbeitung dauert einige Sekunden, und währenddessen kann creative_type noch REGULAR sagen, bevor er auf VIDEO umspringt.
4. POST /v5/pins mit media_source.source_type auf video_id, der media_id und einer cover_image_url. Erfolg ist 201 Created mit der Pin-ID.

Zwei Obergrenzen, die du vor einem Massenimport kennen solltest: 2.000 Boards jeder Art, inklusive Gruppen-Boards, die du nicht angelegt hast, und 200.000 Pins auf einem privaten Konto, geheime Pins und deine Pins auf Gruppen-Boards inklusive. Wenn du Inhalte neu pinnst, die es auf Pinterest schon gibt, ist pins/save der richtige Call statt pins/create, genau damit du diese Entitäten-Limits nicht verbrauchst.

Eine neue Falle: Apps, die am 14. September 2026 oder später registriert wurden, können einen 403 PINNER_DATA_ACCESS_DENIED bekommen, wenn sie ein Board oder einen Pin eines Nicht-Unternehmensnutzers ohne Pinterests Freigabe abfragen. Teste mit einem Unternehmenskonto.

pinterest api python: die Form davon

Kein SDK nötig, requests reicht. Das ist der Create-Pin-Call mit den dokumentierten Feldern:

import os, requests

TOKEN = os.environ["PINTEREST_ACCESS_TOKEN"]
BASE = "https://api.pinterest.com/v5"
headers = {"Authorization": f"Bearer {TOKEN}"}

boards = requests.get(f"{BASE}/boards", headers=headers, timeout=30).json()
board_id = boards["items"][0]["id"]

pin = requests.post(
    f"{BASE}/pins",
    headers=headers,
    json={
        "board_id": board_id,
        "title": "Weeknight pasta",
        "description": "Ten minutes, one pan.",
        "link": "https://example.com/recipes/weeknight-pasta",
        "media_source": {"source_type": "image_url",
                         "url": "https://example.com/img/pasta.jpg"},
    },
    timeout=30,
)
print(pin.status_code, pin.json())

Beobachte x-ratelimit-limit, x-ratelimit-remaining und x-ratelimit-reset bei jeder Antwort. Im Trial zählen sie ein Tagesbudget herunter, eine Retry-Schleife auf einem fehlschlagenden Call kann deinen Testtag also vor dem Mittagessen beenden. Pinterest veröffentlicht keinen Preis für den API-Zugang: die Stufen und diese Limits sind die Rationierung.

Wo Pinterest neben den anderen Plattform-APIs steht

Pinterest liegt auf der leichteren Hälfte des Spektrums: gewöhnliches OAuth, einfache Entitäten, kurze Create-Calls. Was es stattdessen verlangt, ist das Review, das App-Formular, dann das Demo-Video, dann das Warten, bevor irgendwer außer dir sieht, was du veröffentlichst. Meta verlangt auch ein App-Review, gibt dir öffentliche Sichtbarkeit aber von Anfang an, nachzulesen in dem Instagram-Graph-API-Guide. Der plattformübergreifende Blick, Rate Limits pro Netzwerk inklusive, steht in dem Social-Media-API-Guide und in der Rate-Limit-Referenz.

Eine Sache ganz offen: PlugKit veröffentlicht nicht auf Pinterest. Es deckt Instagram, Facebook, LinkedIn, TikTok, YouTube, X, Threads, Bluesky, WhatsApp und Telegram ab, und Pinterest steht heute nicht auf dieser Liste. Wenn Pinterest dein Hauptkanal ist, schreib selbst gegen v5, oder nimm ein Tool, das es nennt.

FAQ

Ist die Pinterest API kostenlos?

Pinterest veröffentlicht keinen Preis für den API-Zugang. Rationiert werden Anfragen und Sichtbarkeit: Trial Access deckelt dich bei 1.000 Anfragen pro Tag pro App und hält die Boards und Pins, die du anlegst, nur für ihren Ersteller sichtbar, während Standard die Grenzen auf 100 Anfragen pro Sekunde pro Nutzer pro App hebt. Ads-Endpoints brauchen weiterhin ein Werbekonto.

Wie bekomme ich Standard Access für die Pinterest API?

Lass die App erst für Trial freigeben, halte dich an die Developer Guidelines, dann geh in My apps und wähle Upgrade auf der App-Karte. Die Einreichung fragt nach deinem Use Case, einem Link zur Datenschutzerklärung und einem Video, in dem deine App eine API-Aktion abschließt und den OAuth-Flow zeigt. Eine Terminal- oder Postman-Aufnahme zählt. Pinterest schickt die Entscheidung per E-Mail.

Warum sieht niemand die Pins, die meine App anlegt?

Weil die App im Trial Access ist, wo Boards und Pins nur ihr Ersteller sieht. Das ist dokumentiertes Verhalten, kein Bug in deinem Code. Erst der Wechsel auf Standard macht sie öffentlich.

Wie lange hält ein Pinterest-Access-Token?

Das Access-Token hält 30 Tage (expires_in: 2592000). Das kontinuierliche Refresh-Token läuft nach 60 Tagen ab, lässt sich aber unbegrenzt erneuern, du musst es also innerhalb dieses Fensters erneuern. Apps, die vor dem 25. September 2025 angelegt wurden, brauchen continuous_refresh=true, um es zu bekommen. Ein abgelaufenes Token gibt HTTP 401 mit API-Fehlercode 2 zurück.

Kann ich mit einem KI-Agenten auf Pinterest posten?

Nur, indem du selbst gegen v5 schreibst oder ein Tool nimmst, das Pinterest unterstützt. Es gibt keinen Pinterest-MCP-Server von Pinterest, und PlugKit deckt Pinterest nicht ab. Das Muster für die abgedeckten Plattformen steht in MCP oder REST-API für deinen Agenten.

AB

Antoine BlancoGründer von PlugKit. Betreibt seine eigenen Instagram-, YouTube- und X-Accounts über die hier beschriebene API und den MCP-Server.