music nerd

Interview memory and sessionsRun an interview action

Interview memory and sessions

Run an interview action

Performs one interview action. start opens a sitting and queues preparation; prepare queues it for an open sitting; continue consumes a ready question (or returns the one already offered); answer saves exact words and returns the state with savedQuestion; finish closes the sitting; boundary and retract save or retract a topic instruction and return { status: "ok" }; memory returns the sitting's assembled mandatory memory; boundaries lists active instructions; source reads an original source window pinned to its revision. The sitting for memory and boundaries is the active one, else the next.

POST/api/artist/{id}/interview
POST/api/artist/aab92f80-f9e1-4299-aa33-7dd85c8de5d3/interview

Performs one interview action. start opens a sitting and queues preparation; prepare queues it for an open sitting; continue consumes a ready question (or returns the one already offered); answer saves exact words and returns the state with savedQuestion; finish closes the sitting; boundary and retract save or retract a topic instruction and return { status: "ok" }; memory returns the sitting's assembled mandatory memory; boundaries lists active instructions; source reads an original source window pinned to its revision. The sitting for memory and boundaries is the active one, else the next.

Authorization

Authorizationstringrequired

Kept in this tab only.

Path

idstringrequired

The artist's ID (a UUID).

Body
cURL
curl --request POST \
  --url 'https://musicnerd-api.vercel.app/api/artist/aab92f80-f9e1-4299-aa33-7dd85c8de5d3/interview' \
  --header 'Content-Type: application/json' \
  --data '{
  "action": "start",
  "requestId": "0f5b6a7c-8d9e-4f01-a234-56789abcdef0"
}'

Send the request to see the live response here.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>.

Path Parameters

idstringrequired

The artist's ID (a UUID).

Body

application/jsonrequired
oneOf · object 1
actionanyrequired
requestIdstringrequired

Idempotency key for the sitting.

format: uuid

oneOf · object 2
actionanyrequired
sessionIdstringrequired

format: uuid

oneOf · object 3
actionanyrequired
sessionIdstringrequired

format: uuid

oneOf · object 4
actionanyrequired
answerIdstringrequired

format: uuid

expectedRevisionstringrequired

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

answerstring | nullrequired

The artist's exact words; null skips the question.

minLength: 1 · maxLength: 8000

oneOf · object 5
actionanyrequired
sessionIdstringrequired

format: uuid

oneOf · object 6
actionanyrequired
requestIdstringrequired

format: uuid

questionKeystringrequired

minLength: 1 · maxLength: 500

wordingstringrequired

minLength: 1 · maxLength: 4000

scopestring · enumrequired

Values: "sitting", "until_retracted"

oneOf · object 7
actionanyrequired
boundaryIdstringrequired

format: uuid

revisionstringrequired

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

oneOf · object 8
actionanyrequired
oneOf · object 9
actionanyrequired
cursorstring

minLength: 1 · maxLength: 4096

oneOf · object 10
actionanyrequired
sourceIdstringrequired

minLength: 1 · maxLength: 100

revisionstringrequired

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

startintegerrequired

The window starts 1000 characters before this and reads 8000.

minimum: 0

Response

application/json

By action: the interview state (start, prepare, continue, answer, finish), { status: "ok" } (boundary, retract), assembled memory (memory), a boundary page (boundaries) or a source window (source). Cache-Control: private, no-store.

oneOf · InterviewState 1
statusanyrequired
sessionobject | nullrequired
Properties for session
idstring

format: uuid

sittinginteger
statestring · enum

Values: "active", "finished"

createdAtstring

format: date-time

closedAtstring | null

format: date-time

questionsarray<object>

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

interviewInvalidatedboolean

True after changed instructions invalidate the fixed offered bank. Saved answers remain intact; finish explicitly before starting a new sitting.

needsPreparedBankResumeboolean

Read-only hint that an active legacy sitting has an offered question and remaining checked bank items. On explicit Resume, call consume to revalidate current ownership, mandatory memory, and evidence and atomically offer eligible remaining questions. GET never offers questions. False for fully offered banks.

legacyOffersarray<object>required

maxItems: 3

Item properties for legacyOffers
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

preparationobject

Present after start and prepare (the queued preparation), and on a restore of an active sitting with no offered question (its current preparation).

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"

savedQuestionobject

Present after answer: the question as saved.

Properties for savedQuestion
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

oneOf · InterviewOk 2
statusstring · enumrequired

Values: "ok"

oneOf · AssembledMemory 3
statusanyrequired
snapshotIdstringrequired

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

sittingintegerrequired
latestAnswerone ofrequired
Properties for latestAnswer
oneOf · null 1

