API do Pinterest: pins, boards e a aprovação que vem antes

A API do Pinterest v5 mora em https://api.pinterest.com/v5. Você pode criar boards e pins no primeiro dia, mas no acesso Trial eles ficam visíveis só para você, e o Pinterest quer um vídeo de demonstração mostrando o fluxo OAuth antes de conceder o Standard. Aqui está o caminho inteiro, lido em 11 de novembro de 2026.

O que a API te dá, e em que ordem

O Pinterest expõe dois mundos atrás de uma única URL base: conteúdo orgânico (boards, pins, contas de usuário, upload de mídia) e anúncios (campanhas, públicos, catálogos, relatórios). Os dois usam o mesmo bearer token, filtrado por scopes, e os dois são racionados pelo nível de acesso em que o seu app está.

A ordem importa, porque quase ninguém lê antes. Você não consegue uma chave de API, escreve código e entrega. Você consegue um app aprovado no Trial, constrói contra limites contados por dia e não por minuto, e depois prova em vídeo que funciona antes de o que você cria ficar visível para mais alguém.

Acesso Trial contra acesso Standard

Dois níveis, mais nenhum. Segundo o guia de níveis de acesso do Pinterest, lido hoje:

Leia duas vezes a linha de visibilidade. No Trial, um pin que a sua integração cria é um pin que só você vê. Todo ticket de “funciona mas nada apareceu” começa aí.

Para subir: o app já precisa estar aprovado no Trial e cumprir as Developer Guidelines, e você envia um vídeo do seu app completando uma ação com a API do Pinterest que mostre o fluxo OAuth. Isso vale mesmo se você é o único usuário, e gravações de tela de terminal ou de Postman são aceitas. O Pinterest verifica o seu caso de uso e o link da sua política de privacidade durante o envio. Você vai em My apps, escolhe Upgrade no cartão do app, confirma as informações, sobe o vídeo, envia. Não existe prazo publicado: os pedidos são “analisados regularmente” e você recebe a decisão por e-mail. Se for negado e você recorrer por um ticket no Help Center, conte “alguns dias”.

Conseguir o app, para começar

Antes de tudo isso: crie uma conta comercial do Pinterest ou entre na sua, confirme o e-mail, aceite os Developer Terms of Service em My apps e envie o formulário de solicitação do app. O Pinterest analisa e manda por e-mail a aprovação ou a recusa. A aprovação Trial também te dá test tokens limitados por produto, que expiram em 24 horas e servem para testar endpoints, não para deixar nada rodando.

Tem um sandbox também, o lugar honesto para aprender o formato das requisições sem queimar 300 escritas por dia.

OAuth, scopes e o token que morre em 60 dias

Três grants, e só um te dá a API inteira:

• Authorization Code, para agir em nome de um usuário. O usuário aprova os scopes em https://www.pinterest.com/oauth/, volta para o seu redirect_uri com um código, e o seu servidor o troca em oauth/token. É o único grant que cobre a API inteira.
• Client Credentials, para a sua própria conta de desenvolvedor. Exige autenticação em dois fatores e não alcança alguns endpoints sensíveis.
• Refresh Token, para trocar um refresh token por um access token novo sem envolver o usuário.

A chamada de autorização quer client_id, redirect_uri, response_type=code e scope. state é opcional e você deveria mandar de todo jeito, já que é ele que protege o callback de uma falsificação de requisição entre sites.

Os scopes se escrevem {entity}:read e {entity}:write, separados por vírgula ou espaço, sobre as entidades ads, billing, biz_access, boards, catalogs, pins e user_accounts. Existem variantes secretas para conteúdo privado: boards:read_secret, pins:write_secret. O conselho do próprio Pinterest é “pedir aos seus usuários o mínimo de scopes necessário para atender à necessidade de negócio”, que também é o conselho que encurta a revisão do seu app.

Agora a parte que quebra integrações meses depois. O access token carrega expires_in: 2592000, ou seja, 30 dias. O refresh token antigo tinha refresh_token_expires_in: 31536000, um ano com limite rígido, e o Pinterest não o aceita mais. O refresh token contínuo expira em 60 dias, mas pode ser renovado indefinidamente, então você precisa renová-lo de fato dentro dessa janela para mantê-lo vivo. Apps criados antes de 25 de setembro de 2025 precisam passar continuous_refresh=true para obtê-lo; os criados nessa data ou depois recebem automaticamente. Se perder a janela não existe chamada de reparo, só o fluxo Authorization Code completo de novo, com o usuário na frente da tela. Um token expirado ou inválido responde HTTP 401 com o código de erro de API 2.

Se esse padrão soa familiar, é a mesma forma de todas as outras plataformas: token curto, token longo, expiração silenciosa. Escrevi a versão geral em access tokens de redes sociais.

Criar um board e um pin

Os boards primeiro, porque um pin precisa de um lugar para morar. As chamadas de criação são boards/create e pins/create, e os scopes de que você precisa são boards:read, boards:write, pins:read e pins:write. Os scopes de leitura não são decorativos: para criar um pin você precisa do ID do board ou da seção, e esse ID vem de uma leitura.

