Aller au contenu

Référence des outils MCP

Chaque outil qui agit sur le monde extérieur en votre nom fonctionne en deux appels : inboxSendTool, commentActTool (reply, delete), automationManageTool (pose, updatePose, removePose, replay, catchUp, delete), webhookManageTool (create, delete), postDeleteTool, contentDeleteTool et postUpdateTool (status: schedule).

  1. Le premier appel (sans confirmationToken) ne fait rien. Il renvoie needsConfirmation: true, un preview qui décrit exactement ce qui se passerait, et un confirmationToken.
  2. Montrez l’aperçu à l’utilisateur et obtenez un oui explicite.
  3. Le deuxième appel, avec les mêmes paramètres et le jeton, agit.

Le jeton est lié à votre espace de travail, à l’action et à ses paramètres exacts (un autre texte, une autre URL ou un autre commentaire est refusé). Il sert une seule fois et expire au bout de 15 minutes. Tout autre cas demande un nouveau premier appel.


Liste tous les comptes de réseaux sociaux connectés (les canaux) de votre organisation.

Paramètres :

Champ Type Requis Description
workspace string Non ID de workspace renvoyé par workspaceList. S’il est fourni, seuls les canaux de ce workspace sont renvoyés

Retour :

Champ Type Description
id string ID de l’intégration (à utiliser pour planifier des publications)
name string Nom affiché du compte
picture string URL de la photo de profil
platform string Identifiant de la plateforme : instagram-standalone, tiktok, youtube, x, linkedin ou threads
workspace object Le workspace du canal, sous la forme { id, name } : chaque canal est dans exactement un workspace

Liste les workspaces de votre organisation, chacun avec les ids de ses canaux. Un workspace est un dossier de canaux : chaque canal est dans exactement un workspace, et toute organisation en a au moins un. Passez l’id d’un workspace à integrationList pour ne garder que ses canaux. Chaque workspace porte aussi son contexte, rempli dans Paramètres → Workspaces : l’agent le lit avant d’écrire une publication, une réponse ou un DM pour l’un de ses canaux. Voir Workspaces et périmètre.

Paramètres : aucun

Retour :

Champ Type Description
id string ID du workspace, à passer à integrationList comme workspace
name string Nom affiché du workspace
channels string[] Les ids des canaux du workspace
type string PERSONAL, BUSINESS ou CLIENT : votre workspace, votre entreprise, ou celui d’un client
logo string | null URL du logo du workspace ; null quand son média a été supprimé
website string | null Site web de la marque
country string | null Pays de l’audience, ISO 3166-1 alpha-2 (MT)
timezone string | null Fuseau horaire du workspace, IANA (Europe/Malta)
about string | null Marque, audience, ton, tels qu’écrits dans l’app (2 000 caractères au plus)

Renvoie les règles de publication, la longueur maximale et les réglages qu’attend une plateforme. Appelez-le avant de planifier une publication pour savoir ce que la plateforme exige. Lecture seule.

Paramètres :

Champ Type Requis Description
platform string Oui La plateforme du canal, telle que la donne integrationList : instagram-standalone, facebook, threads, tiktok, youtube, linkedin ou x
isPremium boolean Non X seulement : le compte a X Premium (publications plus longues). À omettre sinon

Retour :

Champ Type Description
rules string Règles de publication et bonnes pratiques propres à la plateforme
maxLength number Longueur maximale d’une publication ou d’un commentaire, en caractères
settings object Schéma JSON des réglages à passer à integrationSchedulePostTool pour cette plateforme

Une plateforme inconnue renvoie errors.


Planifie des publications, crée des brouillons ou publie tout de suite sur les réseaux sociaux. C’est l’outil principal pour créer du contenu.

Paramètres :

Champ Type Requis Description
socialPost array Oui Tableau des publications à créer

Chaque élément de socialPost :

Champ Type Requis Description
integrationId string Oui ID d’intégration renvoyé par integrationList
contentId string Non La carte du tableau de contenus dont la publication est tirée, renvoyée par contentListTool. Lie la publication à la carte : la carte passe d’elle-même en PUBLISHED quand la publication est en ligne
isPremium boolean Oui Si l’utilisateur est premium
date string Oui Date et heure. Sans décalage (2026-11-03T18:00:00) : lue dans le fuseau du workspace du canal (timezone de workspaceList), en UTC si le workspace n’en a pas. Avec un décalage ou Z (2026-11-03T17:00:00Z) : prise telle quelle
shortLink boolean Oui Raccourcir ou non les liens de la publication
type string Oui draft, schedule ou now
postsAndComments array Oui Le contenu de la publication et d’éventuels commentaires
settings array Oui Réglages propres à la plateforme, tirés de integrationSchema

Le retour donne, pour chaque publication, l’heure murale à laquelle elle est programmée (date, YYYY-MM-DD HH:mm), le fuseau utilisé (timeZone) et la façon dont la date a été lue (dateReadIn : offset, workspace ou utc). « À 18 h » se dit donc à l’agent comme à l’app : à l’heure de l’audience, celle du workspace.

