Articles sur : API & MCP
Cet article est aussi disponible en :

Utiliser l'API de Scheduled : token, scopes, posts, médias et webhooks

Scheduled a une API REST, le mĂȘme moteur que celui qu'utilise Claude. Utilise-la pour brancher Scheduled Ă  Zapier, n8n, Make ou tes propres scripts : programmer des posts, envoyer des mĂ©dias, lire tes stats et ĂȘtre prĂ©venu quand un post part.


L'API est incluse dans les plans Pro et Agency, essais compris. Chaque post créé par l'API est écrit dans ton calendrier Notion, comme n'importe quelle autre carte.


Avant de commencer


  • URL de base : https://api.scheduled.so/v1
  • Authentification : un Personal Access Token. CrĂ©e-en un dans ParamĂštres → API en ne donnant que les permissions dont ton outil a besoin. Envoie-le dans Authorization: Bearer <token>.
  • Format : JSON en entrĂ©e et en sortie. Les erreurs ressemblent toujours Ă  { "error": "...", "message": "...", "request_id": "..." } : garde le request_id si tu nous Ă©cris.
  • Limites : 600 requĂȘtes par minute et par token.


Traite le token comme un mot de passe. Il n'est affichĂ© qu'une fois, et tu peux le rĂ©voquer Ă  tout moment depuis la mĂȘme page.


Permissions (scopes)


  • read:calendars, read:connections : lister tes calendriers et comptes connectĂ©s
  • read:posts : lister et lire des posts
  • write:posts : crĂ©er et modifier des posts, relancer un calendrier, vĂ©rifier des tags LinkedIn
  • delete:posts : annuler des posts
  • read:analytics : stats, meilleurs posts, comparaisons, meilleurs crĂ©neaux
  • write:media : envoyer et lire des mĂ©dias


Programme ton premier post


curl -X POST https://api.scheduled.so/v1/posts \
-H "Authorization: Bearer $TOKEN" \
-H "Idempotency-Key: lancement-2026-11-20" \
-H "Content-Type: application/json" \
-d '{
"scheduled_for": "2026-11-20T09:00:00+01:00",
"social_connection_labels": ["LI@ton-nom"],
"title": "Post de lancement (interne)",
"text": "On vient de le sortir."
}'


  • social_connection_labels sont les labels affichĂ©s dans l'app (ou utilise social_connection_ids). Avec un seul calendrier actif tu peux omettre le calendrier, sinon passe calendar_name ou calendar_id.
  • title est interne (affichĂ© dans Notion). Le texte publiĂ© est text.
  • Idempotency-Key rend l'appel sĂ»r Ă  rejouer : la mĂȘme clĂ© renvoie le mĂȘme rĂ©sultat au lieu de crĂ©er un second post.
  • Un 201 veut dire que la carte existe dĂ©jĂ  dans Notion. Un 202 veut dire qu'elle est créée mais que la synchro rattrape encore : ne la renvoie pas, lis-la avec GET /v1/posts.


Ajouter des médias, une couverture et un titre de vidéo


  1. POST /v1/media avec filename, mime_type et size_bytes. Tu reçois une URL d'envoi.
  2. PUT le fichier vers cette URL.
  3. Utilise l'identifiant media_... reçu dans media_ids à la création du post.


Pour une vidĂ©o, ajoute une couverture (un JPEG ou PNG envoyĂ© de la mĂȘme façon) et un titre :


