- Documentation
- API · Version 1.0
- Publications
Publications
Sur cette page
Une publication porte un contenu commun et une cible par destination choisie. Chaque cible a son propre statut, son propre texte et sa propre issue : Facebook peut réussir pendant qu'Instagram échoue, et relancer Instagram ne republie pas sur Facebook.
La ressource
{
"data": {
"id": "pub_01k4b8y5t2v9h6p8w0y2z4b6c8",
"title": null,
"content": "Notre nouvel article est en ligne.",
"link_url": "https://example.com/article",
"status": "scheduled",
"external_reference": "article-42",
"tags": ["PainAuLevain"],
"media": [
{ "id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "Une miche de pain au levain sur une planche." }
],
"scheduled_at": "2026-10-01T09:14:22+00:00",
"published_at": null,
"timezone": "Europe/Paris",
"targets": [
{
"destination_id": "dst_01k4b8x2q9r7f3m5t6v8w0y2z4",
"network": "facebook",
"provider": "meta",
"status": "pending",
"content": "Notre nouvel article est en ligne.",
"link_url": "https://example.com/article",
"tags": ["PainAuLevain"],
"title": null,
"first_comment": null,
"media": [
{ "id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "Une miche de pain au levain sur une planche." }
],
"scheduled_at": null,
"published_at": null,
"external_url": null,
"attempts": 0,
"error": null,
"metrics": null
}
],
"created_at": "2026-10-01T09:14:22+00:00"
}
}
| Champ | Sens |
|---|---|
title |
Titre interne. Il n'est envoyé sur aucun réseau. |
content |
Texte commun. |
link_url |
Lien commun. |
status |
Statut agrégé, voir Statuts. |
external_reference |
Votre propre référence, telle que vous l'avez envoyée. |
tags |
Hashtags communs, mis en forme et sans #. Voir Les tags. |
media |
Images communes, dans l'ordre, avec leur texte alternatif. |
scheduled_at |
Date de départ prévue. Vaut l'instant de création pour une publication immédiate, null pour un brouillon ou une publication soumise à validation. |
published_at |
Date de publication. |
timezone |
Fuseau de la publication, celui de la marque par défaut. |
targets[].destination_id |
La destination visée. Reliez une cible à sa destination par ce champ. |
targets[].network |
Le nom court du réseau (facebook, instagram, linkedin, threads, pinterest). |
targets[].provider |
Le fournisseur de la connexion : meta pour Facebook et Instagram, sinon le même nom que le réseau. |
targets[].content |
Le texte réellement envoyé sur cette destination. |
targets[].link_url, tags, title, first_comment, media |
Les valeurs réellement retenues pour cette destination : la surcharge du réseau s'il y en a une, la valeur commune sinon, déjà filtrées par ce que le réseau accepte. |
targets[].external_url |
L'adresse publique du post, une fois publié. |
targets[].attempts |
Nombre de tentatives d'envoi. |
targets[].error |
{ "code", "message" } de la dernière erreur, ou null. Nos propres refus sont en anglais ; ceux du réseau gardent ses mots (voir Erreurs). |
targets[].metrics |
Statistiques du dernier jalon relevé, ou null. Voir Statistiques. |
Les valeurs d'une cible sont figées à la création : ce qui part est ce que la cible porte.
Le code et le message d'erreur d'une cible viennent du réseau et sont transmis tels quels : les reformuler ferait perdre ce qui permet de corriger.
POST /publications
Crée une publication et ses cibles.
Périmètre requis : publications:create.
En-tête requis : Idempotency-Key (voir Idempotence).
| Champ | Type | Requis | Note |
|---|---|---|---|
destination_ids |
liste de dst_… |
oui | Au moins un, 100 au plus, sans doublon. |
content |
texte | non | Texte commun. |
title |
texte (255) | non | Titre interne, jamais publié. |
link_url |
URL absolue (2048) | non | Ignoré sur une destination qui n'accepte pas les liens (Instagram). |
media |
liste d'objets {id, alt_text} |
non | 10 au plus, sans doublon. alt_text : 1 000 caractères au plus. |
media_ids |
liste de med_… |
non | Ancienne forme, sans texte alternatif. 10 au plus. Exclusif de media. |
tags |
liste de textes | non | 30 au plus, 100 caractères chacun une fois mis en forme. |
first_comment |
texte (8000) | non | Accepté, mais aucun réseau ne publie de premier commentaire aujourd'hui : il est ignoré. |
mastodon |
objet | non | Réglages des destinations Mastodon : content_warning (texte, 500, l'avertissement derrière lequel le texte est replié, compté dans la limite du serveur), visibility (public, unlisted ou private ; absente, celle du compte), language (fr, en, es, de, it, pt, nl, ca ; absente, la langue de la marque). Une autre clé est refusée. Rendus dans mastodon de la publication. |
scheduled_at |
date ISO 8601 | non | Doit être dans le futur. |
timezone |
fuseau IANA | non | Europe/Paris, America/Montreal… Celui de la marque par défaut. |
mode |
draft, approval, scheduled, immediate |
non | Déduit s'il est absent. |
overrides |
objet indexé par réseau | non | Voir Les surcharges par réseau. |
external_reference |
texte (255) | non | Votre référence, pour retrouver la publication plus tard. |
brand_id |
brd_… |
selon | Exigé si le client couvre tout l'espace de travail. |
Une publication doit porter un texte ou une image, et chaque destination doit recevoir l'un ou l'autre une fois les surcharges appliquées.
Les dates
scheduled_at suit la norme ISO 8601 : 2026-10-15T09:00:00+02:00, 2026-10-15T07:00Z ou 2026-10-15T09:00. Les secondes et le décalage sont facultatifs ; sans décalage, l'heure est lue en UTC. Toute autre forme — 15/10/2026, par exemple — est refusée en 422, plutôt que lue au hasard d'une convention. L'instant envoyé est conservé, quel que soit le décalage, et rendu en UTC.
Le mode
mode |
Effet | Statut de départ |
|---|---|---|
immediate |
Part au prochain passage du planificateur, qui tourne chaque minute. | scheduled |
scheduled |
Part à scheduled_at, qui devient obligatoire. |
scheduled |
draft |
Enregistrée, rien ne part. À libérer avec publish. |
draft |
approval |
Soumise à la validation de l'équipe dans le tableau de bord. | pending_approval |
Sans mode, une date veut dire scheduled et son absence veut dire immediate : un contenu envoyé sans rien préciser part, il ne dort pas en brouillon.
En mode draft ou approval, scheduled_at n'est pas enregistré : la date de départ se choisit au moment de la libérer, avec publish. Une date envoyée doit tout de même être dans le futur.
Une publication en mode approval attend qu'un membre de l'équipe la valide dans le tableau de bord ; l'API ne valide pas. Une fois validée (status: "approved"), elle se libère avec POST /publications/{id}/publish.
Les images
media nomme les images de la bibliothèque de la marque, dans l'ordre, chacune avec un texte alternatif facultatif :
"media": [
{ "id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "Une miche de pain au levain sur une planche." }
]
media_ids(["med_…"]) reste accepté, sans texte alternatif. Envoyer les deux est refusé.- Le texte alternatif est transmis aux réseaux qui l'acceptent (Facebook, Instagram, LinkedIn, Threads, Pinterest). Pinterest le limite à 500 caractères.
- Un média supprimé, même s'il est encore dans la corbeille, n'est plus utilisable.
- Le nombre d'images dépend du réseau : Facebook, Instagram, Threads et LinkedIn en acceptent jusqu'à dix (un carrousel sur Instagram et Threads ; le lien d'un carrousel Threads n'est pas envoyé ; sur LinkedIn, les images l'emportent sur le lien, comme une image seule), Mastodon et Bluesky jusqu'à quatre, Pinterest une seule pour l'instant. Voir
capabilities.maximum_media_count. Les images partent dans l'ordre demedia.
Les tags
tags porte des hashtags, écrits librement : "pain au levain", "#PainAuLevain" ou "pain-au-levain" deviennent tous PainAuLevain. Chaque mot prend une majuscule initiale, tout ce qui n'est ni lettre ni chiffre sépare deux mots, et le # est retiré : la ressource rend les tags sans lui. Un tag dont il ne reste rien ("!!!") est refusé.
Chaque réseau les place à sa manière :
| Réseau | Placement | Compté dans la limite de texte |
|---|---|---|
| Facebook, Instagram, Pinterest | À la fin du texte, après une ligne vide, #Tag séparés par des espaces. |
Oui |
| À la fin du texte, comme hashtags cliquables. | Oui, sous la forme envoyée à LinkedIn, plus longue que #Tag. |
|
| Threads | Le premier tag devient le sujet du post (50 caractères au plus). Les suivants ne partent pas. | Non |
Un tag que le texte porte déjà comme hashtag (… notre #PainAuLevain) n'est pas répété. Sur Instagram, les hashtags du texte et les tags comptent ensemble dans la limite de 30.
Les surcharges par réseau
overrides remplace, pour un réseau, les valeurs communes. Il est indexé par nom de réseau, pas par destination : une surcharge s'applique à toutes les destinations de ce réseau présentes dans la requête.
"overrides": {
"linkedin": { "content": "Une version plus longue pour LinkedIn.", "tags": ["Boulangerie"] },
"instagram": { "content": "Une légende pour Instagram.", "tags": [] },
"pinterest": { "title": "Pain au levain maison" }
}
Champs admis, par réseau :
| Réseau | content |
tags |
link_url |
media |
title |
first_comment |
|---|---|---|---|---|---|---|
facebook, linkedin, threads |
oui | oui | oui | oui | non | oui |
instagram |
oui | oui | non | oui | non | oui |
pinterest |
oui | oui | oui | oui | oui (100) | non |
- Une clé qu'un réseau n'admet pas est refusée en
422, sur le champ de la surcharge (« « instagram » does not accept: « link_url » ») : elle n'est jamais ignorée en silence. - Un nom de réseau inconnu est refusé (« Unknown network: « linkedln ». »).
tags: []retire les hashtags de ce réseau ; une clé absente laisse la valeur commune.mediaremplace les images communes pour ce réseau ; une liste vide n'est pas une surcharge.titleest le titre visible d'un Pin. La publication n'en a pas de commun : le titre interne n'est jamais publié.first_commenten surcharge est refusé à la validation, puisqu'aucun réseau ne le publie aujourd'hui (voir Les refus).- Une surcharge qui vise un réseau absent de
destination_idsest ignorée, médias compris. - Les limites s'appliquent aux valeurs réellement envoyées sur chaque destination, surcharges comprises.
Exemple
curl -X POST https://quietsocial.dev/api/v1/publications \
-u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: article-42-publie-v1' \
-d '{
"content": "Notre nouvel article est en ligne.",
"link_url": "https://example.com/article",
"destination_ids": ["dst_01k4b8x2q9r7f3m5t6v8w0y2z4", "dst_01k4b8x3r0s8g4n6u7w9x1z3a5"],
"media": [{"id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "Une miche de pain au levain."}],
"tags": ["pain au levain"],
"overrides": {"linkedin": {"content": "Une version pour LinkedIn."}},
"external_reference": "article-42"
}'
201 Created, avec la ressource complète, cibles comprises.
Les refus
Un corps mal formé — champ manquant, type faux, valeur hors liste, date qui n'est pas en ISO 8601, clé de surcharge non admise — répond 422 avec l'enveloppe de validation (voir Erreurs).
Un corps bien formé mais qui ne peut pas devenir une publication répond 422 publication_not_publishable, et rien n'est créé. Toutes les destinations sont examinées : vous recevez toutes les erreurs d'un coup, pas réseau par réseau.
{
"error": {
"code": "publication_not_publishable",
"message": "“Instagram Fabrique” requires an image.",
"errors": [],
"destination_errors": {
"dst_01k4b8x4s1t9j5q7v8y0z2b4d6": ["“Instagram Fabrique” requires an image."]
}
}
}
errors porte ce qui vaut pour toute la publication, destination_errors ce qui vaut pour une destination, indexé par son identifiant. message reprend la première erreur ; lisez les deux listes. Le détail des messages est dans Erreurs.
Un identifiant de destination ou de média inconnu, ou qui appartient à une autre marque, est refusé dans errors, avec le même message dans les deux cas, et fait refuser la publication entière : rien ne part sur les destinations valides de la même requête.
Codes : 201, 400, 401, 403, 409, 422, 429.
GET /publications
Les publications visibles par le client, les plus récentes d'abord, avec leurs cibles.
Périmètre requis : publications:read.
| Paramètre | Type | Note |
|---|---|---|
brand_id |
brd_… |
Ne rend que les publications de cette marque. Une marque hors de portée rend une liste vide. |
external_reference |
texte (255) | Ne rend que les publications portant exactement cette référence. |
status |
statut de publication | Ne rend que les publications dans ce statut. Une valeur inconnue répond 422. |
per_page |
entier | Entre 1 et 100, 25 par défaut. |
page |
entier |
curl "https://quietsocial.dev/api/v1/publications?external_reference=article-42" \
-u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET"
Le filtre par external_reference donne un chemin de retour depuis votre identifiant vers le nôtre : une automatisation qui rejoue son événement métier peut vérifier si elle a déjà publié, même après avoir perdu l'identifiant pub_….
Codes : 200, 401, 403, 422, 429.
GET /publications/{id}
Périmètre requis : publications:read.
Rend la ressource complète. C'est l'appel à faire après un webhook publication.published pour connaître les adresses publiques dans targets[].external_url.
Codes : 200, 401, 403, 404, 429.
POST /publications/{id}/publish
Libère une publication retenue : un brouillon, ou une publication validée.
Périmètre requis : publications:update. Pas de clé d'idempotence.
| Champ | Type | Requis | Note |
|---|---|---|---|
scheduled_at |
date ISO 8601 | non | Sans date, la publication part au prochain passage du planificateur. |
curl -X POST https://quietsocial.dev/api/v1/publications/pub_01k4b8y5t2v9h6p8w0y2z4b6c8/publish \
-u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET" \
-H 'Content-Type: application/json' \
-d '{"scheduled_at": "2026-10-02T08:00:00+02:00"}'
200 OK, avec la publication relue. Son statut passe à scheduled ; les cibles en brouillon passent à pending sans date, à scheduled avec une date.
Refus, tous en 409 transition_not_allowed :
- la publication attend une validation (
pending_approval) ; - elle est déjà programmée (
scheduled) : pour changer son heure, déplacez-la depuis le calendrier du tableau de bord ; pour l'arrêter, annulez-la ; - elle est déjà partie ou terminée ;
- elle n'a aucune destination ;
scheduled_atest dans le passé ;- le quota mensuel de livraisons de la marque ne suffit pas pour ses cibles.
Une valeur de scheduled_at qui n'est pas une date ISO 8601 répond 422.
Codes : 200, 401, 403, 404, 409, 422, 429.
POST /publications/{id}/cancel
Arrête ce qui peut encore l'être.
Périmètre requis : publications:cancel. Pas de clé d'idempotence.
Seules les cibles en draft, pending_approval, pending, scheduled ou queued sont annulées. Une cible déjà prise en charge (processing, uploading_media, waiting_for_media, publishing) a peut-être déjà parlé au réseau : elle n'est pas annulée.
Le statut de la publication est dérivé de ses cibles. Si l'une d'elles avait déjà abouti, la publication ressort partially_published, pas cancelled. Lisez le statut rendu plutôt que d'attendre cancelled.
Une publication déjà terminée (published, partially_published, failed, cancelled) répond 409 transition_not_allowed.
Codes : 200, 401, 403, 404, 409, 429.
POST /publications/{id}/retry
Relance les cibles en échec.
Périmètre requis : publications:retry. Pas de clé d'idempotence.
Les cibles en failed ou requires_reconnect repassent en pending, avec un compteur de tentatives remis à zéro et une erreur effacée. Une cible publiée ne repart jamais.
Une publication terminée (failed, partially_published) dont des cibles repartent redevient scheduled, avec pour date de départ l'instant de la relance : elle peut de nouveau être annulée, et le calendrier la montre au jour où elle repart.
Refus, en 409 transition_not_allowed :
- aucune cible n'est à relancer ;
- une cible à relancer dépend d'une destination qui ne peut pas publier (connexion à rétablir, destination désactivée). Rien n'est modifié : rétablissez d'abord la connexion dans le tableau de bord.
La relance ne consulte pas le quota de livraisons : refuser de terminer une publication à moitié partie serait pire que de dépasser le plafond de quelques unités.
Codes : 200, 401, 403, 404, 409, 429.
Statuts
Statuts d'une publication
| Valeur | Sens |
|---|---|
draft |
Enregistrée, rien ne part. |
pending_approval |
En attente de validation par l'équipe. |
approved |
Validée, pas encore libérée. |
scheduled |
Programmée, y compris pour « maintenant ». |
queued |
Réservé ; aucune publication ne prend ce statut aujourd'hui. |
processing |
Au moins une cible est en cours ou attend encore. |
published |
Toutes les cibles sont publiées. |
partially_published |
Une cible au moins est publiée, une autre non. |
failed |
Aucune cible n'est publiée. |
cancelled |
Toutes les cibles sont annulées. |
Les quatre derniers sont terminaux.
Statuts d'une cible
| Valeur | Sens |
|---|---|
draft |
Retenue avec son brouillon. |
pending_approval |
En attente de validation. |
pending |
Attend le prochain passage du planificateur. |
scheduled |
Programmée à une date. |
queued |
En file d'envoi. |
processing |
Prise en charge. |
uploading_media |
Envoi de l'image au réseau. |
waiting_for_media |
Le réseau traite le média (une vidéo, le plus souvent) : la cible sera relue d'elle-même. Tant qu'une cible est dans cet état, la publication ne peut être ni annulée, ni déplacée, ni supprimée (409). |
publishing |
Appel de publication en cours. |
published |
Publiée. external_url est renseignée. |
failed |
Abandonnée après ses tentatives, ou refusée. |
cancelled |
Annulée. |
requires_reconnect |
La connexion doit être rétablie dans le tableau de bord. |
Les règles propres à chaque réseau qui ne figurent pas dans capabilities — format et proportions de l'image sur Instagram, largeur de l'image sur Threads, image supprimée depuis la création — sont vérifiées au moment de l'envoi. Une cible qui ne les respecte pas passe en failed avec error.code à validation_failed et un message qui nomme la règle ; elle n'est pas retentée.
Une cible fait jusqu'à cinq tentatives. Seules les erreurs passagères — réseau indisponible, limite de débit du réseau — sont retentées automatiquement : entre deux tentatives, la cible repasse en scheduled et garde sa dernière erreur dans error. Une erreur d'autorisation la met directement en requires_reconnect. failed et requires_reconnect sont les deux statuts que retry fait repartir.
Statistiques
targets[].metrics porte les compteurs du dernier jalon relevé avec compteurs : vers J+1, J+7 et J+30 après la publication (au plus trois jours plus tard ; un jalon manqué au-delà n'est pas rattrapé). Il vaut null avant le premier relevé, sur un réseau dont les statistiques ne sont pas relevées, et quand aucun relevé n'a de compteur (publication supprimée, accès non accordé…). Aujourd'hui, seul Mastodon est relevé, sans jeton, pour les publications publiques ou non listées.
{
"checkpoint": 7,
"measured_at": "2026-10-08T05:40:12+00:00",
"favourites": 34,
"reblogs": 3,
"replies": 5,
"quotes": 1,
"impressions": null,
"reach": null,
"likes": 34,
"comments": 5,
"shares": 3,
"saves": null,
"clicks": null,
"video_views": null,
"limited_by": null
}
| Champ | Sens |
|---|---|
checkpoint |
Le jalon : 1, 7 ou 30 jours après la publication. |
measured_at |
L'instant du relevé. |
impressions |
Affichages ou vues de la publication. |
reach |
Personnes distinctes atteintes. |
likes |
J'aime, réactions ou favoris. |
comments |
Commentaires ou réponses. |
shares |
Partages, republications ou envois. |
quotes |
Citations. |
saves |
Enregistrements. |
clicks |
Clics sortants ou sur le contenu. |
video_views |
Lectures vidéo. |
limited_by |
Pourquoi impressions, portée et clics manquent alors que le reste a été lu : permission_missing (le compte n'a pas accordé l'accès aux statistiques ; une reconnexion le rouvre aux jalons suivants), not_eligible (le réseau ne les fournit pas à ce compte), not_measurable (ce type de publication n'en a pas). null sinon. |
favourites, reblogs, replies |
Dépréciés. Anciens noms Mastodon de likes, shares et comments, de même valeur, rendus pour tous les réseaux. Ils restent dans la version 1 de l'API ; préférez les nouveaux noms. |
Un compteur que le réseau ne donne pas vaut null, ce qui n'est pas 0 : Mastodon ne donne ni impressions ni portée. D'autres compteurs peuvent s'ajouter à cet objet : ignorez les clés que vous ne connaissez pas.