API Pinterest : épingles, tableaux et l'autorisation qu'il faut d'abord

L'API Pinterest v5 vit sur https://api.pinterest.com/v5. Tu peux créer des tableaux et des épingles dès le premier jour, mais en accès Trial ils ne sont visibles que par toi, et Pinterest veut une vidéo de démo montrant le flux OAuth avant d'accorder le Standard. Voici tout le parcours, lu le 11 novembre 2026.

Ce que l'API te donne, et dans quel ordre

Pinterest expose deux mondes derrière une seule base URL : le contenu organique (tableaux, épingles, comptes utilisateurs, envois de médias) et la publicité (campagnes, audiences, catalogues, reporting). Les deux utilisent le même bearer token, filtré par les scopes, et les deux sont rationnés par le palier d'accès dans lequel ton app se trouve.

L'ordre compte, parce que presque personne ne le lit à l'avance. Tu n'obtiens pas une clé d'API pour écrire du code et livrer. Tu fais approuver une app en Trial, tu construis contre des limites comptées par jour plutôt que par minute, puis tu prouves en vidéo que ça marche avant que ce que tu crées soit visible par quelqu'un d'autre.

Accès Trial contre accès Standard

Deux paliers, pas d'autres. D'après le guide des paliers d'accès de Pinterest, lu aujourd'hui :

Relis deux fois la ligne de visibilité. En Trial, une épingle que ton intégration crée est une épingle que toi seul peux voir. Tous les tickets « ça marche mais rien n'est apparu » commencent là.

Pour monter : l'app doit déjà être approuvée en Trial et respecter les Developer Guidelines, et tu envoies une vidéo de ton app réalisant une action avec l'API Pinterest qui montre le flux OAuth. Ça s'applique même si tu es le seul utilisateur, et les enregistrements d'écran de terminal ou de Postman sont acceptés. Pinterest vérifie ton cas d'usage et le lien vers ta politique de confidentialité pendant la soumission. Tu vas dans My apps, tu choisis Upgrade sur la carte de l'app, tu confirmes les informations, tu envoies la vidéo, tu soumets. Il n'y a pas de délai publié : les demandes sont « examinées régulièrement » et tu reçois la décision par e-mail. En cas de refus et d'appel par un ticket au Help Center, compte « quelques jours ».

Obtenir l'app, déjà

Avant tout ça : crée un compte professionnel Pinterest ou connecte-toi, vérifie ton e-mail, accepte les Developer Terms of Service dans My apps, puis envoie le formulaire de demande d'app. Pinterest l'examine et t'envoie par e-mail une approbation ou un refus. L'approbation Trial te donne aussi des test tokens limités en produits, qui expirent au bout de 24 heures et servent à tâter les endpoints, pas à faire tourner quoi que ce soit en continu.

Il y a aussi un sandbox, l'endroit honnête pour apprendre la forme des requêtes sans brûler 300 écritures par jour.

OAuth, les scopes, et le token qui meurt à 60 jours

Trois grants, et un seul te donne toute l'API :

• Authorization Code, pour agir au nom d'un utilisateur. L'utilisateur approuve les scopes sur https://www.pinterest.com/oauth/, revient sur ton redirect_uri avec un code, et ton serveur l'échange sur oauth/token. C'est le seul grant qui couvre toute l'API.
• Client Credentials, pour ton propre compte développeur. Il exige l'authentification à deux facteurs et ne peut pas atteindre certains endpoints sensibles.
• Refresh Token, pour échanger un refresh token contre un nouvel access token sans intervention de l'utilisateur.

L'appel d'autorisation veut client_id, redirect_uri, response_type=code et scope. state est optionnel et tu devrais l'envoyer quand même, puisque c'est lui qui protège le callback d'une falsification de requête inter-sites.

Les scopes s'écrivent {entity}:read et {entity}:write, séparés par une virgule ou une espace, sur les entités ads, billing, biz_access, boards, catalogs, pins et user_accounts. Des variantes secrètes existent pour le contenu privé : boards:read_secret, pins:write_secret. Le conseil de Pinterest lui-même : « demande à tes utilisateurs le minimum de scopes nécessaires à leur besoin métier », ce qui est aussi le conseil qui raccourcit la revue de ton app.

Maintenant la partie qui casse les intégrations des mois plus tard. L'access token porte expires_in: 2592000, soit 30 jours. L'ancien refresh token avait refresh_token_expires_in: 31536000, un an avec une limite dure, et Pinterest ne le prend plus en charge. Le refresh token continu expire au bout de 60 jours mais peut être rafraîchi indéfiniment, donc il faut vraiment le rafraîchir dans cette fenêtre pour le garder en vie. Les apps créées avant le 25 septembre 2025 doivent passer continuous_refresh=true pour l'obtenir ; celles créées à cette date ou après l'obtiennent automatiquement. Si tu rates la fenêtre, il n'y a pas d'appel de réparation, seulement le flux Authorization Code complet à refaire, avec l'utilisateur devant l'écran. Un token expiré ou invalide répond HTTP 401 avec le code d'erreur API 2.

Si ce schéma te semble familier, c'est la même forme que sur toutes les autres plateformes : token court, token long, expiration silencieuse. J'en ai fait la version générale dans les access tokens des réseaux sociaux.

Créer un tableau et une épingle

Les tableaux d'abord, parce qu'une épingle a besoin d'un endroit où vivre. Les appels de création sont boards/create et pins/create, et les scopes dont tu as besoin sont boards:read, boards:write, pins:read et pins:write. Les scopes de lecture ne sont pas décoratifs : pour créer une épingle il te faut l'ID du tableau ou de la section, et cet ID vient d'une lecture.

