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.
Path Parameters
idstringrequiredThe artist's ID (a UUID).
Body
application/jsonrequiredoneOf · object 1
actionanyrequiredrequestIdstringrequiredIdempotency key for the sitting.
format: uuid
oneOf · object 2
actionanyrequiredsessionIdstringrequiredformat: uuid
oneOf · object 3
actionanyrequiredsessionIdstringrequiredformat: uuid
oneOf · object 4
actionanyrequiredanswerIdstringrequiredformat: uuid
expectedRevisionstringrequiredpattern: ^[a-f0-9]{64}$
answerstring | nullrequiredThe artist's exact words; null skips the question.
minLength: 1 · maxLength: 8000
oneOf · object 5
actionanyrequiredsessionIdstringrequiredformat: uuid
oneOf · object 6
actionanyrequiredrequestIdstringrequiredformat: uuid
questionKeystringrequiredminLength: 1 · maxLength: 500
wordingstringrequiredminLength: 1 · maxLength: 4000
scopestring · enumrequiredValues: "sitting", "until_retracted"
oneOf · object 7
actionanyrequiredboundaryIdstringrequiredformat: uuid
revisionstringrequiredpattern: ^[a-f0-9]{64}$
oneOf · object 8
actionanyrequiredoneOf · object 9
actionanyrequiredcursorstringminLength: 1 · maxLength: 4096
oneOf · object 10
actionanyrequiredsourceIdstringrequiredminLength: 1 · maxLength: 100
revisionstringrequiredpattern: ^[a-f0-9]{64}$
startintegerrequiredThe window starts 1000 characters before this and reads 8000.
minimum: 0
Response
application/jsonBy 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
statusanyrequiredsessionobject | nullrequiredProperties for session
idstringformat: uuid
sittingintegerstatestring · enumValues: "active", "finished"
createdAtstringformat: date-time
closedAtstring | nullformat: date-time
questionsarray<object>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
interviewInvalidatedbooleanTrue after changed instructions invalidate the fixed offered bank. Saved answers remain intact; finish explicitly before starting a new sitting.
needsPreparedBankResumebooleanRead-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>requiredmaxItems: 3
Item properties for legacyOffers
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
preparationobjectPresent 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
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"
savedQuestionobjectPresent after answer: the question as saved.
Properties for savedQuestion
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
oneOf · InterviewOk 2
statusstring · enumrequiredValues: "ok"
oneOf · AssembledMemory 3
statusanyrequiredsnapshotIdstringrequiredpattern: ^[a-f0-9]{64}$
sittingintegerrequiredlatestAnswerone ofrequiredProperties for latestAnswer
oneOf · null 1
null
oneOf · object 2
entryIdstringrequiredrevisionstringrequiredpattern: ^[a-f0-9]{64}$
entriesarray<object>requiredEvery mandatory entry, each field complete; pages are assembled before returning.
maxItems: 5000
Item properties for entries
entryIdstringrequiredrevisionstringrequiredpattern: ^[a-f0-9]{64}$
kindstring · enumrequiredValues: "latest_answer", "correction", "boundary"
fieldsarray<object>requiredItem properties for fields
namestring · enumrequiredValues: "question", "answer", "claim", "correction", "wording"
textstring | nullrequiredstartintegerrequiredminimum: 0
endintegerrequiredminimum: 0
totalCharsintegerrequiredminimum: 0
completebooleanrequiredmetadataobjectrequiredconstraintsCompleteanyrequiredreturnedCharsintegerrequiredminimum: 0 · maximum: 32000
oneOf · BoundaryPage 4
statusanyrequiredsittingintegerrequiredminimum: 1
boundariesarray<Boundary>requiredmaxItems: 5
Item properties for boundaries
idstringrequiredformat: uuid
revisionstringrequiredpattern: ^[a-f0-9]{64}$
wordingstringrequiredmaxLength: 4000
scopestring · enumrequiredValues: "sitting", "until_retracted"
sittingintegerrequiredminimum: 1
questionKeystringrequiredcreatedAtstringrequiredretractedAtstring | nullrequiredquestionstringrequiredExact offered question captured when this instruction was saved.
nextCursorstring | nullrequiredContinuation 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 · enumrequiredValues: "ok"
passageobjectrequiredExact 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
sourceobjectrequiredProperties for source
sourceIdstringrequiredpattern: ^(vault:[0-9a-f-]{36}|social:[0-9a-f-]{36}:(caption|transcript))$
kindstring · enumrequiredValues: "vault", "social_caption", "reel_transcript"
titlestring | nullrequiredmaxLength: 300
titleTruncatedbooleanrequiredurlstring | nullrequiredformat: uri
revisionstringrequiredIncludes empty stored evidence, so unreadable/unknown sources remain identifiable without claiming readable content.
pattern: ^[a-f0-9]{64}$
publishedAtany ofrequiredPreserve 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 | nullrequiredformat: date-time
provenanceobjectrequiredProperties for provenance
originstring · enumrequiredValues: "vault_link", "vault_upload", "social_caption", "provider_transcript"
providerstring | nullrequiredmethodstring | nullrequiredspeakerstring · enumrequiredValues: "not_applicable", "unverified", "verified"
publisherstring | nullrequiredStored social account username, not a verified speaker identity; null for unestablished publisher.
speakerNamenullrequiredrelationshipstringrequiredextractionobjectrequiredProperties for extraction
readinessstring · enumrequiredValues: "ready", "queued", "running", "failed", "unknown"
storedCharsintegerrequiredminimum: 0
truncatedboolean | nullrequiredlimitationsarray<string>requiredItem properties for limitations
string
descriptionstring | nullrequiredPublisher metadata; not original body text and never sufficient support for a premise.
maxLength: 600
descriptionTruncatedbooleanrequireduploadedAtstring | nullrequiredformat: date-time
eventDatenullrequiredUnknown in the current schema; never inferred from upload/publication time.
originalSourceUrlnullrequiredNo verified original/repost relationship is available in legacy storage.
revisionstringrequiredpattern: ^[a-f0-9]{64}$
startintegerrequiredminimum: 0
endintegerrequiredminimum: 0
textstringrequiredpageinteger | nullrequiredminimum: 1
startSecondsnumber | nullrequiredminimum: 0
endSecondsnumber | nullrequiredminimum: 0
totalCharsintegerrequiredminimum: 0
nextStartinteger | nullrequiredminimum: 0
returnedCharsintegerrequiredminimum: 0 · maximum: 20000
truncatedbooleanrequiredversionobjectRequired when includeVersion=true; omitted for legacy current-only reads.
Properties for version
statestring · enumrequiredValues: "current", "historical"
currentRevisionstringrequiredpattern: ^[a-f0-9]{64}$
capturedAtstring | nullrequiredRetention time, not publication/event time; null for a current read.
format: date-time