"media_ids": ["media_<video>"],
"cover_media_id": "media_<image>",
"video_title": "Pourquoi MQTT ?"


  • La couverture n'est pas dans media_ids : une vidĂ©o plus une image lĂ -dedans forme un post multi-mĂ©dias, que YouTube refuse.
  • video_title est utilisĂ© sur YouTube (100 caractĂšres max) et LinkedIn.
  • La couverture demande la fonctionnalitĂ© Cover image sur la base Notion du calendrier, sinon tu reçois cover_property_missing et rien n'est créé.
  • Tu peux changer ou retirer la couverture plus tard avec PATCH /v1/posts/:id et cover_media_id (un identifiant de mĂ©dia, ou null).
  • Tu peux changer le titre de la vidĂ©o plus tard avec PATCH /v1/posts/:id et video_title (1 Ă  100 caractĂšres, ou null pour l'effacer). Un post sans bloc vidĂ©o est refusĂ© avec video_not_found et rien ne change.
  • Pour YouTube, choisis comment la vidĂ©o est publiĂ©e avec visibility : public, unlisted ou private (public si tu l'omets). Il faut la fonctionnalitĂ© VisibilitĂ© YouTube sur la base Notion du calendrier, sinon tu reçois visibility_property_missing et rien n'est créé. PATCH /v1/posts/:id peut la changer tant que le post n'est pas publiĂ©, ensuite il rĂ©pond already_published : passe par YouTube Studio. Les vidĂ©os non rĂ©pertoriĂ©es ou privĂ©es n'ont pas de statistiques dans Scheduled.


Vérifier un tag LinkedIn avant de poster


POST /v1/linkedin/mentions/check avec { "profile_urls": ["https://www.linkedin.com/in/jane-doe"] } (profils ou pages entreprise, 5 liens maximum). Chaque lien revient taggable (avec le nom), not_taggable ou unknown. C'est limité à 60 vérifications par heure. taggable veut dire que Scheduled sait construire le tag, LinkedIn peut encore refuser de l'afficher.


Vérifier un post avant de le créer


Tu n'es pas sĂ»r qu'un post va passer (un texte trop long pour X, un post sans mĂ©dia sur Instagram, un format de mĂ©dia) ? Envoie le mĂȘme corps avec "dry_run": true. Scheduled lance les mĂȘmes contrĂŽles que pour un vrai post et rĂ©pond sans rien crĂ©er dans Notion ni rien programmer :


{ "dry_run": true, "valid": false, "error": { "code": "x_limit_exceeded", "message": "..." } }


  • valid: true veut dire que le post serait acceptĂ© tel quel. Renvoie-le sans dry_run pour le crĂ©er. L'appel rĂ©pond 200 mĂȘme quand le post n'est pas valide (calendrier ou compte inconnu compris) : lis valid.
  • Ça ne vĂ©rifie pas ce qui n'existe qu'une fois la carte dans Notion (options de reel ou de story, propriĂ©tĂ©s sc_*), ni ce qui peut Ă©chouer Ă  la publication. La rĂ©ponse le liste dans not_checked.
  • Un dry run n'utilise jamais ton Idempotency-Key, tu peux donc rĂ©utiliser la mĂȘme clĂ© pour l'appel rĂ©el. Il est limitĂ© Ă  20 par minute.


Les principaux endpoints


  • GET /posts, GET /posts/:id : lister (pagination par curseur) et lire des posts
  • POST /posts, PATCH /posts/:id : crĂ©er et modifier un post
  • POST /posts/:id/duplicate : copier un post vers une autre date
  • DELETE /posts/:id : annuler un post
  • GET /calendars, GET /connections : tes calendriers et comptes
  • GET /analytics/top-posts, /analytics/compare, /analytics/post/:id : stats
  • GET /scheduling/best-times, /scheduling/next-slot : quand poster
  • POST /media, GET /media/:id : envoyer et vĂ©rifier des mĂ©dias


Être prĂ©venu avec les webhooks


CrĂ©e un endpoint avec POST /v1/webhook_endpoints et tu reçois post.published, post.failed et post.sync_failed. Chaque appel est signĂ© : vĂ©rifie l'en-tĂȘte X-Scheduled-Signature (t=<unix>,v1=<hmac>) avec le secret affichĂ© Ă  la crĂ©ation de l'endpoint, et utilise X-Scheduled-Delivery pour ignorer les doublons.


Ce que l'API ne sait pas faire (pour l'instant)


  • Changer le texte ou les mĂ©dias d'un post existant : annule-le et crĂ©es-en un nouveau.


À retenir


  • Personal Access Token, avec scopes, rĂ©vocable, 600 requĂȘtes par minute.
  • Chaque post atterrit dans ton calendrier Notion.
  • Envoie un Idempotency-Key Ă  la crĂ©ation pour qu'un nouvel essai ne duplique jamais un post.
  • La couverture d'une vidĂ©o est un cover_media_id Ă  part, jamais dans media_ids.
  • Envoie dry_run: true pour vĂ©rifier un post avant de le crĂ©er.


Tu as suivi toutes les Ă©tapes et ça ne marche toujours pas ? Écris-nous via le chat en bas Ă  droite ou Ă  [email protected]. On t'aide Ă  diagnostiquer 🙌

Mis Ă  jour le : 18/11/2026

Cet article a-t-il répondu à vos questions ?

Partagez vos commentaires

Annuler

Merci !