API de Pinterest: pines, tableros y la aprobación que necesitas antes

La API de Pinterest v5 vive en https://api.pinterest.com/v5. Puedes crear tableros y pines desde el primer día, pero con acceso Trial solo los ves tú, y Pinterest quiere un vídeo de demostración que muestre el flujo OAuth antes de conceder el Standard. Aquí tienes todo el recorrido, leído el 11 de noviembre de 2026.

Qué te da la API y en qué orden te lo da

Pinterest expone dos mundos detrás de una sola URL base: contenido orgánico (tableros, pines, cuentas de usuario, subidas de archivos) y publicidad (campañas, audiencias, catálogos, informes). Los dos usan el mismo bearer token, filtrado por scopes, y los dos están racionados por el nivel de acceso en el que está tu app.

El orden importa, porque casi nadie lo lee antes. No consigues una clave de API, escribes código y publicas. Consigues una app aprobada en Trial, construyes contra límites contados por día y no por minuto, y luego demuestras en vídeo que funciona antes de que lo que creas sea visible para alguien más.

Acceso Trial frente a acceso Standard

Dos niveles, no hay más. Según la guía de niveles de acceso de Pinterest, leída hoy:

Lee dos veces la fila de visibilidad. En Trial, un pin que crea tu integración es un pin que solo ves tú. Todos los tickets de «funciona pero no apareció nada» empiezan ahí.

Para subir: la app ya tiene que estar aprobada en Trial y cumplir las Developer Guidelines, y envías un vídeo de tu app completando una acción con la API de Pinterest que muestre el flujo OAuth. Vale incluso si eres el único usuario, y se aceptan grabaciones de pantalla de terminal o de Postman. Pinterest verifica tu caso de uso y el enlace a tu política de privacidad durante el envío. Vas a My apps, eliges Upgrade en la tarjeta de la app, confirmas la información, subes el vídeo y envías. No hay plazo publicado: las solicitudes se «revisan regularmente» y recibes la decisión por correo. Si te la deniegan y reclamas con un ticket al Help Center, cuenta «unos días».

Conseguir la app, para empezar

Antes de todo eso: crea una cuenta de empresa de Pinterest o entra en la tuya, verifica tu correo, acepta los Developer Terms of Service en My apps y envía el formulario de solicitud de app. Pinterest la revisa y te envía por correo la aprobación o el rechazo. La aprobación Trial también te da test tokens limitados por producto, que caducan a las 24 horas y sirven para probar endpoints, no para dejar nada funcionando.

También hay un sandbox, el sitio honesto para aprender la forma de las peticiones sin quemar 300 escrituras al día.

OAuth, scopes y el token que muere a los 60 días

Tres grants, y solo uno te da toda la API:

• Authorization Code, para actuar en nombre de un usuario. El usuario aprueba los scopes en https://www.pinterest.com/oauth/, vuelve a tu redirect_uri con un código, y tu servidor lo canjea en oauth/token. Es el único grant que cubre toda la API.
• Client Credentials, para tu propia cuenta de desarrollador. Exige autenticación en dos pasos y no puede llegar a algunos endpoints sensibles.
• Refresh Token, para cambiar un refresh token por un access token nuevo sin que intervenga el usuario.

La llamada de autorización quiere client_id, redirect_uri, response_type=code y scope. state es opcional y deberías enviarlo igual, porque es lo que protege el callback de una falsificación de petición entre sitios.

Los scopes se escriben {entity}:read y {entity}:write, separados por coma o espacio, sobre las entidades ads, billing, biz_access, boards, catalogs, pins y user_accounts. Existen variantes secretas para el contenido privado: boards:read_secret, pins:write_secret. El consejo de Pinterest es «pide a tus usuarios el mínimo de scopes necesario para cubrir su necesidad de negocio», que además es el consejo que acorta la revisión de tu app.

Ahora la parte que rompe integraciones meses después. El access token lleva expires_in: 2592000, o sea 30 días. El refresh token antiguo tenía refresh_token_expires_in: 31536000, un año con un tope duro, y Pinterest ya no lo admite. El refresh token continuo caduca a los 60 días pero se puede refrescar indefinidamente, así que hay que refrescarlo de verdad dentro de esa ventana para mantenerlo vivo. Las apps creadas antes del 25 de septiembre de 2025 deben pasar continuous_refresh=true para conseguirlo; las creadas en esa fecha o después lo reciben automáticamente. Si pierdes la ventana no hay llamada de reparación, solo el flujo Authorization Code completo otra vez, con el usuario delante de la pantalla. Un token caducado o inválido responde HTTP 401 con el código de error de API 2.

Si el patrón te suena, es la misma forma que en todas las demás plataformas: token corto, token largo, caducidad silenciosa. Escribí la versión general en access tokens de redes sociales.

Crear un tablero y un pin

Los tableros primero, porque un pin necesita un sitio donde vivir. Las llamadas de creación son boards/create y pins/create, y los scopes que necesitas son boards:read, boards:write, pins:read y pins:write. Los scopes de lectura no son decorativos: para crear un pin necesitas el ID del tablero o de la sección, y ese ID viene de una lectura.

