Markaestro

Desarrolladores

API pública de publicación

Sube contenido, crea publicaciones y publica en Facebook, Instagram, TikTok, LinkedIn, Threads y Pinterest, todo limitado a un producto mediante una clave de API del espacio de trabajo. La forma recomendada de integrarse es la API Connect, una superficie plana en/api/connect/v1 que la mayoría de herramientas de programación pueden usar tal cual.

¿Necesitas control total, publicación explícita, consulta de ejecuciones, webhooks firmados, procesamiento por lotes, configuración por canal? La API avanzada /api/public/v1, más abajo, expone todo eso. Ambas comparten la misma autenticación, productos y flujo de publicación; usa únicamente estas rutas públicas versionadas (las rutas internas de la aplicación requieren autenticación de usuario de Firebase y no forman parte del contrato público).

Facebook, Instagram y TikTok son de publicación manual en la API por defecto. Las publicaciones para esos canales usan por defecto manual_reminder: Markaestro no llama a la API de la plataforma y mueve la publicación a la cola «Por publicar». Envía deliveryMode: "direct_publish" para usar la API oficial. En TikTok se usa por defecto el traspaso a la bandeja de entrada, salvo que settings.postMode sea direct_post. LinkedIn, Threads y Pinterest publican de forma programática por defecto.

Los espacios de trabajo pueden tener varios productos. Al crear una clave de API, o bien la vinculas a un producto, de modo que las llamadas apuntan a ese producto automáticamente y se rechazan las solicitudes para cualquier otro, o bien la conviertes en una clave de todas las marcas que indica el producto en cada solicitud.

¿Estás creando un agente de IA?

Empieza mejor con la guía para agentes de IA. Incluye esquemas de herramientas listos para copiar y pegar, un resumen para el system prompt, las reglas de reintento y gestión de errores que necesita un agente, y una guía rápida de cuatro comandos. Tu agente también puede leer /llms.txt directamente.

Especificación legible por máquinas

Cada endpoint, formato de petición y respuesta, y código de error, en OpenAPI 3.1. Se genera a partir de los mismos esquemas con los que valida la API, así que no puede describir una API que no servimos.

API Connect
Recomendada
La forma predeterminada de integrarse: una superficie plana en /api/connect/v1 que la mayoría de herramientas de programación pueden usar tal cual. Adapta la convención habitual create-upload-url → PUT → post al mismo espacio de trabajo, autenticación, productos y flujo de publicación que la API completa de más abajo. Configura la URL base del cliente en /api/connect y autentícate con una clave de API del espacio de trabajo limitada a un producto (permisos posts.read, posts.write, media.write).
GET/api/connect/v1/social-accounts

Lista los destinos conectados de Facebook, Instagram, TikTok y LinkedIn como cuentas planas, cada una etiquetada con su producto para que los clientes puedan agrupar y distinguir. Cada canal tiene su propia ruta, sin distribución entre canales.

GET/api/connect/v1/products

Lista las marcas (nombre en la API: products) con sus cuentas conectadas anidadas, un selector centrado en la marca.

POST/api/connect/v1/media/create-upload-url

Devuelve una URL de subida firmada, de un solo uso y de corta duración, además de un id de contenido.

PUT<upload_url>

Sube los bytes de la imagen sin procesar a la URL firmada. No hace falta clave de API, la firma autoriza la petición.

POST/api/connect/v1/posts

Crea un borrador por cada cuenta seleccionada. Define is_draft=false con scheduled_at para programar la entrega; TikTok usa el traspaso a la bandeja de entrada del creador.

GET/api/connect/v1/posts

Lista las publicaciones del espacio de trabajo con estado, texto y URLs de contenido en formato plano.

# 1. List connected accounts
curl "$MARKAESTRO_URL/api/connect/v1/social-accounts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

# 2. Request a signed upload url, then PUT the bytes
curl -X POST "$MARKAESTRO_URL/api/connect/v1/media/create-upload-url" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mime_type": "image/png", "size_bytes": 184320, "name": "slide-1.png" }'
curl -X PUT "<upload_url>" -H "Content-Type: image/png" --data-binary @slide-1.png

# 3. Create a draft post for one or more accounts
curl -X POST "$MARKAESTRO_URL/api/connect/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "New drop",
    "media": ["ast_111", "ast_222"],
    "social_accounts": ["prod_123#instagram:instagram:ig_123"]
  }'

