Aller au contenu
Quiet Social

Publications

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 de media.

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
LinkedIn À 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.
  • media remplace les images communes pour ce réseau ; une liste vide n'est pas une surcharge.
  • title est le titre visible d'un Pin. La publication n'en a pas de commun : le titre interne n'est jamais publié.
  • first_comment en 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_ids est 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_at est 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.