MarkaestroMarkaestro

Développeurs

API publique de publication

Importez des contenus, créez des publications et publiez sur Facebook, Instagram, TikTok, LinkedIn, Threads et Pinterest, le tout limité à un produit via une clé API d'espace de travail. La façon recommandée de s'intégrer est l<connectLink>API Connect</connectLink>, une surface plate sur<code>/api/connect/v1</code> que la plupart des outils de programmation peuvent utiliser telle quelle.

Besoin d'un contrôle total, publication explicite, consultation des exécutions, webhooks signés, traitement par lots, paramètres par canal ? L'API avancée /api/public/v1, plus bas, expose tout cela. Les deux partagent la même authentification, les mêmes produits et le même pipeline de publication ; utilisez uniquement ces routes publiques versionnées (les routes internes de l'application nécessitent une authentification utilisateur Firebase et ne font pas partie du contrat public).

Facebook, Instagram et TikTok sont en publication manuelle par défaut via l'API. Ces canaux utilisent par défaut manual_reminder : Markaestro n'appelle pas l'API de la plateforme et place la publication dans la file « À publier ». Envoyez deliveryMode: "direct_publish" pour utiliser l'API officielle. Sur TikTok, la boîte de réception est utilisée par défaut, sauf si settings.postMode vaut direct_post. LinkedIn, Threads et Pinterest publient de façon programmatique par défaut.

Les espaces de travail peuvent avoir plusieurs produits. Chaque clé API est limitée à un produit à sa création, donc les appels ciblent automatiquement ce produit et les demandes pour tout autre produit sont rejetées.

Vous créez un agent IA ?

Commencez plutôt par le guide pour agents IA. Il contient des schémas d'outils prêts à copier-coller, un résumé pour le system prompt, les règles de nouvelle tentative et de gestion des erreurs dont un agent a besoin, et un démarrage rapide en quatre commandes. Votre agent peut aussi lire directement /llms.txt.

Spécification lisible par machine

Chaque endpoint, chaque format de requête et de réponse et chaque code d'erreur, au format OpenAPI 3.1. Générée à partir des schémas que l'API valide, elle ne peut donc pas décrire une API que nous ne servons pas.

API Connect
Recommandée
La façon par défaut de s'intégrer : une surface plate en snake_case sur /api/connect/v1 que la plupart des outils de programmation peuvent utiliser telle quelle. Elle adapte la convention courante create-upload-url → PUT → post au même espace de travail, à la même authentification, aux mêmes produits et au même pipeline de publication que l'API complète ci-dessous. Configurez l'URL de base du client sur /api/connect et authentifiez-vous avec une clé API d'espace de travail limitée à un produit (permissions posts.read, posts.write, media.write).
GET/api/connect/v1/social-accounts

Liste les destinations Facebook, Instagram, TikTok et LinkedIn connectées sous forme de comptes à plat, chacun étiqueté avec son produit pour que les clients puissent regrouper et distinguer. Chaque canal a son propre chemin, sans diffusion inter-canaux.

GET/api/connect/v1/products

Liste les marques (nom dans l'API : products) avec leurs comptes connectés imbriqués, un sélecteur centré sur la marque.

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

Renvoie une URL d'import signée, à usage unique et de courte durée, plus un id de contenu.

PUT<upload_url>

Envoie les octets bruts de l'image vers l'URL signée. Aucune clé API nécessaire, la signature autorise la requête.

POST/api/connect/v1/posts

Crée un brouillon par compte sélectionné. Définissez is_draft=false avec scheduled_at pour programmer la livraison ; TikTok utilise la transmission vers la boîte de réception du créateur.

GET/api/connect/v1/posts

Liste les publications de l'espace de travail avec statut, texte et URLs de contenu au format plat.

# 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"]
  }'

Chaque compte de /social-accounts est étiqueté avec son product, le nom au format API d'une marque (le même compte peut apparaître dans plusieurs marques), et son id encode productId#destinationId, renvoyez-le tel quel dans social_accounts, et la requête se répartit en une publication par compte. Chaque clé est limitée à une marque, donc elle ne voit et ne publie que sur cette marque. Les publications Facebook, Instagram et TikTok sont en publication manuelle, créées comme brouillons et publiées de façon native par le propriétaire de l'espace de travail depuis la file « À publier » de Markaestro, jamais via l'API de la plateforme. LinkedIn, Threads et Pinterest publient de façon programmatique après une action de publication explicite. Le statut d'une publication est l'un de draft, processing, posted ou failed. Facebook, Instagram, LinkedIn, TikTok et Threads sont chacun une destination dédiée propre, publier sur l'un ne se diffuse jamais vers un autre. Suivez l'état de publication via GET /api/connect/v1/posts.

Avancé : API publique complète

La surface complète de /api/public/v1, publication explicite, exécutions asynchrones, webhooks signés, création par lots et paramètres par canal. Utilisez-la lorsque l'API Connect ne suffit pas.

Meta et TikTok sont en publication manuelle
Les publications Facebook, Instagram et TikTok utilisent par défaut la file manuelle « À publier », aucun appel à l'API de la plateforme, le propriétaire de l'espace de travail publie de façon native et confirme. Vous pouvez activer la publication via API par publication avec deliveryMode.
Instagram Login pris en charge
Les marques peuvent exposer des comptes professionnels Instagram indépendants même sans page Facebook liée.
TikTok propose deux parcours optionnels
La publication via API utilise la boîte de réception par défaut. Définissez settings.postMode sur direct_post avec un niveau de confidentialité pour demander Direct Post si votre application TikTok est approuvée.
Asynchrone par conception
Chaque publication renvoie un id d'exécution. Consultez les exécutions ou abonnez-vous à des webhooks signés plutôt que de supposer une réussite synchrone.
Marques et destinations
Découvrez les marques et les destinations de publication disponibles pour la clé API. Les marques sont appelées products dans le format de l'API, les routes et les corps de requête utilisent products/productId par compatibilité ascendante, et les corps POST acceptent aussi brandId comme alias.
GET/api/public/v1/products

Liste les marques de la clé ainsi que les canaux actuellement disponibles pour chacune.

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

Liste les destinations de publication de cette marque, y compris Instagram Login indépendant, page Facebook, Threads, profil ou page LinkedIn, et destinations TikTok connectées.

Contenu
Importez des images ou des vidéos vers le stockage géré par Markaestro avant de créer des publications.
POST/api/public/v1/media/upload-sessions

Crée une session d'envoi direct de 15 minutes avec le nom, le type et la taille exacte.

PUT<uploadSession.uploadUrl>

Envoie les octets directement au stockage avec le Content-Type renvoyé, sans clé API.

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

Vérifie le type et la taille et renvoie l'actif média ; les sessions terminées peuvent être réessayées.

POST/api/public/v1/media

Import multipart de compatibilité. Renvoie un id d'actif et une URL hébergée.

Publications
Créez, listez, inspectez, publiez et supprimez des publications pour Facebook, Instagram, LinkedIn, Threads, Pinterest et TikTok.
POST/api/public/v1/posts

Crée un brouillon dans l'espace de travail. Facebook, Instagram et TikTok utilisent par défaut la publication manuelle (deliveryMode manual_reminder) ; envoyez deliveryMode direct_publish pour que la publication utilise l'API.

GET/api/public/v1/posts

Liste les publications, des plus récentes aux plus anciennes. Filtrez avec ?status=scheduled pour voir ce qui est programmé, et ?productId= pour limiter à une marque. Une clé limitée à une marque est toujours restreinte à sa propre marque et peut omettre productId.

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

Renvoie le statut actuel de la publication, le mode de livraison et les résultats de publication.

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

Met en file une exécution de publication asynchrone. Les publications manuelles rejoignent la file « À publier » de l'espace de travail pour publication native ; LinkedIn, Threads et Pinterest publient directement ; les publications Meta ayant activé l'option se publient via l'API officielle, et celles de TikTok utilisent la transmission vers la boîte de réception.

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

Supprime la publication de Markaestro. Utilise la permission existante posts.write. Renvoie 400 VALIDATION_POST_IS_PUBLISHING pendant qu'une exécution de publication est en cours. Supprimer une publication déjà publiée ne retire pas la copie active sur la plateforme.

Exécutions et webhooks
Suivez le travail asynchrone par consultation périodique ou livraison de webhooks signés.
GET/api/public/v1/job-runs/:id

Renvoie queued, running, succeeded ou failed.

POST/api/public/v1/webhook-endpoints

Enregistre une destination de webhook, avec un maximum de 25 endpoints actifs par espace.

GET/api/public/v1/webhook-endpoints

Liste les destinations de webhook enregistrées pour la portée de cette clé API.

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

Désactive une destination de webhook.

1. Lister les produits
Découvrez à quels produits cette clé API peut accéder.
curl "$MARKAESTRO_URL/api/public/v1/products" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
2. Inspecter les destinations
Consultez les pages et comptes liés d'un produit avant de créer la publication. Utilisez le destinationId renvoyé lorsqu'un produit a plusieurs destinations, comme un profil LinkedIn plus des pages.
curl "$MARKAESTRO_URL/api/public/v1/products/prod_123/destinations" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
3. Importer un contenu
Chaque publication fait référence à des actifs de contenu importés au préalable.
# 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. Créer une publication
Créez un brouillon à l'aide de ces ids d'actif. Instagram utilise par défaut la publication manuelle ; ajoutez "deliveryMode": "direct_publish" pour que cette publication utilise l'API officielle.
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"
  }'