Cada cuenta de /social-accounts está etiquetada con su product, el nombre en formato API de una marca (la misma cuenta puede aparecer en varias marcas), y su id codifica productId#destinationId, pásalo de vuelta tal cual en social_accounts, y la solicitud se distribuye en una publicación por cuenta. Cada clave está limitada a una marca, así que solo ve y publica en esa marca. Las publicaciones de Facebook, Instagram y TikTok son de publicación manual, se crean como borradores y las publica de forma nativa el propietario del espacio de trabajo desde la cola «Por publicar» de Markaestro, nunca a través de la API de la plataforma. LinkedIn, Threads y Pinterest publican de forma programática tras una acción de publicación explícita. El estado de una publicación es uno de draft, processing, posted o failed. Facebook, Instagram, LinkedIn, TikTok y Threads son cada uno un destino dedicado propio, publicar en uno nunca se distribuye a otro. Consulta el estado de publicación mediante GET /api/connect/v1/posts.

Avanzado: API pública completa

La superficie completa de /api/public/v1, publicación explícita, ejecuciones asíncronas, webhooks firmados, creación por lotes y configuración por canal. Úsala cuando la API Connect no sea suficiente.

Meta y TikTok son de publicación manual
Las publicaciones de Facebook, Instagram y TikTok usan por defecto la cola manual «Por publicar», sin llamada a la API de la plataforma, el propietario del espacio de trabajo publica de forma nativa y confirma. Puedes optar por la publicación vía API en cada publicación con deliveryMode.
Compatible con Instagram Login
Las marcas pueden exponer cuentas profesionales de Instagram independientes incluso sin tener una página de Facebook vinculada.
TikTok admite dos rutas opcionales
La publicación vía API usa la bandeja de entrada por defecto. Define settings.postMode como direct_post con un nivel de privacidad para solicitar Publicación Directa si tu app de TikTok está aprobada.
Asíncrona por diseño
Cada publicación devuelve un id de ejecución. Consulta las ejecuciones o suscríbete a webhooks firmados en lugar de asumir una finalización síncrona.
Marcas y destinos
Descubre las marcas y los destinos de publicación disponibles para la clave de API. Las marcas se llaman products en el formato de la API, las rutas y los cuerpos usan products/productId por compatibilidad con versiones anteriores, y los cuerpos POST también aceptan brandId como alias.
GET/api/public/v1/products

Lista las marcas de la clave junto con los canales disponibles actualmente para cada una.

GET/api/public/v1/products/:id/destinations

Lista los destinos de publicación de esa marca, incluyendo Instagram Login independiente, página de Facebook, Threads, perfil o página de LinkedIn, y destinos de TikTok conectados.

Contenido
Sube imágenes o vídeos al almacenamiento gestionado por Markaestro antes de crear publicaciones.
POST/api/public/v1/media/upload-sessions

Crea una sesión de subida directa de 15 minutos con nombre, tipo y tamaño exacto.

PUT<uploadSession.uploadUrl>

Sube los bytes directamente al almacenamiento con el Content-Type devuelto; no envíes la clave API.

POST/api/public/v1/media/upload-sessions/:id/finalize

Verifica tipo y tamaño y devuelve el activo multimedia; las sesiones completadas admiten reintentos seguros.

POST/api/public/v1/media

Subida multipart de compatibilidad. Devuelve un id de activo y una URL alojada.

Publicaciones
Crea, lista, inspecciona, publica y elimina publicaciones para Facebook, Instagram, LinkedIn, Threads, Pinterest y TikTok.
POST/api/public/v1/posts

Crea un borrador en el espacio de trabajo. Facebook, Instagram y TikTok usan por defecto la publicación manual (deliveryMode manual_reminder); envía deliveryMode direct_publish para que la publicación use la API.

GET/api/public/v1/posts

Lista publicaciones, de más reciente a más antigua. Filtra con ?status=scheduled para ver lo programado, y ?productId= para limitar a una marca. Una clave limitada a una marca siempre está restringida a su propia marca y puede omitir productId.

GET/api/public/v1/posts/:id

Devuelve el estado actual de la publicación, el modo de entrega y los resultados de publicación.

POST/api/public/v1/posts/:id/publish

Encola una ejecución de publicación asíncrona. Las publicaciones manuales van a la cola «Por publicar» del espacio de trabajo para publicación nativa; LinkedIn, Threads y Pinterest publican directamente; las publicaciones de Meta que optaron por ello se publican vía API oficial, y las de TikTok que optaron por ello usan el traspaso a la bandeja de entrada.

DELETE/api/public/v1/posts/:id

Elimina la publicación de Markaestro. Usa el permiso existente posts.write. Devuelve 400 VALIDATION_POST_IS_PUBLISHING mientras una ejecución de publicación está en curso. Eliminar una publicación ya publicada no retira la copia activa en la plataforma.

Ejecuciones y webhooks
Haz seguimiento del trabajo asíncrono mediante consultas periódicas o entrega de webhooks firmados.
GET/api/public/v1/job-runs/:id

Devuelve queued, running, succeeded o failed.

POST/api/public/v1/webhook-endpoints

Registra un destino de webhook, hasta 25 endpoints activos por espacio de trabajo.

GET/api/public/v1/webhook-endpoints

