music nerd

Interview memory and sessionsPrepare or offer the next question

Interview memory and sessions

Prepare or offer the next question

action=prepare queues durable work in the existing research-job system and returns preparation status without waiting for model generation. action=consume atomically rechecks the current session, ordinal, mandatory memory and evidence before offering the entire checked bank atomically at explicit Start, without generating on consume. Returns question (first unanswered) plus questions (all authoritative sitting rows); offeredAt is fixed for every bank question at this transaction; it returns the saved question. At most three sequential questions per sitting. For a session that has explicitly opted into durable preparation, all bank questions are offered at Start; subsequent answer saves preserve exact text and do not generate or run an eligibility model. New answers inform future sittings, not adaptive changes to the fixed current bank. Legacy partially offered checked banks can be upgraded through explicit Resume/consume when current memory and evidence still match. Existing offered questions and their timestamps are preserved; GET only exposes the needsPreparedBankResume hint. Changed memory prevents expansion. Legacy foreground sessions are unchanged. Preparation itself does not set offeredAt or expose a question to the artist. Actual current approved claimant only; administrator status alone is insufficient. Bearer authentication is verified on every request; bearer tokens are never stored in the job. Private/no-store. Approved claims may automatically queue private question preparation after source research. The artist still explicitly chooses Start before any question is offered. Existing jobs wait for readable approved originals or artist-owned social text; pending Lore alone is not usable evidence. Existing readable artist context can proceed without waiting for unrelated Latest or ongoing research jobs. Waiting runs no model or scrape. Automatic waiting stops after 24 hours, and the same job becomes eligible again when usable evidence appears. Exact claimant ownership is rechecked before preparing. Reading pages or GET status never queues this work.

POST/api/artist/{artistId}/interview/session/{sessionId}/prepare
POST/api/artist/{artistId}/interview/session/{sessionId}/prepare

action=prepare queues durable work in the existing research-job system and returns preparation status without waiting for model generation. action=consume atomically rechecks the current session, ordinal, mandatory memory and evidence before offering the entire checked bank atomically at explicit Start, without generating on consume. Returns question (first unanswered) plus questions (all authoritative sitting rows); offeredAt is fixed for every bank question at this transaction; it returns the saved question. At most three sequential questions per sitting. For a session that has explicitly opted into durable preparation, all bank questions are offered at Start; subsequent answer saves preserve exact text and do not generate or run an eligibility model. New answers inform future sittings, not adaptive changes to the fixed current bank. Legacy partially offered checked banks can be upgraded through explicit Resume/consume when current memory and evidence still match. Existing offered questions and their timestamps are preserved; GET only exposes the needsPreparedBankResume hint. Changed memory prevents expansion. Legacy foreground sessions are unchanged. Preparation itself does not set offeredAt or expose a question to the artist. Actual current approved claimant only; administrator status alone is insufficient. Bearer authentication is verified on every request; bearer tokens are never stored in the job. Private/no-store. Approved claims may automatically queue private question preparation after source research. The artist still explicitly chooses Start before any question is offered. Existing jobs wait for readable approved originals or artist-owned social text; pending Lore alone is not usable evidence. Existing readable artist context can proceed without waiting for unrelated Latest or ongoing research jobs. Waiting runs no model or scrape. Automatic waiting stops after 24 hours, and the same job becomes eligible again when usable evidence appears. Exact claimant ownership is rechecked before preparing. Reading pages or GET status never queues this work.

Authorization

Authorizationstringrequired

Kept in this tab only.

Path

artistIdstringrequired

sessionIdstringrequired

Body
cURL
curl --request POST \
  --url 'https://musicnerd-api.vercel.app/api/artist/{artistId}/interview/session/{sessionId}/prepare' \
  --header 'Content-Type: application/json' \
  --data '{
  "action": "prepare"
}'

Send the request to see the live response here.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>.

Path Parameters

artistIdstringrequired
sessionIdstringrequired

Body

application/jsonrequired
actionstring · enumrequired

Values: "prepare", "consume"

Response

application/json

Preparation status for prepare, or the saved offer for consume.

oneOf · object 1
statusanyrequired
preparationobjectrequired
Properties for preparation
jobIdstring

Present when a preparation job exists.

format: uuid

statusstring · enumrequired

Values: "idle", "pending", "running", "ready", "failed", "stale"

errorCodestring · enum

Safe failure classification only; never raw provider errors or private job payloads.

Values: "preparation_failed", "model_output_invalid", "timeout_or_cancelled", "external_outcome_unknown"

readyCountinteger

Number of independently checked available questions. Zero while initial preparation or eligibility checking is pending.

minimum: 0 · maximum: 3

totalCountinteger

Questions targeted by this preparation bank; a new sitting targets three, an existing sitting only remaining slots.

minimum: 1 · maximum: 3

phasestring · enum

Preparing generates the initial bank; checking revalidates saved questions after an answer or changed instructions without generating replacements.

Values: "preparing", "checking"

oneOf · object 2
statusany
questionobject
Properties for question
idstring

format: uuid

questionKeystring
questionstring
answerstring | null
statestring · enum

Values: "offered", "answered", "skipped"

revisionstring

pattern: ^[a-f0-9]{64}$

sittinginteger
offeredAtstring

format: date-time

answerUpdatedAtstring

format: date-time

ordinalinteger | null
referencesarray<object>
Item properties for references
kindstring · enumrequired

Values: "original", "answer"

sourceIdstring

Required for original evidence: full vault/social source identity.

entryIdstring

Required for answer evidence: full answer identity.

revisionstringrequired

pattern: ^[a-f0-9]{64}$

startintegerrequired

UTF-16 offset.

minimum: 0

endintegerrequired

minimum: 1

quotestringrequired

minLength: 8 · maxLength: 1600

questionsarray<object>

All authoritative questions offered atomically at explicit Start; use these rows to advance locally while exact answer saves are pending.

maxItems: 3

Item properties for questions
idstring

format: uuid

questionKeystring
questionstring
answerstring | null
statestring · enum

Values: "offered", "answered", "skipped"

revisionstring

pattern: ^[a-f0-9]{64}$

sittinginteger
offeredAtstring

format: date-time

answerUpdatedAtstring

format: date-time

ordinalinteger | null
referencesarray<object>
Item properties for references
kindstring · enumrequired

Values: "original", "answer"

sourceIdstring

Required for original evidence: full vault/social source identity.

entryIdstring

Required for answer evidence: full answer identity.

revisionstringrequired

pattern: ^[a-f0-9]{64}$

startintegerrequired

UTF-16 offset.

minimum: 0

endintegerrequired

minimum: 1

quotestringrequired

minLength: 8 · maxLength: 1600