> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.scheduled.so/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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](https://app.scheduled.so/settings#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 à team@scheduled.so. On t'aide à diagnostiquer 🙌