Lista los destinos de webhook registrados para el alcance de esa clave de API.

DELETE/api/public/v1/webhook-endpoints/:id

Desactiva un destino de webhook.

1. Listar productos
Descubre a qué productos puede acceder esta clave de API.
curl "$MARKAESTRO_URL/api/public/v1/products" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
2. Inspeccionar destinos
Consulta las páginas y cuentas vinculadas de un producto antes de crear la publicación. Usa el destinationId devuelto cuando un producto tenga varios destinos, como un perfil de LinkedIn más páginas.
curl "$MARKAESTRO_URL/api/public/v1/products/prod_123/destinations" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
3. Subir contenido
Cada publicación hace referencia a activos de contenido subidos previamente.
# 1. Create a 15-minute upload session
UPLOAD=$(curl -s -X POST "$MARKAESTRO_URL/api/public/v1/media/upload-sessions" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"launch-1.jpg","contentType":"image/jpeg","sizeBytes":184320}')

# 2. PUT bytes directly to uploadSession.uploadUrl with its returned headers
curl -X PUT "<upload_url>" -H "Content-Type: image/jpeg" --data-binary @launch-1.jpg

# 3. Finalize; the response contains asset.id for mediaAssetIds
curl -X POST "$MARKAESTRO_URL/api/public/v1/media/upload-sessions/<session_id>/finalize" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
4. Crear una publicación
Crea un borrador usando esos ids de activo. Instagram usa por defecto la publicación manual; añade "deliveryMode": "direct_publish" para que esta publicación use la API oficial.
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-001" \
  -d '{
    "channel": "instagram",
    "caption": "Launch day carousel",
    "mediaAssetIds": ["ast_123", "ast_124"],
    "productId": "prod_123",
    "destinationId": "instagram:instagram:ig_123"
  }'
Ejemplo de TikTok
Las publicaciones de TikTok llegan como borradores de Markaestro y usan por defecto la publicación manual desde la cola «Por publicar». Con deliveryMode: "platform_inbox" (o direct_publish), una publicación explícita envía el borrador a la bandeja de entrada del creador en TikTok.
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-tt-001" \
  -d '{
    "channel": "tiktok",
    "caption": "Spring drop teaser",
    "mediaAssetIds": ["ast_vid_123"],
    "productId": "prod_123",
    "destinationId": "tiktok:tiktok:tt_open_123"
  }'
5. Encolar publicación
Publicar crea una ejecución asíncrona. Las publicaciones manuales (el valor por defecto de Facebook/Instagram/TikTok) pasan a la cola «Por publicar» y disparan post.action_required; LinkedIn, Threads, Pinterest y las publicaciones de Meta que optaron por ello se publican directamente; las de TikTok que optaron por ello encolan el traspaso a la bandeja de entrada.
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts/pst_123/publish" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Idempotency-Key: publish-001"
6. Revisar la programación y cancelar
Lista lo que está programado para una marca, y elimina lo que ya no quieras que se publique. Ambas usan permisos que las claves existentes ya tienen: posts.read y posts.write.
# The key is already bound to one brand
curl "$MARKAESTRO_URL/api/public/v1/posts?status=scheduled&limit=100" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

# Cancel one
curl -X DELETE "$MARKAESTRO_URL/api/public/v1/posts/pst_123" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
Ejemplo de payload de webhook
Las entregas se firman con HMAC usando tu secreto de webhook.
{
  "id": "evt_123",
  "type": "post.action_required",
  "createdAt": "2026-04-08T18:06:10.000Z",
  "workspaceId": "ws_123",
  "data": {
    "postId": "pst_123",
    "channel": "instagram",
    "status": "platform_action_required",
    "nextAction": "post_manually_from_reminder"
  }
}
Comportamiento por canal
Reglas de validación y entrega aplicadas por la API pública.

Facebook

Publicaciones de solo texto, imagen o vídeo. Hasta 10 imágenes o 1 vídeo por publicación. Publicación manual por defecto; publicación directa si se opta por ello.

Instagram

Al menos una imagen o vídeo, hasta 10 elementos. Un solo vídeo se publica como Reel. Publicación manual por defecto; publicación directa si se opta por ello.

TikTok

Al menos una imagen o un vídeo. Hasta 35 imágenes o 1 vídeo. Publicación manual por defecto; las publicaciones activadas van a la bandeja de entrada de TikTok del creador, o directamente al perfil con postMode direct_post de TikTok.

LinkedIn

Texto, imagen individual, vídeo individual, o publicaciones multiimagen orgánicas de hasta 20 imágenes. Dirígete al perfil conectado o a una página gestionada.

X

Texto, hasta cuatro imágenes, un GIF o un vídeo. Los controles de respuesta se aplican por publicación y la publicación se bloquea cuando se agota el presupuesto de costes de X del espacio de trabajo.