music nerd
music nerd

OnboardingOnboarding chat turn

Onboarding

Onboarding chat turn

One turn of an artist's onboarding, streamed as server-sent events. The server owns the step order (profiles → vault → interview → publish): a turn for a step that is not current gets an error event and the real step. Confirmed steps are resumed rather than repeated. Claim approval grants editing rights; it never approves sources or publishes an About. A turn stops at 55 seconds and says so, and the server finishes the work even if the client disconnects.

Each event is a data: line holding one JSON object with a kind: chat, progress, step, candidate, linked, unreachable, source, sources, text-delta, choices, draft, complete or error. A turn ends with step, draft, complete or error.

The initial interview prepares up to three questions once from already saved material, with one 15-second total preparation budget. It does not wait for a social scrape. Drafting and source verification share that deadline; timed-out model work is cancelled and only verified questions may be used. Remaining slots use distinct optional general questions. The private question plan is reused after answers, skips, reloads and server restarts, scoped to the current claim. Choosing a fallback plan does not retry generation on each skip. Prepared questions are not artist testimony; only explicit answers/skips create answer records. Saved history is checked before offering the next question; a history read failure returns a recoverable error rather than restarting or completing the interview. Each answered/skipped key counts once toward the three-question cap. Existing answer revisions and explicit publication are unchanged.

POST/api/onboarding/{artistId}/chat
POST/api/onboarding/aab92f80-f9e1-4299-aa33-7dd85c8de5d3/chat

One turn of an artist's onboarding, streamed as server-sent events. The server owns the step order (profiles → vault → interview → publish): a turn for a step that is not current gets an error event and the real step. Confirmed steps are resumed rather than repeated. Claim approval grants editing rights; it never approves sources or publishes an About. A turn stops at 55 seconds and says so, and the server finishes the work even if the client disconnects.

This one can’t run in the browser. Copy the curl and run it from a terminal.

Authorization

Authorizationstringrequired

The signed-in user's access token. Copy it at https://musicnerd.net/access after signing in. The user must be the artist's approved claimant or a Music Nerd admin. Kept in this tab only.

Path

artistIdstringrequired

The artist's ID (a UUID). Staging and production IDs differ.

Body
cURL
curl --request POST \
  --url 'https://musicnerd-api.vercel.app/api/onboarding/aab92f80-f9e1-4299-aa33-7dd85c8de5d3/chat' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "open"
}'

Send the request to see the live response here.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>. The signed-in user's access token. Copy it at https://musicnerd.net/access after signing in. The user must be the artist's approved claimant or a Music Nerd admin.

Path Parameters

artistIdstringrequired

The artist's ID (a UUID). Staging and production IDs differ.

Body

application/jsonrequired
oneOf · object 1

Start or resume. A fresh claim uses completed directory discovery when its versioned checkpoint is at most 24 hours old, belongs to the original directory-add event, and still matches the artist identity and source content. Approving or rejecting sources does not invalidate that discovery. Reuse shows saved profiles and pending sources for explicit review without repeating profile or web discovery. Saved Deezer artist IDs and YouTube channel IDs render as their canonical public profile URLs, and a stored channel counts as an existing YouTube profile; missing, incomplete, stale or changed discovery does not suppress a new search. Discovery completion has its own immutable timestamp; a parent job still pending, running or failed while handing off later work can reuse the completed discovery. Downstream queue retries do not restart discovery or reset an existing child job. Social collection and caption processing have separate completion state. The artist can still request more profiles or refresh research explicitly. Opening never approves sources or publishes an About.

typeanyrequired
oneOf · object 2

Confirm the profiles step, adding and removing links.

typeanyrequired
addedLinksarray<object>required

maxItems: 100

Item properties for addedLinks
urlstringrequired
removedSiteNamesarray<string>required

maxItems: 100

Item properties for removedSiteNames

string

oneOf · object 3

Apply link changes and search again, without confirming the step.

typeanyrequired
addedLinksarray<object>

maxItems: 100

Item properties for addedLinks
urlstringrequired
removedSiteNamesarray<string>

maxItems: 100

Item properties for removedSiteNames

string

oneOf · object 4

Explicitly approve or reject the displayed sources and add URLs. All pending sources must be reviewed before moving on. Previously rejected sources stay rejected; claim approval and opening the chat do not approve them. Generated text can reuse a private prepared draft only when every cited original is unchanged and approved and no newer artist material would be omitted.

typeanyrequired
decisionsarray<object>required

maxItems: 100

Item properties for decisions
sourceIdstringrequired

format: uuid

statusstring · enumrequired

Values: "approved", "rejected"

addedUrlsarray<string>required

maxItems: 100

Item properties for addedUrls

string

oneOf · object 5

Answer or skip one interview question.

typeanyrequired
questionKeystringrequired
answerstring | nullrequired

null skips the question.

questionstring

The question text, for grounded (social_…) questions.

oneOf · object 6

Generate the About from the doc, or write it yourself.

typeanyrequired
modestring · enumrequired

Values: "generate", "self"

docstringrequired
sourcesarray<object>
Item properties for sources

object

oneOf · object 7

Publish the About and save the doc; confirms the publish step.

typeanyrequired
docstringrequired
aboutstringrequired
sourcesarray<object>
Item properties for sources

object

expectedBiostring | nullrequired

The bio the draft started from; a different current bio is refused.

Response

text/event-stream

A stream of turn events.

string