Un objeto media_source lleva la imagen o el vídeo. Los source types documentados son image_url y video_id. Para un pin de imagen, image_url más board_id, title y description es todo el cuerpo. Una URL de imagen válida no es opcional: Pinterest avisa de que «hay que proporcionar una URL de imagen válida para evitar un 400 Bad Request».

El vídeo son tres llamadas más una espera:

1. POST https://api.pinterest.com/v5/media con {"media_type": "video"}. Recibes un media_id, una upload_url y un bloque upload_parameters.
2. POST el archivo a upload_url como multipart/form-data, pasando cada clave de upload_parameters como campo de formulario junto al .mp4, .mov o .m4v. Sin cabecera Authorization en esta. El éxito es 204 No Content.
3. GET /v5/media/{media_id} hasta que el estado indique succeeded. El procesado tarda unos segundos, y mientras ocurre creative_type puede seguir diciendo REGULAR antes de pasar a VIDEO.
4. POST /v5/pins con media_source.source_type puesto en video_id, el media_id y un cover_image_url. El éxito es 201 Created con el ID del pin.

Dos techos que conviene saber antes de diseñar una importación masiva: 2.000 tableros de cualquier tipo, incluidos los tableros de grupo que no creaste tú, y 200.000 pines en una cuenta personal, pines secretos y tus pines en tableros de grupo incluidos. Si estás repineando contenido que ya existe en Pinterest, pins/save es la llamada correcta en lugar de pins/create, precisamente para no gastar esos límites de entidades.

Una trampa reciente: las apps registradas el 14 de septiembre de 2026 o después pueden recibir un 403 PINNER_DATA_ACCESS_DENIED cuando piden un tablero o un pin de un usuario no empresarial sin la autorización de Pinterest. Haz las pruebas con una cuenta de empresa.

pinterest api python: la forma que tiene

No hace falta SDK, con requests basta. Esta es la llamada de creación de pin con los 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())

Vigila x-ratelimit-limit, x-ratelimit-remaining y x-ratelimit-reset en cada respuesta. En Trial van descontando un presupuesto diario, así que un bucle de reintentos sobre una llamada que falla puede terminar tu día de pruebas antes de comer. Pinterest no publica un precio para el acceso a la API: los niveles y estos límites son el racionamiento.

Dónde queda Pinterest al lado de las otras APIs de plataformas

Pinterest está en la mitad fácil del espectro: OAuth normal, entidades simples, llamadas de creación cortas. Lo que cobra a cambio es la revisión, el formulario de app, luego el vídeo de demostración, luego la espera, antes de que lo que publiques lo vea alguien más. Meta también cobra una revisión de app pero te da visibilidad pública desde el principio, algo que cuento en la guía de la Instagram Graph API. La vista multiplataforma, límites por red incluidos, está en la guía de APIs de redes sociales y en la referencia de límites.

Una cosa que hay que decir claro: PlugKit no publica en Pinterest. Cubre Instagram, Facebook, LinkedIn, TikTok, YouTube, X, Threads, Bluesky, WhatsApp y Telegram, y Pinterest no está hoy en esa lista. Si Pinterest es tu canal principal, escribe contra v5 tú mismo o coge una herramienta que lo nombre.

Preguntas frecuentes

¿La API de Pinterest es gratis?

Pinterest no publica un precio para el acceso a la API. Lo que raciona son las peticiones y la visibilidad: el acceso Trial te limita a 1.000 peticiones al día por app y mantiene los tableros y los pines que creas visibles solo para quien los crea, mientras que el Standard sube los límites a 100 peticiones por segundo, por usuario y por app. Los endpoints de Ads siguen necesitando una cuenta publicitaria.

¿Cómo consigo acceso Standard a la API de Pinterest?

Consigue primero la aprobación Trial de la app, respeta las Developer Guidelines y luego ve a My apps y elige Upgrade en la tarjeta de la app. El envío pide tu caso de uso, un enlace a tu política de privacidad y un vídeo de tu app completando una acción de la API que muestre el flujo OAuth. Vale una grabación de terminal o de Postman. Pinterest envía la decisión por correo.

¿Por qué nadie ve los pines que crea mi app?

Porque la app está en acceso Trial, donde los tableros y los pines solo los ve quien los crea. Es un comportamiento documentado, no un bug de tu código. Pasar a Standard es lo que los hace públicos.

¿Cuánto dura un access token de Pinterest?

El access token dura 30 días (expires_in: 2592000). El refresh token continuo caduca a los 60 días pero se puede refrescar indefinidamente, así que tienes que refrescarlo dentro de esa ventana. Las apps creadas antes del 25 de septiembre de 2025 necesitan continuous_refresh=true para conseguirlo. Un token caducado devuelve HTTP 401 con el código de error de API 2.

¿Puedo publicar en Pinterest desde un agente de IA?

Solo escribiendo contra v5 tú mismo o usando una herramienta que admita Pinterest. No hay un servidor MCP de Pinterest hecho por Pinterest, y PlugKit no cubre Pinterest. El patrón para las plataformas que sí cubre está en MCP o API REST para tu agente.

AB

Antoine BlancoFundador de PlugKit. Gestiona sus propias cuentas de Instagram, YouTube y X a través de la API y del servidor MCP que se describen aquí.