Um objeto media_source carrega a imagem ou o vídeo. Os source types documentados são image_url e video_id. Para um pin de imagem, image_url mais board_id, title e description é todo o corpo. Uma URL de imagem válida não é opcional: o Pinterest avisa que “é preciso fornecer uma URL de imagem válida para evitar um 400 Bad Request”.

O vídeo são três chamadas mais uma espera:

1. POST https://api.pinterest.com/v5/media com {"media_type": "video"}. Você recebe um media_id, uma upload_url e um bloco upload_parameters.
2. POST do arquivo para upload_url como multipart/form-data, passando cada chave de upload_parameters como campo de formulário ao lado do .mp4, .mov ou .m4v. Sem cabeçalho Authorization nessa. O sucesso é 204 No Content.
3. GET /v5/media/{media_id} até o status indicar succeeded. O processamento leva alguns segundos, e durante ele creative_type ainda pode dizer REGULAR antes de virar VIDEO.
4. POST /v5/pins com media_source.source_type definido como video_id, o media_id e um cover_image_url. O sucesso é 201 Created com o ID do pin.

Dois tetos para saber antes de desenhar uma importação em massa: 2.000 boards de qualquer tipo, incluindo boards de grupo que você não criou, e 200.000 pins em uma conta pessoal, pins secretos e os seus pins em boards de grupo incluídos. Se você está repinando conteúdo que já existe no Pinterest, pins/save é a chamada certa em vez de pins/create, justamente para não gastar esses limites de entidades.

Uma pegadinha recente: apps registrados em 14 de setembro de 2026 ou depois podem receber um 403 PINNER_DATA_ACCESS_DENIED quando pedem um board ou um pin de um usuário não comercial sem a autorização do Pinterest. Teste com uma conta comercial.

pinterest api python: o formato disso

Não precisa de SDK, requests basta. Esta é a chamada de criação de pin com os campos documentados:

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

Fique de olho em x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset em cada resposta. No Trial eles vão descontando um orçamento diário, então um laço de novas tentativas em uma chamada que falha pode encerrar o seu dia de testes antes do almoço. O Pinterest não publica preço para o acesso à API: os níveis e esses limites são o racionamento.

Onde o Pinterest fica ao lado das outras APIs de plataforma

O Pinterest está na metade fácil do espectro: OAuth comum, entidades simples, chamadas de criação curtas. O que ele cobra em troca é a revisão, o formulário do app, depois o vídeo de demonstração, depois a espera, antes de o que você publica ficar visível para mais alguém. A Meta também cobra uma revisão de app, mas te dá visibilidade pública desde o começo, o que eu conto em o guia da Instagram Graph API. A visão multiplataforma, com os limites por rede, está em o guia de APIs de redes sociais e na referência de limites.

Uma coisa para dizer com franqueza: o PlugKit não publica no Pinterest. Ele cobre Instagram, Facebook, LinkedIn, TikTok, YouTube, X, Threads, Bluesky, WhatsApp e Telegram, e o Pinterest não está nessa lista hoje. Se o Pinterest é o seu canal principal, escreva contra a v5 você mesmo, ou escolha uma ferramenta que o cite.

Perguntas frequentes

A API do Pinterest é gratuita?

O Pinterest não publica preço para o acesso à API. O que ele raciona são requisições e visibilidade: o acesso Trial te limita a 1.000 requisições por dia por app e mantém os boards e pins que você cria visíveis só para quem os cria, enquanto o Standard sobe os limites para 100 requisições por segundo, por usuário e por app. Os endpoints de Ads continuam exigindo uma conta de anúncios.

Como consigo acesso Standard à API do Pinterest?

Primeiro consiga a aprovação Trial do app, fique dentro das Developer Guidelines, depois vá em My apps e escolha Upgrade no cartão do app. O envio pede o seu caso de uso, um link para a sua política de privacidade e um vídeo do seu app completando uma ação da API que mostre o fluxo OAuth. Uma gravação de terminal ou de Postman vale. O Pinterest manda a decisão por e-mail.

Por que ninguém vê os pins que o meu app cria?

Porque o app está no acesso Trial, onde boards e pins ficam visíveis só para quem os cria. É comportamento documentado, não um bug no seu código. Subir para o Standard é o que os torna públicos.

Quanto tempo dura um access token do Pinterest?

O access token dura 30 dias (expires_in: 2592000). O refresh token contínuo expira em 60 dias, mas pode ser renovado indefinidamente, então você precisa renová-lo dentro dessa janela. Apps criados antes de 25 de setembro de 2025 precisam de continuous_refresh=true para obtê-lo. Um token expirado devolve HTTP 401 com o código de erro de API 2.

Posso publicar no Pinterest a partir de um agente de IA?

Só escrevendo contra a v5 você mesmo ou usando uma ferramenta que aceite o Pinterest. Não existe um servidor MCP do Pinterest feito pelo Pinterest, e o PlugKit não cobre o Pinterest. O padrão para as plataformas que ele cobre está em MCP ou API REST para o seu agente.

AB

Antoine BlancoFundador da PlugKit. Gerencia as próprias contas de Instagram, YouTube e X pela API e pelo servidor MCP descritos aqui.