Aller au contenu

Présentation de l’API

L’API publique, c’est tout ce que fait l’app, en HTTP : le composeur, l’agent, la CLI, le node n8n et le serveur MCP passent tous par elle. C’est un fork de l’API d’upstream : mêmes routes de base, plus plusieurs ressources qu’upstream n’a pas.

UseNadia a son propre SDK Node.js (@usenadia/node) et son propre node n8n (n8n-nodes-nadia). Aucun des deux n’est encore publié sur npm. Les paquets d’upstream ne les remplacent pas : ils parlent à son API, pas à celle-ci.

Deux façons de s’authentifier :

Votre clé API se trouve dans UseNadia, sous Paramètres → Développeurs, section Accès, à la ligne Clé API. Cliquez sur l’icône d’affichage pour la révéler, puis copiez-la. Elle se renouvelle au même endroit, et le renouvellement invalide l’ancienne clé aussitôt : mettez à jour en même temps tout ce qui s’en sert (scripts, n8n, clients MCP, la CLI).

Passez-la dans l’en-tête Authorization :

Fenêtre de terminal
curl -H "Authorization: your-api-key" https://app.usenadia.com/api/public/v1/integrations

Pour une app destinée à d’autres utilisateurs de UseNadia, passez par l’authentification OAuth2 : elle donne des jetons qui agissent au nom des utilisateurs. Un jeton OAuth commence par pos_ et s’utilise de la même façon :

Fenêtre de terminal
curl -H "Authorization: pos_your-oauth-token" https://app.usenadia.com/api/public/v1/integrations

L’URL de base est https://app.usenadia.com/api.

Un GET, PUT ou DELETE réussi répond 200 ; un POST réussi répond 201. Une erreur porte { "msg": "…" }, sauf une publication refusée par la plateforme, qui porte { provider, name, error }.

Statut Signification
400 Bad Request Le corps ou un paramètre est mal formé (mauvaise forme, valeur d’enum inconnue, champ obligatoire absent), ou la plateforme a refusé la publication.
401 Unauthorized L’en-tête Authorization manque, ou la clé API n’est pas reconnue.
403 Forbidden La clé est valide mais n’a pas le droit de faire ça (les routes d’écriture de la musique, par exemple).
404 Not Found La route n’existe pas, ou le canal, la publication ou l’enregistrement du chemin n’est pas dans votre organisation.
409 Conflict Une carte de contenu avec ce externalId existe déjà, ou une carte ne peut pas encore aller dans cette colonne.
413 Payload Too Large Le corps a dépassé 50 Mo sur /posts, en général parce que les images étaient intégrées en base64 au lieu d’être téléversées avant. Voir Dépannage des téléversements.
429 Too Many Requests La limite horaire de POST /posts est dépassée.
5xx Erreur serveur : réessayez avec un délai croissant (backoff exponentiel).

Sur les routes DELETE, un 404 veut toujours dire « déjà supprimé » et s’ignore sans risque. Les autres 500 sont de vraies erreurs serveur : journalisez-les, réessayez avec un backoff exponentiel, et ne les étouffez pas en silence.

Six de ces groupes de ressources n’existent pas chez upstream : le tableau de contenus, les automatisations, l’Inbox, les analyses collectées, les webhooks, et les hooks et la musique. Les réglages propres à chaque plateforme pour une publication sont sur les pages Instagram et TikTok.

Six canaux se connectent ici, et tous publient :

Plateforme __type Réglages principaux
Instagram instagram-standalone post_type, is_trial_reel, graduation_strategy, share_to_feed, collaborators, automationFlowId, automationKeywords, automationVariables
TikTok tiktok content_posting_method, privacy_level, duet, stitch, comment, autoAddMusic, brand_content_toggle, brand_organic_toggle, video_made_with_ai, title
X x who_can_reply_post, community, made_with_ai, paid_partnership
LinkedIn linkedin post_as_images_carousel, carousel_name
YouTube youtube title, type, selfDeclaredMadeForKids, tags, thumbnail
Threads threads aucun : settings ne porte que __type

À la création d’une publication, l’objet settings doit contenir un champ __type qui correspond à la plateforme du canal.

Le plus simple pour générer vos payloads de publication, c’est le composeur lui-même : le même assistant que celui qui planifie dans l’app, sauf qu’au lieu de planifier, il génère le payload JSON de vos requêtes API.

Connectez-vous d’abord à app.usenadia.com.

Ouvrir en plein écran

Fenêtre de terminal
# Étape 1 : téléverser
curl -X POST "https://app.usenadia.com/api/public/v1/upload" \
-H "Authorization: your-api-key" \
-F "file=@reel.mp4"
# 201 → { "id": "cm4med0001", "path": "https://media.usenadia.com/k3J9aQ2xZp.mp4", ... }
# Étape 2 : créer la publication avec le média téléversé
curl -X POST "https://app.usenadia.com/api/public/v1/posts" \
-H "Authorization: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"type": "schedule",
"date": "2026-11-03T10:00:00.000Z",
"shortLink": false,
"tags": [],
"posts": [{
"integration": { "id": "your-instagram-id" },
"value": [{
"content": "Trois choses que personne ne dit sur Malte.",
"image": [{ "id": "cm4med0001", "path": "https://media.usenadia.com/k3J9aQ2xZp.mp4" }]
}],
"settings": { "__type": "instagram-standalone", "post_type": "post" }
}]
}'
# 201 → [ { "postId": "cm4post0001", "integration": "your-instagram-id" } ]
{
"type": "now",
"date": "2026-11-03T10:00:00.000Z",
"shortLink": false,
"tags": [],
"posts": [
{
"integration": { "id": "your-tiktok-id" },
"value": [
{
"content": "Trois choses que personne ne dit sur Malte.",
"image": [{ "id": "cm4med0001", "path": "https://media.usenadia.com/k3J9aQ2xZp.mp4" }]
}
],
"settings": {
"__type": "tiktok",
"content_posting_method": "DIRECT_POST",
"privacy_level": "PUBLIC_TO_EVERYONE",
"duet": true,
"stitch": true,
"comment": true,
"autoAddMusic": "no",
"brand_content_toggle": false,
"brand_organic_toggle": false
}
}
]
}
{
"settings": {
"__type": "instagram-standalone",
"post_type": "story",
"automationFlowId": "<template id>",
"automationKeywords": ["LIEN", "LEIN", "GUIDE"],
"automationVariables": { "ressource": "le guide Malte", "bouton": "Le guide", "lien": "https://…" }
}
}

La pose est créée au moment où la publication part, pas à la planification : Instagram n’a pas d’identifiant de média avant. Les mots-clés et les valeurs sont vérifiés dès la planification. Voir Automatisations.

GET /notifications?page=0

Les notifications de l’organisation, les plus récentes d’abord, 100 par page (page commence à 0) : une publication partie, une publication en échec, un canal à reconnecter. Réponse 200 :

{
"notifications": [
{ "id": "a1b2c3d4-…", "content": "Your post to Instagram was published successfully", "link": null, "createdAt": "2026-10-20T10:30:00.000Z" }
],
"total": 250,
"page": 0,
"limit": 100,
"hasMore": true
}

Pour être prévenu plutôt que d’interroger, enregistrez un webhook.