Exemple TikTok
Les publications TikTok arrivent comme brouillons Markaestro et utilisent par défaut la publication manuelle depuis la file « À publier ». Avec deliveryMode: "platform_inbox" (ou direct_publish), une publication explicite envoie le brouillon dans la boîte de réception du créateur sur 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. Mettre en file une publication
Publier crée une exécution asynchrone. Les publications manuelles (le comportement par défaut de Facebook/Instagram/TikTok) rejoignent la file « À publier » et déclenchent post.action_required ; LinkedIn, Threads, Pinterest et les publications Meta ayant activé l'option se publient directement ; celles de TikTok mettent en file la transmission vers la boîte de réception.
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts/pst_123/publish" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Idempotency-Key: publish-001"
6. Revoir la programmation et annuler
Listez ce qui est programmé pour une marque, puis supprimez tout ce que vous ne voulez plus voir publié. Les deux utilisent des permissions que les clés existantes possèdent déjà : posts.read et 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"
Exemple de payload de webhook
Les livraisons sont signées avec HMAC à l'aide de votre secret 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"
  }
}
Comportement par canal
Règles de validation et de livraison appliquées par l'API publique.

Facebook

Publications texte seul, image ou vidéo. Jusqu'à 10 images ou 1 vidéo par publication. Publication manuelle par défaut ; publication directe en cas d'activation.

Instagram

Au moins une image ou vidéo, jusqu'à 10 éléments. Une seule vidéo se publie comme Reel. Publication manuelle par défaut ; publication directe en cas d'activation.

TikTok

Au moins une image ou une vidéo. Jusqu'à 35 images ou 1 vidéo. Publication manuelle par défaut ; les publications activées vont dans la boîte de réception TikTok du créateur, ou directement sur le profil avec postMode direct_post de TikTok.

LinkedIn

Texte, image simple, vidéo simple, ou publications multi-images organiques jusqu'à 20 images. Ciblez le profil connecté ou une page gérée.

X

Texte, jusqu'à quatre images, un GIF ou une vidéo. Les contrôles de réponse s'appliquent par publication, et la publication est bloquée lorsque le budget de coûts X de l'espace de travail est épuisé.