Artist chat
Chat about an artist
Answers an artist question using approved sources and the web, streaming source citations and the reply as server-sent events. Authentication is optional; signed-in requests use the account’s hourly allowance instead of the IP allowance. Approved public PDFs require a current approved artist claim and are read from the original file under current permissions, with at most two read attempts per turn, 4 MiB and 50 pages per file. PDF discovery runs for ordinary questions too, ranking approved PDFs by title and stored extracted text, not only when the question names a document. An explicitly named, uniquely matching PDF can be read in one operation; ambiguous names use discovery, and answers are instructed to cite physical pages, retain qualifications and acknowledge unavailable evidence without promising accuracy or response time. Planning text the model writes before calling a tool is not streamed; only answer text reaches the client.
Two retrieval modes. The server answers either from whole sources (the default) or from passages of the artist's saved documents. Which one is active is a server setting, not a request parameter, and it can change between requests, so a client must handle the stream parts of both. In whole-source mode the model uses tool-searchSources, tool-readSource, tool-webSearch and the PDF tools, and citations are [n] or [n, p.N] for a PDF page. In passage mode the model uses tool-searchPassages, tool-readUnits and tool-listDocuments on the artist's documents, plus tool-webSearch; tool-searchSources and tool-readSource then serve only latest-release questions and published answers, and there are no PDF tools.
Passage mode stream parts. Each tool part carries an output once its state is output-available. Rely on these fields.
- tool-searchPassages, input { query }: results[] (n, locator, title, passage), weak, truncated, expanded and documents[]. A passage is a whole page or section, or for a very long page the part that best matches the query. weak: true is an early sign that nothing matched well, not a verdict. truncated: true means the answer's read budget ran out and later hits were dropped without being numbered. expanded is the number of a short document that had several hits and was returned whole, or null. Each entry of documents[] is a document this call numbered: n, sourceKind (vault, social or evidence), sourceId, revision, title, url (a string or null), units (how many pages or sections the document has now) and shown (how many of them this call returned). At most four searches run per answer; a fifth returns { "error": "Search limit reached for this answer", "results": [], "documents": [] } and numbers nothing.
- tool-readUnits, input { n, locators? }: n, title, units[] (locator, text), truncated, missing (locators the document does not have) and documents[] holding the one document read (n, sourceKind, sourceId, revision, title, url; no units or shown). Reads share the answer's read budget; truncated: true means some pages were not returned. Without locators it reads the whole document. Errors are { "error": "Unknown document number" }, { "error": "Source changed or is no longer public" } and { "error": "No such locator: …" }, and carry no documents.
- tool-listDocuments, no input: documents[] of at most 60 entries (vault files first, then research, then social posts), each with n (the document's number, or null when this conversation has not numbered it), title, kind, url, units and indexing (true when it is not searchable yet). Listing numbers nothing and sends no source-url part.
- tool-webSearch: results[] (n, title, url, snippet), or { "error": "Web search limit reached for this answer" } after two searches.
- tool-searchSources and tool-readSource, for latest-release questions: as in the example below. readSource returns n, title, url, text and dates, or { "error": … } for an unknown sourceId.
source-url parts. In passage mode one source-url part is sent for each numbered document, with sourceId the document's number as a string. When a conversation continues, the server sends a source-url part at the start of the answer for each document numbered earlier and still in the history, so a client can rebuild its source list from the latest stream alone. The url is the document's public URL; a document with none gets musicnerd://<kind>/<id>, which is an identifier and not a page, so a client must not render it as a link. Numbers are stable for the whole conversation: a number never means two sources, and gaps are possible.
Citations in answer text. Cite with the document number and, for documents, a locator: [n, p.N] for a PDF page, [n, §Heading] for a section, [n, ¶N] for a paragraph, and [n] for a web or latest-source result. Several numbers may share brackets ([2, 5]). In the locator forms only n is a citation number; everything after the first comma is the locator, and a heading may itself contain commas ([1, §Live, 1999] cites document 1). A bracketed date such as [2026-05-13] is not a citation.
Locators. A locator is p.N (a page), §Heading (a section) or ¶N (a paragraph), written with no space after the marker. They are the locator values in tool outputs.
Follow-up requests. Send { messages }: the conversation so far, ending with the new question. The server keeps the last 12 messages. It reads only text and tool-* parts and discards every other part (source-url, step-start, reasoning and the rest) before counting, so a client can resend a stored message as it is. A message may hold at most 512 parts as sent and at most 64 once the unread ones are discarded. The last message must be a user message whose text is 1 to 500 characters after trimming. Anything outside these limits is a 400.
To keep document numbers stable, the server reads from an assistant message's completed tool-searchPassages and tool-readUnits parts only output.documents[], and from each entry only n (1 to 256), sourceKind, sourceId (a UUID), revision, title and url. A client may therefore send those outputs reduced to those fields, and units and shown may be left out. At most the first 48 documents of one message are kept, each document once. If an assistant message's documents cannot be identified, that message is left out of the conversation instead of failing the request. Tool parts on a user message are ignored.
Withdrawn or edited documents. An earlier answer stays in the history the model sees only while every document it numbered is still public at the revision it was numbered at. If one is withdrawn or edited, that answer and every later answer leave the history, because a later answer can cite an earlier number from memory. An answer whose text cites a locator form for a number no earlier answer numbered also leaves it. An answer that sends text only, with [n] citations, stays as long as the documents of the answers before it are current. The same holds for whole-source mode: an answer that read a PDF is kept only while that PDF is unchanged.
Path Parameters
idstringrequiredThe artist's ID (a UUID).
Body
application/jsonrequiredmessagesarray<UIMessage>requiredThe conversation so far, oldest first. The last message is the question; at most the last 12 are read.
minItems: 1
Item properties for messages
idstringrequiredrolestring · enumrequiredValues: "user", "assistant"
partsarray<object>requiredMessage parts. Only text parts { "type": "text", "text": "…" } and tool-* parts are read; every other part is discarded first. At most 512 parts as sent and 64 after the discard. On an assistant message, the output.documents[] of completed tool-searchPassages and tool-readUnits parts (n, sourceKind, sourceId, revision, title, url) let the server keep document numbers stable and check the documents are still current. Earlier assistant turns containing PDF reads are not reused as evidence unless the document is unchanged.
Item properties for parts
typestringrequiredResponse
text/event-streamThe reply as server-sent events, one JSON chunk per data: line, ending with data: [DONE]. source-url chunks are the cited sources (sourceId "1", "2", …, matching the [n] markers), text-delta chunks carry the answer, and tool-* chunks report progress. In passage mode the tool chunks are searchPassages, readUnits and listDocuments as well, and source-url chunks for documents numbered earlier in the conversation arrive first; see the endpoint description.
string