Chaque publication revient aussi avec son link, un lien court (https://go.usenadia.com/s/…) qui existe avant sa sortie : il mène au profil du canal tant que la publication n’est pas en ligne, puis à la publication, sans rien faire. On le donne dans une newsletter, une bio ou une autre publication avant la sortie. Il suit la publication quand on la déplace ou la modifie ; une publication supprimée puis programmée à nouveau est une autre publication, avec un autre lien. Une publication sur plusieurs canaux a un lien par canal. link vaut null sur une plateforme dont UseNadia ne sait pas bâtir l’adresse du profil.

Chaque élément de postsAndComments :

Champ Type Description
content string Le texte de la publication, brut (voir la mise en forme plus bas)
attachments array Tableau d’URL d’images ou de médias
thumbnail string Facultatif. La couverture de la vidéo d’attachments (son premier .mp4) : l’URL d’un JPEG, idéalement 1080×1920. Un reel Instagram sort avec elle comme couverture, l’image de la grille du profil. N’importe quelle URL publique, signée comprise : UseNadia en garde une copie à la programmation. Ne mettez jamais la couverture dans attachments : elle deviendrait une seconde image

Chaque élément de settings :

Champ Type Description
key string Nom du réglage
value any Valeur du réglage (préférez les ID aux libellés quand ils existent)

Envoyez le texte comme une personne le taperait : texte brut, une ligne par phrase, une ligne vide entre les paragraphes. Pas de HTML, pas de <p>, pas de <br>. Nadia le met en forme pour chaque plateforme et garde vos retours à la ligne : une ligne vide dans votre texte est une ligne vide dans la légende publiée, sur Instagram comme sur TikTok.

Freelance en mission longue = CDI déguisé ? Non, et voilà pourquoi.
On me le dit souvent : « t'es pas un vrai entrepreneur ».
Abonne-toi à @vincentleserpent pour apprendre à coder.
#freelance #developpeur #cdi

Le HTML reste accepté, pour les clients qui en envoient déjà (le tableau de bord, l’API publique) : un contenu qui porte une balise est stocké tel quel, avec ces seules balises.

Balise Usage
<p> Une ligne ; un <p></p> vide est une ligne vide
<h1>, <h2>, <h3> Titres
<strong> Texte en gras
<u> Texte souligné
<ul>, <li> Listes

Le premier élément de postsAndComments est la publication. Sur les canaux que UseNadia connecte :

  • instagram-standalone : les éléments suivants sont publiés en commentaires sous la publication, texte seul (un commentaire Instagram ne peut pas porter de média) ;
  • tiktok : les éléments en plus sont ignorés, seul le premier est publié ;
  • youtube : les éléments en plus sont ignorés aussi ;
  • x : chaque élément devient un tweet du fil, publié en réponse au précédent (chaque tweet compte dans le quota de publication de l’offre) ;
  • linkedin : les éléments suivants sont publiés en commentaires sous le post, texte seul ;
  • threads : chaque élément devient une réponse au précédent, enchaînée sous la publication, et peut porter ses propres médias.

Détail et délais entre les parties : Fils et commentaires.

Pour planifier plusieurs publications (par ex. 20 publications sur des jours différents), ajoutez plusieurs éléments au tableau socialPost, chacun avec sa date et son integrationId.

Retour :

Champ Type Description
postId string L’ID de la publication créée
integration string L’intégration sur laquelle elle a été publiée

Si la validation échoue, l’outil renvoie { errors: string } avec le détail de ce qui ne va pas (par ex. un contenu qui dépasse la limite de caractères).


Lit le calendrier : les publications de l’organisation (brouillons, planifiées et déjà publiées) entre deux dates, ou une seule publication en entier. Lecture seule.

Paramètres :

Champ Type Requis Description
postId string Non Seulement cette publication, en entier, avec son fil. Les dates sont alors ignorées
startDate string Sans postId Date UTC du début de la période (par ex. 2026-07-20T00:00:00Z)
endDate string Sans postId Date UTC de la fin de la période (par ex. 2026-07-27T00:00:00Z)
integrationId string Non Seulement les publications de ce canal, renvoyé par integrationList
workspace string Non Seulement les publications des canaux de ce workspace, un ID renvoyé par workspaceList. Avec integrationId, ce canal doit être dans ce workspace, sinon la liste revient vide

Retour :

Un objet avec un tableau posts. Chaque élément comporte :

Champ Type Description
id string ID de la publication
group string L’ID du groupe de la publication (commun à une publication et à ses variantes par canal)
state string État de la publication (QUEUE, DRAFT, PUBLISHED ou ERROR)
publishDate string Date et heure UTC de la publication (YYYY-MM-DD HH:mm)
content string Le texte de la publication, sans HTML. Sur une période, un extrait de 280 caractères ; avec postId, en entier
integrationId string ID du canal
channel string Nom affiché du canal
platform string Identifiant de la plateforme (par ex. instagram-standalone, tiktok, x)
link string Le lien court de la publication : le profil du canal tant qu’elle n’est pas en ligne, la publication ensuite (voir integrationSchedulePostTool). null pour une publication d’avant les liens, ou sur une plateforme sans adresse de profil
linkClicks object Les clics sur link, aperçus de lien exclus : total, toPost (envoyés vers la publication), toProfile (envoyés vers le profil du canal, avant la publication), sources ([{ source, clicks }], par le ?src= que portait le lien, le plus cliqué d’abord). null quand link vaut null
thread string[] Avec postId seulement : les commentaires publiés dessous, dans l’ordre
releaseId string Avec postId seulement : l’ID de la publication sur la plateforme une fois publiée (l’ID de média des outils Instagram), ou missing quand son média n’est jamais arrivé sur la plateforme
releaseURL string Avec postId seulement : l’URL de la publication
missingMedia array Avec postId seulement, quand releaseId vaut missing : les fichiers qui ne sont jamais arrivés sur la plateforme (id, url)

Change la nature d’une publication sans la réécrire : sortir une publication planifiée de la file, y remettre un brouillon, ou enregistrer l’ID donné par la plateforme à une publication faite hors de UseNadia.

Paramètres :

Champ Type Requis Description
postId string Oui La publication, renvoyée par postsListTool
status string Non draft (hors de la file) ou schedule (de retour dans la file, à sa date)
releaseId string Non L’ID de la publication sur la plateforme (ID de média Instagram, ID de vidéo TikTok…), pour que les analyses, les commentaires et les automatisations la retrouvent
confirmationToken string status: schedule, deuxième appel Le jeton du premier appel, une fois que l’utilisateur a dit oui

Remettre un brouillon dans la file (status: schedule) le fait partir à sa date : c’est donc une action confirmée. Sortir une publication de la file et enregistrer un releaseId n’en sont pas.

Retour : { updated, needsConfirmation?, preview?, confirmationToken?, errors? }.


Supprime une publication et tout ce qui est planifié avec elle (ses variantes par canal et son fil). Une publication planifiée est annulée ; une publication déjà publiée est retirée de UseNadia, pas de la plateforme. C’est irréversible, donc c’est une action confirmée : l’aperçu indique la date, le canal et les premiers mots de la publication.

Paramètres :

Champ Type Requis Description
postId string L’un des deux La publication, renvoyée par postsListTool
group string L’un des deux Le groupe de la publication, renvoyé par postsListTool
confirmationToken string Deuxième appel Le jeton du premier appel, une fois que l’utilisateur a dit oui

Retour : { deleted, group, needsConfirmation?, preview?, confirmationToken?, errors? }.


Le prochain créneau libre dans le planning de publication d’un canal (la file d’attente) : ses créneaux sont des heures sur des jours choisis, parcourus dans l’ordre à partir de maintenant, en sautant ceux déjà pris par une publication. C’est l’outil de « mets-le dans le prochain créneau libre » : l’agent lit la date, puis programme avec integrationSchedulePostTool. Lecture seule.

Paramètres :

Champ Type Requis Description
integrationId string Non Le canal. Sans lui, le prochain créneau libre de tout l’espace de travail

Retour : { date }, en UTC, au format ISO 8601 (avec son Z), à passer telle quelle à integrationSchedulePostTool. Pour l’annoncer à l’utilisateur, l’agent la convertit dans le fuseau du workspace du canal.


Lit les créneaux de publication d’un canal ou d’un workspace entier (la grille de Paramètres → Publication). Un créneau, c’est une heure et les jours où il sert, en UTC : { time, days? }, time en minutes après minuit UTC (18 h 30 UTC = 1110), days de 0 (dimanche) à 6 (samedi), sans days = tous les jours. L’app affiche la grille dans le fuseau du workspace : l’agent convertit avant de les montrer. Lecture seule.

Paramètres :

Champ Type Requis Description
integrationId string Un des deux Le canal
workspaceId string Un des deux Tous les canaux de ce workspace (renvoyé par workspaceList)

Retour : { channels: [{ integrationId, times }], aligned, slotsPerWeek } : les créneaux de chaque canal, aligned vrai si tous les canaux ont les mêmes, et le nombre de créneaux par semaine. API : GET /public/v1/integrations/:id/posting-times.


Remplace les créneaux de publication d’un canal, ou de tous les canaux d’un workspace (la grille de Paramètres → Publication). Tous les anciens créneaux sont remplacés ; aucune publication déjà programmée ne bouge. L’agent convertit d’abord l’heure de l’utilisateur (le fuseau du workspace) en UTC, montre le changement et n’appelle l’outil qu’après un oui explicite.

Paramètres :

Champ Type Requis Description
integrationId string Un des deux Le canal
workspaceId string Un des deux Tous les canaux de ce workspace (renvoyé par workspaceList)
times { time, days? }[] Oui Les nouveaux créneaux, qui remplacent tous les anciens

Retour : les créneaux tels qu’écrits, sous la même forme que scheduleSlotsGetTool. API : PUT /public/v1/integrations/:id/posting-times.


Liste les automatisations commentaire → DM du compte (Instagram) : les ID que demandent les réglages Instagram d’une publication, et ce qui tourne déjà sur une publication. Lecture seule.

Une publication désigne son automatisation par un ID dans ses réglages Instagram : automationFlowId (un template dessiné dans l’app), avec automationKeywords et automationVariables. Des mots ou des valeurs envoyés sans l’ID sont refusés à la planification, car rien ne tournerait.

Paramètres :

Champ Type Requis Description
flowId string Non Seulement ce template, avec toutes les publications sur lesquelles il est posé
integrationId string Non Un canal Instagram, renvoyé par integrationList. Renvoie aussi ce qui tourne sur ses publications
workspace string Non Les poses de tous les canaux de ce workspace, un ID renvoyé par workspaceList. Avec integrationId, ce canal doit être dans ce workspace, sinon aucune pose ne revient
postId string Non Avec integrationId ou workspace : seulement ce qui tourne sur cette publication. Un ID de publication renvoyé par postsListTool, ou un ID de média Instagram. Une publication pas encore publiée (avec ou sans filtre) : renvoie aussi scheduled
onlyWithIssues boolean Non Seulement les poses qui ne tourneront pas en l’état (issues non vide)

Retour :

Champ Type Description
templates array Les automatisations dessinées dans l’app : id (à passer comme automationFlowId), name, status (DRAFT, ACTIVE, PAUSED ou ARCHIVED : un template ARCHIVED continue de répondre sur les publications où il est déjà posé, mais ne se pose plus sur un nouveau post et ne se modifie plus), ready (ACTIVE et sans erreur : peut aller sur un post tel quel, jamais un archivé), issues, trigger (post_comment ou story_reply : les deux se posent aussi bien sur un post, un reel que sur une story, c’est la publication qui décide ; dm_keyword ne se pose pas encore), keywordsRequired (toujours true : les mots d’un post ; sur une story ils sont facultatifs), variables (les noms à remplir dans automationVariables), variableHints (pour chaque variable, sa description et une valeur d’exemple example, quand le template les donne), poses, posesWithIssues (les publications où il est posé et qui ne répondront pas tant que leurs valeurs ne sont pas corrigées)
scheduled object Avec postId, une publication Instagram pas encore publiée : postId, integrationId, kind (post ou story), publishDate, flowId (le template posé à sa publication, null s’il n’y en a pas), keywords, variables
poses array Avec integrationId : les templates qui tournent sur les publications du canal ; avec flowId seul : toutes les publications sur lesquelles ce template est posé. Chacune avec id (le poseId de automationManageTool et automationRunsTool), flowId, flowName, postId, mediaId, keywords, variables, active, issues (codes de ce qui empêche la pose de tourner, vide quand rien ne l’en empêche : variable_without_value quand le template a gagné une variable après la pose, no_keywords, button_title_too_long…), ready (aucun problème, la pose active et son template en ACTIVE ou ARCHIVED), runs

Chaque pose porte aussi counts, le funnel de la publication : runs (les personnes entrées), replied (ont réécrit après leur commentaire ou leur réponse à la story : un bouton touché, un texte, une question), emails, clicked (ont cliqué au moins un lien reçu, aperçus de lien exclus), waiting et waitingAt, où ces personnes attendent : firstMessage (n’ont jamais touché le premier DM : plus rien ne peut leur être envoyé, Meta n’autorise qu’une réponse privée par commentaire), email (ont répondu au premier DM sans laisser leur e-mail), other (ailleurs), puis done et failed. Les personnes elles-mêmes : automationRunsTool.

Pour reprendre sur une nouvelle publication l’automatisation d’une plus ancienne, lisez la pose de celle-ci avec integrationId et postId, puis planifiez avec les mêmes automationFlowId et automationKeywords, en ne changeant que les valeurs de automationVariables qui diffèrent.

Une pose qui a un problème est sautée sans un mot au commentaire suivant. Après avoir modifié un template (une variable ajoutée ou renommée), listez ses poses avec flowId, puis donnez à chaque pose qui a des issues ses valeurs manquantes avec updatePose de automationManageTool (envoyez toutes les valeurs : variables remplace l’ensemble des valeurs de la pose).


Tout ce que l’API publique fait sur un template ou une pose, sauf dessiner l’arbre des étapes (c’est le rôle de l’éditeur, dans l’app). Une action par appel.

Paramètres :

Champ Type Requis Description
action string Oui pose, updatePose, removePose, poll, replay, catchUp, activate, pause, archive, unarchive, delete, rename, createFromPreset
flowId string Selon l’action Le template (pose, activate, pause, archive, unarchive, delete, rename)
poseId string Selon l’action La pose, renvoyée par automationList (updatePose, removePose, poll, replay, catchUp)
postId string Non pose, removePose : une publication ou une story Instagram programmée mais pas encore publiée, renvoyée par postsListTool, à la place d’integrationId et mediaId (ou de poseId)
integrationId string pose Le canal Instagram (aussi rename, createFromPreset)
mediaId string pose La publication déjà en ligne, renvoyée par commentsListTool
kind string Non post ou story (par défaut : le déclencheur du template)
keywords string[] pose, updatePose Les mots-clés déclencheurs de cette publication
variables object pose, updatePose Une valeur par variable du template
active boolean updatePose false met la pose en pause
commentIds string[] replay De 1 à 50 ID de commentaires, renvoyés par commentsListTool
resend boolean Non replay : relancer un commentaire qui a déjà un run
name string Non rename, createFromPreset
preset string createFromPreset lead_magnet, newsletter, link, follow, follow_gate ou blank
language string Non createFromPreset : fr (par défaut) ou en
confirmationToken string Deuxième appel pose, updatePose, removePose, replay, catchUp, delete : le jeton du premier appel

Retour : { ok, errors? }, plus pose, template, poll (checked, started), replay (un résultat par commentaire) ou catchUp (matching, started, queued, perMinute) selon l’action. Sur une publication que vous planifiez, passez automationFlowId, automationKeywords et automationVariables dans ses réglages Instagram.

Une publication ou une story déjà programmée mais pas encore publiée reçoit son automatisation après coup : pose avec flowId, postId, keywords et variables (le genre est celui de la publication : une story n’a pas besoin de mot), ou removePose avec postId pour la retirer. Elle est vérifiée comme à la programmation et, à la publication, posée exactement comme si elle avait été dans les réglages dès le départ : inutile de supprimer et reprogrammer la publication (son lien reste le même). Rappelé, pose remplace le template qu’elle porte. Une fois la publication en ligne, posez sur la publication elle-même (integrationId, mediaId). Renvoie scheduled (comme automationList). Côté API : GET, PUT et DELETE /public/v1/posts/{id}/automation.

pose, updatePose, removePose, replay, catchUp et delete sont des actions confirmées : elles font écrire le compte à des personnes, ou ne peuvent pas être annulées. poll, activate, pause, archive, unarchive, rename et createFromPreset agissent tout de suite. activate est refusé tant que le template contient des erreurs.

catchUp rattrape les commentaires déjà là quand le template a été posé sur une publication déjà en ligne : sans lui, un commentaire antérieur à la pose est ignoré. Le premier appel lit les commentaires et renvoie le nombre et les personnes qui recevraient l’automatisation (comments, people), sans rien envoyer ; s’il n’y en a aucun, il répond tout de suite (catchUp.matching vaut 0), rien à confirmer. Confirmé, chaque commentaire démarre la même conversation qu’un commentaire neuf (réponse publique comprise), 10 par minute au plus pour rester sous la limite de Meta (750 réponses privées par heure et par compte) ; UseNadia envoie la suite seul. Les garde-fous sont ceux d’un commentaire neuf, sa date avant la pose mise à part : commentaire de premier niveau, pas les vôtres, moins de 7 jours, un des mots, une fois par personne, jamais un commentaire qui a déjà un run. Côté API : GET puis POST /public/v1/automation-flow-poses/{id}/catch-up.

archive met de côté un template ACTIVE : les publications où il est déjà posé continuent de répondre, mais il ne se pose plus sur de nouveaux posts (pose est refusé, ready vaut false) et ne se modifie plus (rename est refusé). Seul un template ACTIVE s’archive : un template en pause se reprend d’abord, un brouillon se supprime. unarchive le remet en ACTIVE, refusé tant qu’il contient des erreurs. Archivez plutôt que supprimer un template dont les publications doivent continuer à répondre : delete retire ses poses avec lui, et les personnes qui y sont passées.


Les personnes passées par une pose : une ligne par personne, les plus récentes d’abord. Lecture seule.

Paramètres :

Champ Type Requis Description
poseId string Oui La pose, renvoyée par automationList
status string Non PENDING, WAITING, DELAYED, DONE, HANDED_OFF, FAILED ou SKIPPED

Retour : { runs, total }. Chaque run : id, username, keyword, text (le commentaire ou le message qui l’a déclenché), status, email, tags, isFollower, error (le message de Meta en cas d’échec), startedAt, completedAt, clickedAt (premier clic sur un lien envoyé par le run, null s’il n’a jamais cliqué) et clicks (nombre de clics). Les aperçus de lien qu’Instagram charge pour la vignette ne comptent pas.


Le côté Instagram d’un canal, lu en direct chez Meta : les publications récentes, les stories en ligne en ce moment, ou les commentaires sous une publication. Sur un canal Threads, comments seulement : les réponses à une publication, à tous les niveaux. Lecture seule.

Paramètres :

Champ Type Requis Description
integrationId string Oui Le canal Instagram, ou un canal Threads pour comments
kind string Oui publications, stories ou comments
mediaId string comments La publication : un ID de média Instagram, ou le releaseId d’une publication lue avec postsListTool

Retour : publications (id, l’ID de média que surveille une pose, type, caption, permalink, publishedAt, comments, likes) ou comments (id, from sous la forme @username, text, at, replyTo, hidden), les plus anciens d’abord.


Répond publiquement à un commentaire, le masque ou le réaffiche, ou le supprime sur la plateforme : Instagram, ou Threads (les réponses à une publication).

Paramètres :

Champ Type Requis Description
integrationId string Oui Le canal de la publication : Instagram ou Threads
commentId string Oui Le commentaire, renvoyé par commentsListTool
action string Oui reply, hide, unhide ou delete
message string reply La réponse publique, 2 200 caractères au plus
confirmationToken string reply, delete Le jeton du premier appel, une fois que l’utilisateur a dit oui

Une réponse est vue par tout le monde aussitôt et une suppression est définitive : les deux sont donc des actions confirmées. Le jeton est lié à ce commentaire et à ce texte précis, à usage unique, valable 15 minutes. Masquer est réversible et ne demande aucune confirmation.

Sur Threads, ce que la plateforme refuse revient dans errors, avec sa raison : une réponse ne se supprime pas (l’API de Threads ne supprime pas la réponse de quelqu’un d’autre, masquez-la plutôt), seule une réponse de premier niveau qui n’est pas la vôtre se masque, et une réponse publique fait 500 caractères au plus.

Retour : { done, needsConfirmation?, preview?, confirmationToken?, errors? }.


La boîte de messages privés (DM) d’un canal Instagram, lue dans la copie qu’en garde UseNadia : une boîte à la fois, ce qui attend un humain d’abord, les plus récentes d’abord à l’intérieur. Chaque conversation vient avec la personne, la date, son statut (NEEDS_REPLY = un humain attend une réponse, ANSWERED = un vrai échange où vous avez parlé en dernier, AUTO = seule une automatisation a parlé), son étiquette (THANKS, QUESTION, NOISE) et son dernier message ; counts donne le nombre de conversations de chaque boîte. Lecture seule.

Les pièces jointes sont aplaties : une carte envoyée par une automatisation (ManyChat, les automatisations de UseNadia) revient sous forme de son texte avec ses boutons et leurs liens, un Reel ou une publication partagés sous forme de leur permalien.

Paramètres :

Champ Type Requis Description
integrationId string Oui Le canal Instagram, renvoyé par integrationList
box string Non needs_reply (par défaut), conversations (tout sauf le full auto), auto, thanks (ce qui attend est un merci ou un emoji), organic (les personnes à qui aucune automatisation n’a jamais écrit), read (marquées lues) ou all
username string Non Seulement la conversation avec cette personne (@username ou son ID), quelle que soit sa boîte
limit integer Non Nombre de conversations, de 1 à 200. Par défaut toutes celles de needs_reply (200 au plus), 25 pour les autres boîtes
after string Non Le next de la réponse précédente, pour la page suivante

Retour :

Champ Type Description
channel string Nom affiché du canal
box string La boîte lue
counts object Nombre de conversations de chaque boîte (needs_reply, conversations, auto, thanks, organic, read, all)
conversations array Chacune avec id (à passer à inboxReadTool), with (@username de la personne), recipientId, participants, updatedAt, status, label, replyWindowOpen (si Instagram accepte encore une réponse : seulement dans les 24 h qui suivent le dernier message de la personne), replyWindowClosesAt et lastMessage
next string Curseur de la page suivante, null sur la dernière
errors string Pourquoi rien n’est revenu (un canal qui n’est pas dans l’espace de travail, une erreur de Meta)

Chaque message, ici et dans inboxReadTool : at, from (@username de l’expéditeur), text, attachments (kind parmi template, reel, share, story_reply, story_mention, image, video…, avec text, url, storyId, buttons), unsupported quand l’API ne montre pas ce type de message (une note vocale, un GIF) et, dans inboxReadTool, automated: true quand une automatisation l’a envoyé ou consommé (le mot-clé, un bouton cliqué, l’e-mail) : ce n’est ni un mot de la personne ni un mot du propriétaire.

Exemple : qui attend une réponse.

{ "integrationId": "abc123" }

Une conversation privée, lue dans la copie qu’en garde UseNadia : ses 50 derniers messages, les plus anciens d’abord, les précédents avec before. Récupérez d’abord l’ID de la conversation avec inboxListTool. Lecture seule.

Paramètres :

Champ Type Requis Description
integrationId string Oui Le canal Instagram
conversationId string Oui L’id de la conversation renvoyé par inboxListTool (l’ID de conversation d’Instagram, ou celui de la personne tant qu’Instagram n’a pas encore nommé le fil)
before string Non Le before de la réponse précédente, pour les messages plus anciens

Retour : channel et conversation : id, with, recipientId, updatedAt, replyWindowOpen, replyWindowClosesAt (le moment où Instagram cesse d’accepter une réponse, 24 h après le dernier message de la personne ; ensuite, seule elle peut rouvrir la conversation en écrivant de nouveau), messages, dans la forme décrite sous inboxListTool, tags et before quand il reste des messages plus anciens. Ou errors.

Ici, chaque message porte en plus son id, celui que replyTo d’inboxSendTool cite, et replyTo quand il cite lui-même un message : l’id du message cité. Instagram ne le dit que pour les messages arrivés en direct et pour les vôtres ; un message plus ancien, rattrapé par la synchronisation, n’en porte jamais.

tags, ce que les automatisations savent de la personne, du plus récent au plus ancien : kind: "automation" pour un template qu’elle a déclenché (automationId, automation, son nom, keyword, le mot qu’elle a écrit — vide pour une réponse à une story où tout compte), kind: "tag" pour une étiquette qu’un pas add_tag lui a posée (value) ; dans les deux cas count, combien de fois, et lastAt, la dernière. Lus sur les runs, donc valables pour le passé aussi.

Exemple :

{ "integrationId": "abc123", "conversationId": "t_1234567890" }

Envoie un message privé (DM) sur un canal Instagram, dans une conversation existante : Instagram ne laisse un compte écrire qu’à quelqu’un qui a écrit en premier.

Un DM est vu par la personne aussitôt et ne se reprend pas : c’est donc une action confirmée. Le premier appel n’envoie rien et renvoie un preview et un confirmationToken, signé sur le canal, le destinataire et le texte exacts, à usage unique, valable 15 minutes. Une fois que l’utilisateur a dit oui à ce destinataire et à ce texte précis, le deuxième appel, avec les mêmes paramètres et le jeton, l’envoie. Changer le texte demande un nouveau premier appel.

Paramètres :

Champ Type Requis Description
integrationId string Oui Le canal Instagram
conversationId string L’un des deux La conversation, renvoyée par inboxListTool
recipient string L’un des deux @username ou ID de la personne, à défaut de conversationId
text string Oui Le message, en texte brut, de 1 à 1 000 caractères
linkUrl string Non Un lien, envoyé sous forme de bouton sous le texte
linkButtonText string Non Libellé de ce bouton, 20 caractères au plus
replyTo string Non L’id d’un message de la conversation (renvoyé par inboxReadTool), à vous ou à la personne : le DM le cite, comme « Répondre » dans Instagram
confirmationToken string Deuxième appel Le jeton de l’aperçu, seulement une fois que l’utilisateur a dit oui à ce message précis

Retour : { sent, needsConfirmation?, preview?, confirmationToken?, messageId?, errors? }. Le preview contient channel, integrationId, conversationId, to, recipientId, text, linkUrl, linkButtonText, replyTo et replyWindowClosesAt.

Quand on sait la fenêtre de 24 h fermée, le premier appel refuse déjà avec errors et rien n’est proposé : seule la personne peut rouvrir la conversation. Ne réessayez pas.

Exemple : le premier appel, puis le même avec le jeton.

{ "integrationId": "abc123", "recipient": "@someone", "text": "Here is the guide", "linkUrl": "https://example.com/guide", "linkButtonText": "The guide" }

Lit tout de suite l’Inbox d’un canal Instagram, pour rattraper ce que le webhook de Meta a manqué : les nouveaux messages privés et les réponses aux stories sont récupérés, et les automatisations qui les attendaient avancent. Le rattrapage horaire tient l’Inbox à jour mais ne fait pas avancer les automatisations : cet outil sert de rattrapage. Rien n’est envoyé.

Paramètres : integrationId (string, requis).

Retour : { polled, channel, conversations, handled, errors? } : conversations, celles lues chez Meta ; handled, les messages entrants qui ont atteint une automatisation en attente.


Génère une image par IA, à joindre à une publication.

Paramètres :

Champ Type Requis Description
prompt string Oui Description de l’image à générer

Retour :

Champ Type Description
id string ID du média
path string URL de l’image générée

Mettez le path renvoyé dans le tableau attachments au moment de planifier une publication.


Déplace une publication existante à une autre date et heure. Une date sans décalage est lue dans le fuseau du workspace du canal de la publication (UTC si le workspace n’en a pas) ; avec un décalage ou Z, elle est prise telle quelle. Récupérez d’abord l’ID de la publication avec postsListTool.

Un déplacement est réversible (il suffit de la remettre en place) : contrairement à la planification, il ne passe pas par une confirmation. Une publication déjà publiée ne se déplace pas.

Paramètres :

Champ Type Requis Description
postId string Oui La publication à déplacer
date string Oui La nouvelle date : YYYY-MM-DDTHH:mm:ss dans le fuseau du workspace du canal, ou avec un décalage / Z

Retour :

Champ Type Description
moved boolean Si la publication a été déplacée
postId string L’ID de la publication
date string Sa nouvelle date, heure murale dans timeZone (YYYY-MM-DD HH:mm)
timeZone string Le fuseau de cette heure (celui du workspace, ou UTC)
dateReadIn string Comment la date a été lue : offset, workspace ou utc
errors string Pourquoi elle n’a pas été déplacée

Lit les performances des vidéos d’un canal TikTok ou Instagram, à partir de l’historique que UseNadia collecte toutes les 30 minutes. Cet outil n’a pas d’équivalent dans upstream, et c’est lui qui permet de répondre à « comment se porte ma dernière vidéo ».

Il est en lecture seule et n’appelle aucun fournisseur : tout vient des séries collectées. Un canal sans rien de collecté encore répond collected: false, avec la raison.

Paramètres :

Champ Type Requis Description
integrationId string Oui Le canal dont on lit les vidéos
videoId string Non L’ID de vidéo chez le fournisseur sur laquelle se concentrer. Par défaut, la plus récente
limit number Non Combien de vidéos parmi les plus récentes lire, de 1 à 30. 10 par défaut

Retour, par vidéo : les compteurs actuels (vues, portée, likes, commentaires, partages, enregistrements, temps de visionnage), les taux d’engagement en pourcentage des vues, le taux de swipe actuel (skipRatePercent, Reels Instagram seulement, plus il est bas, mieux c’est), les vues atteintes à des âges fixes (H+4, H+12, H+24, H+48, H+72, H+120, H+168) et les vues gagnées sur les dernières 24 et 48 heures.

La vidéo ciblée est en plus comparée aux autres à son propre âge (rang et médiane), avec une projection à H+120 fondée sur le multiplicateur H+24 → H+120 propre au canal, sa vitesse actuelle, et le nombre d’abonnés avec son gain sur 24 et 48 heures.


Les métriques d’un canal sur les derniers jours, lues en direct sur la plateforme (mises en cache une heure) : abonnés, portée, impressions, vues, likes… tout ce que la plateforme fournit. Avec postId, les métriques de cette seule publication publiée. Lecture seule.

Paramètres :

Champ Type Requis Description
integrationId string Oui Le canal
days integer Non La période, en jours (30 par défaut)
postId string Non Une publication publiée de ce canal, à la place du compte
series boolean Non true ajoute les points jour par jour de chaque métrique

Retour : { metrics }. Chaque métrique : label, latest (la dernière valeur), total (la somme sur la période), percentageChange par rapport à la période précédente, et series sur demande. Avec postId, missing: true indique que le média de la publication n’est jamais arrivé sur la plateforme.


L’historique brut que UseNadia collecte toutes les 30 minutes sur un canal TikTok ou Instagram, sous forme de séries temporelles : les compteurs du compte, ou ceux de chaque vidéo. Pour une lecture toute faite, videoPerformance passe en premier ; celui-ci sert à un graphique, à un export, ou à une question à laquelle l’autre ne répond pas. Lecture seule.

Paramètres :

Champ Type Requis Description
integrationId string Oui Le canal
kind string Oui account ou video
videoId string Non video : seulement cette vidéo (l’ID de la plateforme)
from, to string Non ISO 8601. Par défaut : les 30 derniers jours
limit, offset integer Non Pagination

Retour : { items, total, from, to }, plus videos (titre, couverture, durée des ID présents) et hidden sur les séries vidéo, dans la même forme que les routes d’historique de l’API publique.


Lit le tableau de contenus : une carte par vidéo, en colonnes IDEA → SCRIPT → VALIDATED → TO_SHOOT → TO_EDIT → TO_SCHEDULE → PUBLISHED. Lecture seule. Cet outil n’a pas d’équivalent dans upstream.

Paramètres :

Champ Type Requis Description
contentId string Non Seulement cette carte
stage string Non Seulement les cartes de cette colonne
withNumbers boolean Non Ajoute les chiffres des cartes publiées (plus lent)

Retour : un tableau contents. Chaque carte comporte id, externalId (votre propre ID quand la carte a été créée avec un, sinon null), title, stage, tags, hook, hookText (le texte affiché à l’écran pendant les premières secondes), script et notes (en entier), resourceStatus, resourceUrl, resourceBrief, integrationIds, plannedAt, hasVideo, scheduledPosts (les canaux de la publication planifiée à partir d’elle), publishedAt, source (la vidéo d’un autre dont la carte est née, voir contentFromLinkTool ; null sur toute autre carte) et, avec withNumbers, numbers : views, engagementRate, followersGained, leads, emails.


Ajoute une carte au tableau. Elle arrive en bas de sa colonne. Une carte est visible sur le tableau et se supprime : cet outil écrit donc directement, sans confirmation, et n’écrase jamais une carte existante.

Paramètres :

Champ Type Requis Description
title string Oui Titre court de la vidéo
stage string Non La colonne de départ. IDEA par défaut
hook string Non L’accroche parlée, les premières secondes
hookText string Non Le texte affiché à l’écran pendant les premières secondes
script string Non
notes string Non
tags string[] Non Étiquettes libres, par ex. une série
resourceStatus string Non La ressource que la vidéo offre : READY, ou TO_CREATE (la carte reste alors hors de TO_SCHEDULE et de PUBLISHED)
resourceUrl string Non Où se trouve la ressource, ou où elle se trouvera
resourceBrief string Non Ce que contient la ressource, ou le prompt pour la fabriquer
integrationIds string[] Non Canaux visés, renvoyés par integrationList
plannedAt string Non Date de publication prévue, en UTC (YYYY-MM-DD HH:mm:ss)

Crée toujours une nouvelle carte. Pour créer ou mettre à jour une carte par votre propre ID (un import, une chaîne de production), passez par contentUpdateTool avec externalId.

Retour : created, l’id et le stage de la carte, ou errors.


Ajoute au tableau, comme idée, une vidéo publiée par quelqu’un d’autre, à partir de son lien : un TikTok, un reel ou un post vidéo Instagram, un Short YouTube. La carte arrive en tête de IDEA, avec le tag inspiration et la vidéo comme source. C’est la même chose que POST /contents/from-link de l’API publique.

Paramètres :

Champ Type Requis Description
url string Oui Le lien de la vidéo, tel que le bouton Partager de l’app le donne (https://www.tiktok.com/@user/video/123, https://vm.tiktok.com/…, https://www.instagram.com/reel/…, https://www.youtube.com/shorts/…) ; un texte qui contient le lien marche aussi
tags string[] Non Tags ajoutés à inspiration (20 au plus)

La carte est créée tout de suite. UseNadia lit ensuite la vidéo en arrière-plan : son auteur, sa légende, sa durée, ses vues du jour, une copie de sa vignette et la transcription de ce qu’elle dit. La vidéo elle-même n’est pas gardée. Relisez la carte avec contentListTool (contentId) une minute plus tard : source.status vaut PENDING pendant la lecture, READY une fois lue, FAILED quand la plateforme a refusé, et source.error dit pourquoi il n’y a pas de transcription (vidéo privée, lien court mort, carrousel photo, vidéo de plus de 10 minutes, YouTube qui refuse les serveurs de UseNadia).

La même vidéo envoyée à nouveau renvoie la carte qui la porte déjà (created: false), et rien n’est relu. Au plus 30 liens par heure et par compte.

Retour : created, content (la carte, sous la forme de contentListTool, avec sa source), message (une phrase courte qui dit où la vidéo est allée) et appUrl (la carte dans l’app) ; ou created: false et errors quand le lien n’est pas une vidéo TikTok, Instagram ou YouTube, ou au-delà du budget horaire.


Modifie une carte et/ou la déplace dans une autre colonne, en un seul appel. Seuls les champs fournis changent. Récupérez d’abord l’ID de la carte avec contentListTool.

Paramètres : contentId, ou externalId (votre propre ID pour la carte, un import, une chaîne de production : la carte qui le porte est mise à jour, et créée quand aucune ne le porte, title est alors requis et la colonne est IDEA par défaut ; un des deux exactement), puis au choix stage (déplace la carte en bas de cette colonne), title, hook, hookText, script, notes, tags (remplace la liste), resourceStatus, resourceUrl, resourceBrief, integrationIds (remplace la liste), plannedAt, postGroup (lie la carte à une publication déjà au calendrier : le groupe de cette publication, renvoyé par postsListTool ; chaque appel en ajoute un, et la carte passe d’elle-même en PUBLISHED quand la première de ses publications est en ligne).

Retour : updated (et created avec externalId, quand la carte vient d’être créée), l’id et le stage de la carte, ou errors quand la carte n’existe pas dans l’espace de travail, ou quand sa ressource est encore en TO_CREATE et que le déplacement vise TO_SCHEDULE ou PUBLISHED (les champs sont écrits, la carte reste où elle est).


Supprime une carte du tableau. Les publications planifiées à partir d’elle restent au calendrier. La suppression ne s’annule pas depuis l’app : c’est donc une action confirmée, et l’aperçu nomme la carte.

Paramètres :

Champ Type Requis Description
contentId string Oui La carte à supprimer
confirmationToken string Deuxième appel Le jeton du premier appel, une fois que l’utilisateur a dit oui

Retour : { deleted, needsConfirmation?, preview?, confirmationToken?, errors? } ; errors quand la carte n’existe pas dans l’espace de travail.


La bibliothèque. hooksFormsTool et hooksSearchTool lisent la bibliothèque mesurée par UseNadia : environ 25 800 premières phrases de vidéos de 61 comptes, chacune avec ses vues normalisées (ses vues rapportées à la médiane des vidéos publiées autour d’elle sur le même compte : 5 veut dire cinq fois ce que fait d’habitude ce compte). C’est la même pour tous les comptes, tenue à jour par UseNadia à chaque nouvelle mesure ; les outils ne font que la lire, personne n’y importe d’accroches.

Le quota. Les accroches rendues sont comptées par compte et par jour (UTC), selon l’offre. Une demande au-delà du plafond par appel est rognée, pas refusée : vous recevez le plafond (hooksFormsTool réduit d’abord les exemples par forme, puis le nombre de formes). Une fois le plafond du jour atteint, les deux outils ne rendent plus que le message, jusqu’à 00:00 UTC.

Offre Accroches par appel Accroches par jour (UTC)
Solo, Starter ultime 10 300
Équipe 30 1 000
Agence 50 3 000
Pendant l’essai de 7 jours, quelle que soit l’offre 5 50

Quand un appel est rogné ou refusé, la réponse porte quota : un texte en anglais, écrit pour l’agent, qui donne les accroches rendues et demandées, ce qui reste du jour, l’offre, le renouvellement à 00:00 UTC et l’offre du dessus (pendant l’essai : ce que donne l’offre une fois l’essai converti). L’agent le dit une fois à l’utilisateur, pas à chaque appel.

C’est l’outil à appeler quand quelqu’un veut des accroches pour une vidéo. Renvoie un catalogue de formes d’accroche (des familles) pour la vidéo en préparation, chacune avec de vraies accroches tirées de la bibliothèque : une sur le sujet lui-même quand la bibliothèque en a une, les autres tirées au hasard parmi les accroches de la famille. Deux appels ne donnent jamais les mêmes exemples. Lecture seule.

Les formes sont classées selon leur effet mesuré sur ce type de vidéo, mais l’ordre est faible. Les vues ne certifient jamais une accroche : elles suivent la taille du sujet, donc normViews est une information, pas un classement. La méthode : dire ce que la vidéo apporte et son sujet, écrire une proposition par forme en adaptant la forme de l’exemple (jamais son sujet), laisser la personne choisir. Ne jamais inventer une accroche de zéro, ne jamais en recopier une mot pour mot, ne jamais nommer un créateur.

Paramètres :

Champ Type Requis Description
nature string Non Ce que la vidéo apporte : tuto_methode, ressource_outil, liste_conseils, explication_concept, actu, opinion, story_perso, story_tiers, demo_build, humour_sketch, vie_coulisses. Absent : tout le corpus
q string Non Mots du sujet (accents et casse ignorés)
language string Non fr (par défaut), en ou all
forms integer Non Nombre de formes, de 1 à 15. 7 par défaut
examples integer Non Vraies accroches par forme, de 1 à 5. 2 par défaut

Retour : { forms }. Chaque forme : family, label, measuredOn (la nature d’où viennent les chiffres, all = tout le corpus), ratio (les vues comparées au reste à base égale), bangers (part des vidéos à deux fois la base ou plus), accountsFor, accountsAgainst, verdict et examples, chacun avec hook (la première phrase), opening (les quelque 40 premiers mots, pour le contexte seulement), normViews (5 = cinq fois ce que fait d’habitude ce compte), year, nature, subject et onSubject (si cette accroche porte sur le sujet demandé). Plus quota quand l’appel a été rogné ; au plafond du jour, quota seul (voir Le quota).

Exemple :

{ "nature": "liste_conseils", "q": "malte expatriation", "forms": 5 }

Cherche dans la bibliothèque de vraies accroches qui ont marché : environ 25 800 premières phrases de vidéos, chacune avec ses vues rapportées à la base de son compte, la même pour tout compte (voir La bibliothèque). Pour « donne-moi des accroches pour ma vidéo », hooksFormsTool passe en premier ; celui-ci est la recherche par mots, par famille ou par nature. Lecture seule. Expérimental, comme hooksFormsTool.

Paramètres :

Champ Type Requis Description
q string Non Mots du sujet, n’importe lesquels. Les accroches qui en contiennent le plus arrivent en premier
family string Non Seulement cette famille d’accroches (slug) : promesse_directe, ciblage_si_tu, ressource_cadeau, interdiction_erreur, reset_fantasy, story_perso, story_tiers, verite_cachee, peur_menace, avant_apres, defi_demo, opinion_polemique, actu_nouveaute, comparatif_meilleur, obligation_urgence, chiffre_fait_choc, question…
nature string Non Seulement les vidéos de cette nature (mêmes valeurs que hooksFormsTool)
language string Non fr (par défaut), en ou all
minNorm number Non Plancher de vues normalisées. 2 par défaut (au moins deux fois la base du compte) ; descendez à 1,5 quand le sujet est rare
limit integer Non De 1 à 100. 15 par défaut
withFamilies boolean Non Renvoie aussi l’effet mesuré de chaque famille d’accroches

Retour : total (la taille de toute la bibliothèque) et hooks, chacune avec year, language, hook, opening, views, normViews, family, nature, concrete, subject, lockinGestures et matchedWords. Avec withFamilies, families : family, n, accounts, ratio, bangers, accountsFor, accountsAgainst, verdict. Seule une famille au verdict prouvé fait une règle ; les autres se choisissent selon ce qui colle. Plus quota quand l’appel a été rogné ; au plafond du jour, quota seul (voir Le quota).

Exemple :

{ "q": "impôts malte", "minNorm": 1.5, "withFamilies": true }

Importe une image ou une vidéo dans la bibliothèque de médias à partir d’une URL. Le serveur télécharge lui-même le fichier : les octets ne passent jamais par l’appel MCP ni par l’assistant.

À utiliser avant de planifier une publication quand le média est hébergé ailleurs : une pièce jointe qui n’est pas déjà hébergée sur le domaine de UseNadia échoue à la validation du domaine d’upload. L’URL doit être en HTTPS et seulement joignable depuis le serveur sans connexion : une URL publique, ou une URL signée qui expire (R2, S3, une vidéo qu’un autre outil a transmise avec son lien de téléchargement). Les adresses privées, de loopback et link-local sont refusées, y compris après chaque redirection.

Le fichier passe par les mêmes contrôles qu’un upload direct confirmé (vrai type détecté d’après les octets, ffprobe) et revient avec ses chiffres, pour que l’appelant puisse les comparer à ce qu’annonçait la source : une taille différente veut dire que le téléchargement n’est pas le fichier voulu.

Paramètres :

Champ Type Requis Description
url string Oui L’URL HTTPS de l’image ou de la vidéo, joignable sans connexion

Retour :

Champ Type Description
id string ID du média
path string URL hébergée, à utiliser dans le tableau attachments
contentType string video/mp4, image/jpeg, image/png, image/webp ou image/gif : le type lu d’après les octets
size number Octets stockés
duration number | null En secondes pour une vidéo, null pour une image
width, height number Dimensions à l’affichage, rotation appliquée
codec string Codec de l’image (h264, hevc, png…)

Les types acceptés et la taille maximale sont ceux de createUploadUrl (500 Mo par défaut). Les erreurs portent un code : URL_UNREACHABLE (pas publique, expirée, ou a répondu par une erreur), FILE_TOO_LARGE, UNSUPPORTED_CONTENT_TYPE, FILE_CORRUPTED, DOWNLOAD_INTERRUPTED.


Obtient une URL à usage unique pour téléverser un fichier qui se trouve sur le disque du client (une vidéo coupée et compressée dans le bac à sable de code d’un assistant IA, par exemple), quand il n’y a pas d’URL publique à donner à uploadFromUrlTool. Les octets ne passent jamais par l’appel MCP : le client les envoie en PUT avec curl, puis appelle confirmUpload.

La séquence : createUploadUrl → lancer la commande curl renvoyée → confirmUpload → integrationSchedulePostTool (ou splitVideoIntoStories).

Toute URL d’upload vit sur un hôte à elle (https://upload.usenadia.com/api/uploads/…), qui ne sert rien d’autre : c’est le seul hôte qu’il faut autoriser dans le réseau d’un bac à sable. Elle est valable 15 minutes, pour un seul fichier, du type et de la taille déclarés, dans l’organisation qui l’a demandée, et ne donne accès à rien d’autre.

Paramètres :

Champ Type Requis Description
filename string Oui Nom ou chemin du fichier sur le disque du client, repris dans la commande curl ; son nom de base devient le nom du média
contentType string Oui video/mp4, image/jpeg, image/png, image/webp ou image/gif
size number Oui Taille exacte en octets. 500 Mo au plus par défaut (NADIA_DIRECT_UPLOAD_MAX_BYTES)

Retour :

Champ Type Description
uploadId string À passer à confirmUpload
uploadUrl string Où envoyer le fichier en PUT
method string Toujours PUT
headers object Les en-têtes exacts à envoyer : Content-Type et Content-Length
expiresAt string Date ISO, 15 minutes après l’appel
maxSize number La taille maximale de ce serveur, en octets
curl string La commande à lancer telle quelle, par ex. curl --fail-with-body -X PUT -T 'reel.mp4' -H 'Content-Type: video/mp4' 'https://upload.usenadia.com/api/uploads/…'

Le PUT répond 201 avec { uploadId, size }, ou par une erreur dont le message commence par un code : UPLOAD_URL_EXPIRED (410), UPLOAD_URL_ALREADY_USED (409), CONTENT_TYPE_MISMATCH (415), SIZE_MISMATCH (400), FILE_TOO_LARGE / SIZE_EXCEEDED (413), UPLOAD_URL_INVALID (404). Un transfert qui échoue en cours de route n’use pas l’URL : relancez la même commande.


Termine un upload une fois que son PUT a répondu 201. Vérifie la taille, que les octets sont bien du type déclaré et, pour une vidéo, que ffprobe sait la lire (codec, durée, dimensions à l’affichage, avec la rotation d’une vidéo de téléphone appliquée). Ajoute ensuite le fichier à la bibliothèque de médias. Un nouvel appel renvoie le même média.

Paramètres :

Champ Type Requis Description
uploadId string Oui Renvoyé par createUploadUrl

Retour :

Champ Type Description
id string ID du média
path string URL hébergée, à utiliser dans attachments, ou comme videoUrl dans splitVideoIntoStories
contentType string Le type déclaré, vérifié
size number Octets
duration number | null En secondes, null pour une image
width / height number À l’affichage
codec string Par ex. h264

Erreurs : FILE_NOT_UPLOADED, UPLOAD_IN_PROGRESS, UPLOAD_URL_EXPIRED, FILE_TYPE_MISMATCH, FILE_CORRUPTED, SIZE_MISMATCH, UPLOAD_NOT_FOUND. Les uploads jamais confirmés sont supprimés au bout de 24 heures.


Liste la bibliothèque de médias, les plus récents d’abord. Lecture seule, limitée à votre espace de travail. C’est ainsi qu’un agent trouve la vidéo que vous venez de téléverser depuis votre téléphone, sans vous demander de lien.

Paramètres :

Champ Type Requis Description
type string Non video ou image ; les deux s’il est absent
search string Non Une partie du nom de fichier, sans tenir compte de la casse
since string Non Seulement les médias téléversés à partir de cette date UTC (ISO 8601)
limit number Non 20 par défaut, 100 au plus
cursor string Non Le nextCursor de l’appel précédent, pour la page suivante

Retour : media et nextCursor (null sur la dernière page). Chaque média :

Champ Type Description
id string ID du média
path string URL hébergée : une entrée attachments de integrationSchedulePostTool, l’entrée de transcribe, cutVideo et splitVideoIntoStories
filename string Nom de fichier d’origine
type string video ou image
size number Octets, null si inconnu
createdAt string Date d’upload, ISO 8601 UTC
duration number Vidéos seulement : en secondes
width, height number Vidéos seulement : taille à l’affichage, rotation appliquée (height > width = vertical)

La taille, la durée et les dimensions sont lues avec ffprobe la première fois qu’un média est listé, puis conservées.


Transcrit une vidéo de la bibliothèque avec ElevenLabs Scribe (langue détectée automatiquement), avec les horodatages.

Paramètres :

Champ Type Requis Description
path string L’un des deux Chemin renvoyé par mediaList
mediaId string L’un des deux Ou l’ID du média
includeWords boolean Non Renvoie aussi chaque mot avec ses horodatages. false par défaut

Retour :

Champ Type Description
mediaId, path string La vidéo transcrite
language string Langue détectée (ISO 639)
cached boolean true quand la transcription est relue d’une transcription antérieure
text string La transcription complète
segments array Un { start, end, text } par phrase, en secondes
words array Seulement avec includeWords : { start, end, text } par mot

Coupe une vidéo de la bibliothèque à des horodatages exacts. Chaque partie est réencodée (H.264 + AAC, yuv420p, +faststart, rotation appliquée, résolution d’origine) et ajoutée à la bibliothèque. Fournissez exactement l’un des deux : cuts ou segments.

Paramètres :

Champ Type Requis Description
path string Oui Chemin du mp4, renvoyé par mediaList
cuts number[] L’un des deux Secondes où couper : [24.45] donne deux parties qui couvrent toute la vidéo
segments array L’un des deux Passages à garder, [{ start, end }] : chacun devient une partie, dans l’ordre donné

Chaque partie dure au moins 0,5 s, 20 parties au plus, et chaque horodatage tombe dans la vidéo.

Retour : duration (de l’original) et parts, dans l’ordre, chacune avec id, path, start, end et duration.


Découpe une vidéo de la bibliothèque de médias en une série de stories de longueur à peu près égale : 20 secondes sauf demande d’une autre durée, entre 10 et 30. Les coupes tombent dans un silence de la vidéo quand il y en a un assez proche, à intervalles réguliers sinon, et les stories s’enchaînent. La durée est une cible, pas une découpe stricte : quelques secondes de reste sont réparties dans les stories au lieu d’en faire une dernière minuscule (2 min 02 à 20 s donne 6 stories d’environ 20 s ; 30 s donne 2 stories de 15).

Paramètres :

Champ Type Requis Description
videoUrl string Oui URL du mp4 : un path renvoyé par mediaList, uploadFromUrlTool ou confirmUpload, ou l’URL d’une vidéo jointe dans le chat
targetSeconds number Non Durée visée pour chaque story, en secondes, de 10 à 30. 20 par défaut
removeSilences boolean Non Retire les longues pauses de la vidéo avant de la couper. false par défaut : un agent ne l’active que si l’utilisateur demande explicitement de retirer les silences, jamais de lui-même et jamais en suggestion

Retour : duration (de la vidéo coupée), silencesRemoved (secondes de silence retirées, 0 si ce n’était pas demandé) et stories, dans l’ordre, chacune avec id, path (la pièce jointe de sa propre publication story), start, end et endsOn : silence (la coupe est tombée dans une pause), even (pas de silence assez proche, coupe à intervalle régulier) ou end (dernière story).

Chaque story se planifie ensuite comme une publication à part avec integrationSchedulePostTool : un socialPost par story, dans l’ordre, exactement une pièce jointe, un contenu vide et le réglage Instagram post_type = story, à une minute d’écart pour que chacune soit publiée avant la suivante.

Exemple :

{ "videoUrl": "https://app.usenadia.com/uploads/2026/10/reel.mp4", "targetSeconds": 15 }

Les notifications de l’espace de travail, les plus récentes d’abord (la cloche de l’app) : une publication publiée ou en échec, un canal à reconnecter, un e-mail capté par une automatisation… 100 par page. Lecture seule.

Paramètres : page (integer, facultatif, 0 = les plus récentes).

Retour : { notifications, total, page, hasMore }. Chaque notification : id, content (texte brut), link, at.


Les webhooks sortants de l’espace de travail et le catalogue des événements auxquels un webhook peut s’abonner. Lecture seule.

Paramètres : webhookId (string, facultatif, seulement celui-ci).

Retour : { webhooks, events }. Chaque webhook : id, name, url, events (vide = tous les événements), integrations (vide = tous les canaux), hasSecret. Le secret de signature lui-même n’est montré qu’une fois, par webhookManageTool à la création.


Enregistre, teste ou supprime un webhook sortant.

Paramètres :

Champ Type Requis Description
action string Oui create, test ou delete
webhookId string test, delete Le webhook
event string Non test : l’événement à simuler (par défaut : le premier événement du webhook, ou post.published s’il les reçoit tous)
name string create
url string create Une URL HTTPS publique
events string[] Non create : les événements à recevoir (vide = tous), noms tirés de webhooksListTool
integrationIds string[] Non create : les canaux (vide = tous), ceux de votre organisation ; un autre id est refusé dès le premier appel
confirmationToken string create, delete, deuxième appel Le jeton du premier appel, une fois que l’utilisateur a dit oui

create et delete sont des actions confirmées : un webhook envoie à son URL tout ce à quoi il est abonné (DM, e-mails captés…) tant qu’il existe. test agit tout de suite.

Retour : { ok, errors? }, plus webhook à la création, avec son secret, renvoyé une seule fois : les livraisons sont signées avec lui (X-Nadia-Signature, HMAC SHA-256 du corps).

test envoie une livraison à ce seul webhook, sans aucun événement réel : l’enveloppe signée habituelle avec test: true et un data d’exemple (de faux ID test_…, rien n’est publié). Il attend la réponse (une tentative, pas de nouvel essai, délai de 10 secondes) et renvoie { ok, delivered, status, event, deliveryId } : status est le code HTTP qu’a répondu l’URL, null quand rien n’a répondu. Équivaut à POST /public/v1/webhooks/{id}/test.