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.
Endpoints
Section intitulée « Endpoints »GET /contentsGET /contents/performanceGET /contents/{id}POST /contentsPOST /contents/upsertPOST /contents/from-linkPUT /contents/{id}PUT /contents/{id}/movePUT /contents/{id}/postDELETE /contents/{id}Une carte d’une autre organisation, ou une carte supprimée, répond 404.
Créer une carte
Section intitulée « Créer une carte »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"]}Créer ou mettre à jour par votre identifiant
Section intitulée « Créer ou mettre à jour par votre identifiant »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.
Une carte depuis un lien
Section intitulée « Une carte depuis un lien »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.
Mettre à jour une carte
Section intitulée « Mettre à jour une carte »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.
Déplacer une carte
Section intitulée « Déplacer une carte »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 |
Forme de la ressource
Section intitulée « Forme de la ressource »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.
Lier une carte à ses publications
Section intitulée « Lier une carte à ses publications »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.
Lister les cartes
Section intitulée « Lister les cartes »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,externalIdLes chiffres
Section intitulée « Les chiffres »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.