Aller au contenu

Tableau de contenus

Le tableau de contenus porte une carte par vidéo, à travers sept colonnes :

IDEA → SCRIPT → VALIDATED → TO_SHOOT → TO_EDIT → TO_SCHEDULE → PUBLISHED

La carte ne disparaît pas quand la vidéo sort : liée aux publications planifiées à partir d’elle, elle passe d’elle-même en PUBLISHED quand la première d’entre elles est en ligne, puis porte leurs chiffres. Ces endpoints lisent et écrivent les mêmes cartes que le tableau de l’app : une carte créée depuis une note vocale, une page Notion ou un DM y apparaît aussitôt.

Ces endpoints n’existent pas chez upstream.

GET /contents
GET /contents/performance
GET /contents/{id}
POST /contents
POST /contents/upsert
POST /contents/from-link
PUT /contents/{id}
PUT /contents/{id}/move
PUT /contents/{id}/post
DELETE /contents/{id}

Une carte d’une autre organisation, ou une carte supprimée, répond 404.

POST /contents

Champ Type Obligatoire Description
title string Oui Titre court de la vidéo
externalId string Non Votre propre identifiant pour la carte (un chemin de fichier de script, un identifiant de build). Unique par organisation : une seconde carte avec le même répond 409
stage string Non La colonne de départ. Par défaut IDEA
hook string Non Le hook parlé, les premières secondes qui arrêtent le scroll. Markdown
hookText string Non Le texte affiché à l’écran pendant les premières secondes
script string Non Markdown : le tableau le met en forme (tableaux, gras, listes)
notes string Non
tags string[] Non Étiquettes libres, par exemple une série
resourceStatus string Non La ressource que la vidéo offre (un lien, un guide, une masterclass) : READY, ou TO_CREATE. Absent : pas de ressource. Voir La ressource d’une vidéo
resourceUrl string Non Où la ressource se trouve, ou se trouvera
resourceBrief string Non Ce que contient la ressource, ou le prompt pour la produire. Markdown
integrationIds string[] Non Les canaux auxquels la vidéo est destinée
plannedAt string Non Date ISO à laquelle la vidéo doit sortir
parentId string Non La carte dont celle-ci est une déclinaison

La carte arrive en bas de sa colonne. La réponse est un 201 avec la carte.

{
"title": "Three mistakes when moving to Malta",
"hook": "Nobody told me about the third one.",
"integrationIds": ["cm4ean69r0003w8w1cdomox9n"]
}

POST /contents/upsert prend les mêmes champs que la création, avec externalId obligatoire. La carte qui porte cet externalId est mise à jour avec les champs envoyés ; s’il n’y en a pas, une carte est créée. Relancer un import ne crée donc jamais de doublon, et vous n’avez pas à tenir une table de correspondance entre vos identifiants et les nôtres.

Sur une carte existante, stage est ignoré : quelqu’un a pu déplacer la carte entre-temps, et l’import ne doit pas la ramener en arrière. Pour la déplacer : PUT /contents/{id}/move.

La réponse est { "created": true | false, "content": { … } }.

Une carte supprimée libère son externalId : l’upsert suivant crée une nouvelle carte.

POST /contents/from-link fait du lien d’une vidéo publiée par quelqu’un d’autre (un TikTok, un reel ou un post vidéo Instagram, un Short YouTube) une carte d’idée : en tête de IDEA, avec le tag inspiration et la vidéo comme source.

