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.
Path Parameters
artistIdstringrequiredsessionIdstringrequiredBody
application/jsonrequiredactionstring · enumrequiredValues: "prepare", "consume"
Response
application/jsonPreparation status for prepare, or the saved offer for consume.
oneOf · object 1
statusanyrequiredpreparationobjectrequiredProperties for preparation
jobIdstringPresent when a preparation job exists.
format: uuid
statusstring · enumrequiredValues: "idle", "pending", "running", "ready", "failed", "stale"
errorCodestring · enumSafe failure classification only; never raw provider errors or private job payloads.
Values: "preparation_failed", "model_output_invalid", "timeout_or_cancelled", "external_outcome_unknown"
readyCountintegerNumber of independently checked available questions. Zero while initial preparation or eligibility checking is pending.
minimum: 0 · maximum: 3
totalCountintegerQuestions targeted by this preparation bank; a new sitting targets three, an existing sitting only remaining slots.
minimum: 1 · maximum: 3
phasestring · enumPreparing generates the initial bank; checking revalidates saved questions after an answer or changed instructions without generating replacements.
Values: "preparing", "checking"
oneOf · object 2
statusanyquestionobjectProperties for question
idstringformat: uuid
questionKeystringquestionstringanswerstring | nullstatestring · enumValues: "offered", "answered", "skipped"
revisionstringpattern: ^[a-f0-9]{64}$
sittingintegerofferedAtstringformat: date-time
answerUpdatedAtstringformat: date-time
ordinalinteger | nullreferencesarray<object>Item properties for references
kindstring · enumrequiredValues: "original", "answer"
sourceIdstringRequired for original evidence: full vault/social source identity.
entryIdstringRequired for answer evidence: full answer identity.
revisionstringrequiredpattern: ^[a-f0-9]{64}$
startintegerrequiredUTF-16 offset.
minimum: 0
endintegerrequiredminimum: 1
quotestringrequiredminLength: 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
idstringformat: uuid
questionKeystringquestionstringanswerstring | nullstatestring · enumValues: "offered", "answered", "skipped"
revisionstringpattern: ^[a-f0-9]{64}$
sittingintegerofferedAtstringformat: date-time
answerUpdatedAtstringformat: date-time
ordinalinteger | nullreferencesarray<object>Item properties for references
kindstring · enumrequiredValues: "original", "answer"
sourceIdstringRequired for original evidence: full vault/social source identity.
entryIdstringRequired for answer evidence: full answer identity.
revisionstringrequiredpattern: ^[a-f0-9]{64}$
startintegerrequiredUTF-16 offset.
minimum: 0
endintegerrequiredminimum: 1
quotestringrequiredminLength: 8 · maxLength: 1600