Un objet media_source porte l'image ou la vidéo. Les source types documentés sont image_url et video_id. Pour une épingle image, image_url plus board_id, title et description, c'est tout le corps. Une URL d'image valide n'est pas optionnelle : Pinterest avertit qu'« il faut fournir une URL d'image valide pour éviter un 400 Bad Request ».

La vidéo, c'est trois appels plus une attente :

1. POST https://api.pinterest.com/v5/media avec {"media_type": "video"}. Tu récupères un media_id, une upload_url et un bloc upload_parameters.
2. POST le fichier vers upload_url en multipart/form-data, en passant chaque clé de upload_parameters comme champ de formulaire à côté du .mp4, .mov ou .m4v. Pas d'en-tête Authorization sur celui-là. Le succès, c'est 204 No Content.
3. GET /v5/media/{media_id} jusqu'à ce que le statut indique succeeded. Le traitement prend quelques secondes, et pendant ce temps creative_type peut encore afficher REGULAR avant de basculer sur VIDEO.
4. POST /v5/pins avec media_source.source_type réglé sur video_id, le media_id, et un cover_image_url. Le succès, c'est 201 Created avec l'ID de l'épingle.

Deux plafonds à connaître avant de concevoir un import en masse : 2 000 tableaux de tout type, y compris les tableaux de groupe que tu n'as pas créés, et 200 000 épingles sur un compte personnel, épingles secrètes et tes épingles sur des tableaux de groupe comprises. Si tu ré-épingles du contenu qui existe déjà sur Pinterest, pins/save est le bon appel plutôt que pins/create, justement pour ne pas dépenser ces quotas d'entités.

Un piège récent : les apps enregistrées le 14 septembre 2026 ou après peuvent recevoir un 403 PINNER_DATA_ACCESS_DENIED quand elles demandent un tableau ou une épingle appartenant à un utilisateur non professionnel sans l'autorisation de Pinterest. Teste avec un compte professionnel.

pinterest api python : la forme que ça prend

Pas besoin de SDK, requests suffit. Voici l'appel de création d'épingle avec les champs documentés :

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())

Surveille x-ratelimit-limit, x-ratelimit-remaining et x-ratelimit-reset sur chaque réponse. En Trial, ils décomptent un budget journalier, donc une boucle de relance sur un appel qui échoue peut terminer ta journée de tests avant midi. Pinterest ne publie pas de prix pour l'accès à l'API : les paliers et ces limites sont le rationnement.

Où se situe Pinterest à côté des autres API de plateformes

Pinterest est sur la moitié facile du spectre : OAuth ordinaire, entités simples, appels de création courts. Ce qu'il facture à la place, c'est la revue, le formulaire d'app puis la vidéo de démo puis l'attente, avant que ce que tu publies soit visible par quelqu'un d'autre. Meta facture aussi une revue d'app mais te donne la visibilité publique dès le départ, traité dans le guide de l'API Graph Instagram. La vue multi-plateformes, quotas par réseau compris, est dans le guide des API réseaux sociaux et la référence des quotas.

Une chose à dire franchement : PlugKit ne publie pas sur Pinterest. Il couvre Instagram, Facebook, LinkedIn, TikTok, YouTube, X, Threads, Bluesky, WhatsApp et Telegram, et Pinterest n'est pas sur cette liste aujourd'hui. Si Pinterest est ton canal principal, écris contre v5 toi-même, ou prends un outil qui le nomme.

FAQ

L'API Pinterest est-elle gratuite ?

Pinterest ne publie pas de prix pour l'accès à l'API. Ce qu'il rationne, ce sont les requêtes et la visibilité : l'accès Trial te plafonne à 1 000 requêtes par jour et par app et garde les tableaux et les épingles que tu crées visibles seulement par leur créateur, tandis que le Standard fait passer les limites à 100 requêtes par seconde, par utilisateur et par app. Les endpoints Ads exigent toujours un compte publicitaire.

Comment obtenir l'accès Standard à l'API Pinterest ?

Fais d'abord approuver l'app en Trial, reste dans les Developer Guidelines, puis va dans My apps et choisis Upgrade sur la carte de l'app. La soumission demande ton cas d'usage, un lien vers ta politique de confidentialité, et une vidéo de ton app réalisant une action via l'API qui montre le flux OAuth. Un enregistrement de terminal ou de Postman compte. Pinterest envoie la décision par e-mail.

Pourquoi personne ne voit les épingles que mon app crée ?

Parce que l'app est en accès Trial, où les tableaux et les épingles ne sont visibles que par leur créateur. C'est un comportement documenté, pas un bug dans ton code. Passer en Standard est ce qui les rend publics.

Combien de temps dure un access token Pinterest ?

L'access token dure 30 jours (expires_in: 2592000). Le refresh token continu expire au bout de 60 jours mais peut être rafraîchi indéfiniment, donc tu dois le rafraîchir dans cette fenêtre. Les apps créées avant le 25 septembre 2025 ont besoin de continuous_refresh=true pour l'obtenir. Un token expiré renvoie HTTP 401 avec le code d'erreur API 2.

Puis-je publier sur Pinterest depuis un agent IA ?

Seulement en écrivant contre v5 toi-même ou en utilisant un outil qui prend en charge Pinterest. Il n'existe pas de serveur MCP Pinterest signé Pinterest, et PlugKit ne couvre pas Pinterest. Le schéma pour les plateformes couvertes est dans MCP ou API REST pour ton agent.

AB

Antoine BlancoFondateur de PlugKit. Gère ses propres comptes Instagram, YouTube et X via l'API et le serveur MCP décrits ici.