Champ Type Obligatoire Description
url string L’un des deux Le lien de la vidéo, tel que le bouton Partager de l’app le donne. Les paramètres de suivi sont retirés, et un lien court TikTok (vm.tiktok.com) est suivi
text string L’un des deux Ce qu’un partage envoie avec le lien (« regarde ça https://vm.tiktok.com/… ») : le premier lien de vidéo qu’il contient est lu quand url n’en a pas
tags string[] Non Tags ajoutés à inspiration (20 au plus)

La carte est créée tout de suite, et la réponse est un 202 :

{
"created": true,
"content": { "id": "…", "stage": "IDEA", "tags": ["inspiration"], "source": { "platform": "tiktok", "status": "PENDING", "…": "…" } },
"message": "Added to your ideas: @creator · TikTok",
"appUrl": "https://app.usenadia.com/content?open=…"
}

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 jamais gardée. Relisez la carte avec GET /contents/{id} : source.status passe à READY, ou à FAILED quand la plateforme a refusé la vidéo.

La même vidéo envoyée à nouveau répond 200 avec la carte qui la porte déjà (created: false), et rien n’est relu. Un lien qui n’est pas une vidéo TikTok, Instagram ou YouTube répond 400, et plus de 30 liens en une heure 429. message est une phrase courte en anglais, pour une notification.

La source d’une carte :

Champ Description
url Le lien canonique de la vidéo
platform tiktok, instagram ou youtube
embedUrl Le lecteur de la plateforme pour cette vidéo, à afficher dans un cadre ; null quand il n’y en a pas
author Le pseudo de l’auteur, sans @
caption, duration, views Tels qu’au jour du partage, jamais rafraîchis. Instagram ne donne pas les vues
thumbnail La copie de la vignette chez UseNadia
status PENDING pendant la lecture, READY une fois lue, FAILED quand la plateforme l’a refusée
error Pourquoi il n’y a pas de transcription : un code, deux-points, puis une phrase. PRIVATE, DEAD_LINK, LOGIN_REQUIRED (la plateforme refuse les serveurs de UseNadia : YouTube aujourd’hui), PHOTO_CAROUSEL, TOO_LONG (plus de 10 minutes), NO_VOICE, TOO_LARGE, NO_SUBSCRIPTION, UNAVAILABLE, TRANSCRIPTION_FAILED
transcript { text, language, segments } ; segments, le texte en morceaux datés, seulement sur GET /contents/{id}
at Quand la vidéo a été partagée

Sur toute autre carte, source vaut null.

PUT /contents/{id} prend les mêmes champs que la création, sauf stage et parentId, plus videoMediaId et videoPath (la vidéo finale, issue de la bibliothèque de médias). Seuls les champs envoyés changent, et null en vide un.

PUT /contents/{id}/move

Champ Type Obligatoire Description
stage string Oui La colonne cible
position number Non Rang dans la colonne (fractionnaire, croissant). Absent : la carte va en bas

Une vidéo qui promet un lien (les ressources qu’elle cite, un guide, une masterclass) ne doit pas sortir avant que le lien mène quelque part. Une carte dont le resourceStatus vaut TO_CREATE ne peut donc pas aller en TO_SCHEDULE ni en PUBLISHED : le déplacement, ou une création directement dans l’une de ces colonnes, répond 409. Passez resourceStatus à READY une fois la ressource prête.

La carte se déplace quand même d’elle-même quand l’une de ses publications passe en ligne (voir plus bas) : c’est un fait, pas un choix.

PUT /contents/{id}/post avec { "postGroup": "…" } : le group d’une publication créée avec POST /posts. Une carte porte plusieurs publications, par exemple un brouillon TikTok envoyé maintenant et une publication Instagram planifiée pour demain : chaque appel en ajoute une aux postGroups de la carte, et envoyer deux fois le même groupe ne change rien. Une carte encore avant TO_SCHEDULE y saute, et elle passe en PUBLISHED quand le premier canal de n’importe laquelle de ses publications est en ligne (tout de suite, si l’un l’est déjà).

Une publication TikTok envoyée dans la boîte de réception de l’app (SENT_UNCONFIRMED) ne compte pas comme en ligne : la vidéo attend encore que quelqu’un la publie dans TikTok.

GET /contents renvoie toutes les cartes, dans l’ordre du tableau. En plus de ses champs, chaque carte a childrenCount (les cartes déclinées à partir d’elle) et posts : une entrée par canal de chaque publication planifiée à partir d’elle, avec son state, sa publishDate et sa releaseURL, et source (la vidéo dont la carte est née, voir Une carte depuis un lien) : null sur toute autre carte. GET /contents/{id} renvoie une seule carte, sous la même forme.

Paramètres de requête, tous facultatifs et combinables :

Paramètre Description
stage Seulement cette colonne
tag Seulement les cartes qui portent ce tag
externalId La carte qui porte cet identifiant
fields Champs à renvoyer, séparés par des virgules, par exemple id,title,stage. L’identifiant revient toujours ; un champ inconnu répond 400. Absent : tous les champs reviennent, scripts compris
GET /contents?stage=SCRIPT&fields=id,title,externalId

GET /contents/performance renvoie un objet indexé par identifiant de carte, pour les cartes publiées liées à une publication :

Champ Description
views Somme sur les canaux. null quand aucun canal n’est collecté, jamais un 0 que personne n’a mesuré
engagementRate Interactions / vues, en %
skipRate Instagram seulement, pondéré par les vues
followersGained Ce que les comptes ont gagné dans les 48 heures après publication
leads, emails Les personnes passées par une automatisation posée sur la publication, et les adresses collectées
channels Les mêmes chiffres, par canal

Les compteurs viennent de l’historique collecté, relevé toutes les 30 minutes : un canal dont la collecte est coupée a des valeurs nulles.