null

oneOf · object 2
entryIdstringrequired
revisionstringrequired

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

entriesarray<object>required

Every mandatory entry, each field complete; pages are assembled before returning.

maxItems: 5000

Item properties for entries
entryIdstringrequired
revisionstringrequired

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

kindstring · enumrequired

Values: "latest_answer", "correction", "boundary"

fieldsarray<object>required
Item properties for fields
namestring · enumrequired

Values: "question", "answer", "claim", "correction", "wording"

textstring | nullrequired
startintegerrequired

minimum: 0

endintegerrequired

minimum: 0

totalCharsintegerrequired

minimum: 0

completebooleanrequired
metadataobjectrequired
constraintsCompleteanyrequired
returnedCharsintegerrequired

minimum: 0 · maximum: 32000

oneOf · BoundaryPage 4
statusanyrequired
sittingintegerrequired

minimum: 1

boundariesarray<Boundary>required

maxItems: 5

Item properties for boundaries
idstringrequired

format: uuid

revisionstringrequired

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

wordingstringrequired

maxLength: 4000

scopestring · enumrequired

Values: "sitting", "until_retracted"

sittingintegerrequired

minimum: 1

questionKeystringrequired
createdAtstringrequired
retractedAtstring | nullrequired
questionstringrequired

Exact offered question captured when this instruction was saved.

nextCursorstring | nullrequired

Continuation for the same active boundary list; null after the final page.

oneOf · SourceRead 5

Requested window from the pinned revision. nextStart continues the same revision; null means exhausted. Legacy empty/unreadable extraction is a successful empty window with unknown/failed extraction state where known, not proof of complete extraction.

statusstring · enumrequired

Values: "ok"

passageobjectrequired

Exact original-text window. Offsets are half-open UTF-16 code units into the requested evidence revision; surrogate pairs are not split. Page/audio locations are null without a verified extraction map. end-start equals text.length in JavaScript.

Properties for passage
sourceobjectrequired
Properties for source
sourceIdstringrequired

pattern: ^(vault:[0-9a-f-]{36}|social:[0-9a-f-]{36}:(caption|transcript))$

kindstring · enumrequired

Values: "vault", "social_caption", "reel_transcript"

titlestring | nullrequired

maxLength: 300

titleTruncatedbooleanrequired
urlstring | nullrequired

format: uri

revisionstringrequired

Includes empty stored evidence, so unreadable/unknown sources remain identifiable without claiming readable content.

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

publishedAtany ofrequired

Preserve available precision; do not invent a time for a date-only publication.

Properties for publishedAt
anyOf · string 1

string

anyOf · string 2

string

anyOf · null 3

null

ingestedAtstring | nullrequired

format: date-time

provenanceobjectrequired
Properties for provenance
originstring · enumrequired

Values: "vault_link", "vault_upload", "social_caption", "provider_transcript"

providerstring | nullrequired
methodstring | nullrequired
speakerstring · enumrequired

Values: "not_applicable", "unverified", "verified"

publisherstring | nullrequired

Stored social account username, not a verified speaker identity; null for unestablished publisher.

speakerNamenullrequired
relationshipstringrequired
extractionobjectrequired
Properties for extraction
readinessstring · enumrequired

Values: "ready", "queued", "running", "failed", "unknown"

storedCharsintegerrequired

minimum: 0

truncatedboolean | nullrequired
limitationsarray<string>required
Item properties for limitations

string

descriptionstring | nullrequired

Publisher metadata; not original body text and never sufficient support for a premise.

maxLength: 600

descriptionTruncatedbooleanrequired
uploadedAtstring | nullrequired

format: date-time

eventDatenullrequired

Unknown in the current schema; never inferred from upload/publication time.

originalSourceUrlnullrequired

No verified original/repost relationship is available in legacy storage.

revisionstringrequired

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

startintegerrequired

minimum: 0

endintegerrequired

minimum: 0

textstringrequired
pageinteger | nullrequired

minimum: 1

startSecondsnumber | nullrequired

minimum: 0

endSecondsnumber | nullrequired

minimum: 0

totalCharsintegerrequired

minimum: 0

nextStartinteger | nullrequired

minimum: 0

returnedCharsintegerrequired

minimum: 0 · maximum: 20000

truncatedbooleanrequired
versionobject

Required when includeVersion=true; omitted for legacy current-only reads.

Properties for version
statestring · enumrequired

Values: "current", "historical"

currentRevisionstringrequired

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

capturedAtstring | nullrequired

Retention time, not publication/event time; null for a current read.

format: date-time