Hooks and music

Note

Paths are relative to the base URL: https://app.usenadia.com/api/public/v1. Every request needs an Authorization header holding your API key.

Experimental

These two resources feed UseNadia’s video pipeline: the agent that writes a script searches a hook that worked and adapts its form; the one that mounts a video picks a track at the right level. They are read-only for an API key, their shapes follow the studies they come from, and they may change without the rest of the API moving. Neither exists in the original project.

GET /hooks                   search the hooks that worked
GET /hooks/forms             the best hook forms for a video, with examples
GET /hooks/families          the measured effect of each family
GET /music                   pick tracks
GET /music/pillars           what each pillar is for
GET /music/{slug}            one track

Hooks

The hook is the first sentence of a video. The library holds real hooks with their views at the baseline of their account (normViews: ×5 means five times the account’s usual views) and the labels of the studies. Nothing that comes out names a creator.

Search

GET /hooks?q=malte+impôts&nature=tuto_methode&limit=20

Query	Type	Description
q	string ≤ 200	Words looked up in the hook, its opening and the subject; the hooks matching the most words come first, then the best normViews
family	string	Only this hook family
nature	string	What the video delivers: tuto_methode, ressource_outil…
language	fr | en | all	Default fr
minNorm	number ≥ 0	Only hooks at or above this normViews
limit	1–100

Response 200: { "total", "hooks": [ … ] }, total being the size of the whole library. Each hook carries hook, opening (the first ~40 words), views, normViews, family, nature, subject, language and matchedWords.

Forms

GET /hooks/forms?nature=tuto_methode&q=malte&forms=5&examples=3

Query	Type	Description
nature	string	The nature of the video being prepared
q	string ≤ 200	Its subject: one example on it comes first when there is one
language	fr | en | all
forms	1–15	How many families
examples	1–5	Real hooks per family, drawn at random (two calls never give the same)

Response 200: an array of families ordered (weakly) by their measured effect on that nature — family, label, ratio, ps, bangers, accountsFor, accountsAgainst, verdict, and examples. Views follow the size of the subject: they do not rank the examples.

Families

GET /hooks/families?nature=all

The measured effect of each family on the corpus: ratio (views vs the rest at equal baseline, ×1.10 = +10 %), ps (probability of superiority, 0.50 = no effect), bangers (share of videos at ≥ 2× the baseline), accountsFor / accountsAgainst, and a verdict. Only a PROUVÉ family is a rule.

Music

A global catalogue of public domain and CC-BY tracks, prepared so that one recipe sets the level under any voice: dynamics flattened, loudness normalised. The same catalogue for every organisation.

Pick tracks

GET /music?pillar=piano&minDuration=60&limit=5

Query	Type	Description
pillar	piano | news | synthwave | epique	Storytelling and educational; tension and news; tech; cinematic
minDuration	number ≥ 0	Seconds
q	string ≤ 100	Text in the title or the artist
includeLimite	boolean	Also the limite tracks (usable, a bit fast or a punch early on)
limit	1–100

Response 200: { "total", "howTo", "tracks": [ … ] }. howTo is the recipe, the same for every track: level under the voice, mix, credit line. ok tracks come first, in a random order. Each track carries slug, title, artist, pillar, durationS, bpm, intro, verdict, license, attributionRequired, creditLine (the exact line to paste at the bottom of the description, null when nothing is owed), url (the prepared MP3) and storedLufs.

Pillars and one track

GET /music/pillars       → [ { pillar, use, ok, limite } ]
GET /music/{slug}        → one track, 404 when unknown

Reserved write routes

Four write routes exist on these resources and are not for an API key: they are how the catalogues are fed.

POST /hooks/import           upsert up to 500 hooks
PUT  /hooks/families         replace the family table
POST /music/import           upsert the track metadata
PUT  /music/{slug}/file      upload a prepared MP3

The two hook routes are written by UseNadia’s content pipeline, hundreds of rows at a time. The two music routes answer 403 unless the key belongs to a super admin: the catalogue is global, not yours to write. None of the four is exposed to the MCP agent either.