# Chat about an artist

Source: https://docs.musicnerd.net/api-reference/chat/artist-chat

Chat about an artist

## POST /api/artist/{id}/chat

Full OpenAPI specification: https://docs.musicnerd.net/spec/chat.json

## Authentication

This operation's specification permits a request without authentication.

[Authentication guide](https://docs.musicnerd.net/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Music Nerd API: artist chat",
    "version": "0.1.0",
    "description": "A listener's conversation about one artist, answered from the artist's approved sources and the web and streamed as it is written."
  },
  "servers": [
    {
      "url": "https://musicnerd-api.vercel.app"
    }
  ],
  "paths": {
    "/api/artist/{id}/chat": {
      "post": {
        "summary": "Chat about an artist",
        "operationId": "postArtistChat",
        "security": [
          {
            "privyBearer": []
          },
          {}
        ],
        "description": "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.\n\n**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.\n\n**Passage mode stream parts.** Each tool part carries an `output` once its state is `output-available`. Rely on these fields.\n\n- `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.\n- `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`.\n- `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.\n- `tool-webSearch`: `results[]` (`n`, `title`, `url`, `snippet`), or `{ \"error\": \"Web search limit reached for this answer\" }` after two searches.\n- `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`.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\nTo 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.\n\n**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.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The artist's ID (a UUID).",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "aab92f80-f9e1-4299-aa33-7dd85c8de5d3"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              },
              "example": {
                "messages": [
                  {
                    "id": "msg_1",
                    "role": "user",
                    "parts": [
                      {
                        "type": "text",
                        "text": "Where did Bio Ritmo record their latest album?"
                      }
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The 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.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "example": "data: {\"type\":\"start\",\"messageId\":\"frAjrewNeeOFTMom\"}\n\ndata: {\"type\":\"start-step\"}\n\ndata: {\"type\":\"tool-input-start\",\"toolCallId\":\"call_1\",\"toolName\":\"searchSources\"}\n\ndata: {\"type\":\"tool-input-delta\",\"toolCallId\":\"call_1\",\"inputTextDelta\":\"{\\\"query\\\": \\\"Bio\"}\n\ndata: {\"type\":\"tool-input-delta\",\"toolCallId\":\"call_1\",\"inputTextDelta\":\" Ritmo founders\\\"}\"}\n\ndata: {\"type\":\"tool-input-available\",\"toolCallId\":\"call_1\",\"toolName\":\"searchSources\",\"input\":{\"query\":\"Bio Ritmo founders\"}}\n\ndata: {\"type\":\"tool-output-available\",\"toolCallId\":\"call_1\",\"output\":{\"sources\":[{\"sourceId\":\"vault:8c16811b-a6fb-484f-be99-70d56880dfc3\",\"title\":\"richmondfolkfestival.org\",\"url\":\"https://www.richmondfolkfestival.org/2023-performers/2023/6/1/bio-ritmo\",\"snippet\":\"Bio Ritmo has been a fixture of the Richmond music scene since 1991…\"},{\"sourceId\":\"vault:635a4493-d845-43da-bfdf-b30bf7af1298\",\"title\":\"richmondmagazine.com\",\"url\":\"https://richmondmagazine.com/news/features/bio-ritmo\",\"snippet\":\"The band started as a college project at VCU…\"}]}}\n\ndata: {\"type\":\"finish-step\"}\n\ndata: {\"type\":\"start-step\"}\n\ndata: {\"type\":\"tool-input-start\",\"toolCallId\":\"call_2\",\"toolName\":\"readSource\"}\n\ndata: {\"type\":\"tool-input-delta\",\"toolCallId\":\"call_2\",\"inputTextDelta\":\"{\\\"sourceId\\\": \\\"vault:8c16811b-a6fb-484f-be99-70d56880dfc3\\\"}\"}\n\ndata: {\"type\":\"tool-input-available\",\"toolCallId\":\"call_2\",\"toolName\":\"readSource\",\"input\":{\"sourceId\":\"vault:8c16811b-a6fb-484f-be99-70d56880dfc3\"}}\n\ndata: {\"type\":\"source-url\",\"sourceId\":\"1\",\"url\":\"https://www.richmondfolkfestival.org/2023-performers/2023/6/1/bio-ritmo\",\"title\":\"richmondfolkfestival.org\"}\n\ndata: {\"type\":\"tool-output-available\",\"toolCallId\":\"call_2\",\"output\":{\"n\":1,\"title\":\"richmondfolkfestival.org\",\"url\":\"https://www.richmondfolkfestival.org/2023-performers/2023/6/1/bio-ritmo\",\"text\":\"Bio Ritmo has been a fixture of the Richmond music scene since 1991…\"}}\n\ndata: {\"type\":\"finish-step\"}\n\ndata: {\"type\":\"start-step\"}\n\ndata: {\"type\":\"text-start\",\"id\":\"0\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"0\",\"delta\":\"Bio Ritmo\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"0\",\"delta\":\" started in Richmond, Virginia, in 1991. [1]\"}\n\ndata: {\"type\":\"text-end\",\"id\":\"0\"}\n\ndata: {\"type\":\"finish-step\"}\n\ndata: {\"type\":\"finish\",\"finishReason\":\"stop\"}\n\ndata: [DONE]\n\n"
              }
            }
          },
          "400": {
            "description": "The body is invalid: no messages, the last message isn't a `user` message with text, the question is over 500 characters, or a message has more than 512 parts as sent or more than 64 readable parts (`text` and `tool-*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatError"
                },
                "example": {
                  "status": "error",
                  "error": "Invalid chat request"
                }
              }
            }
          },
          "404": {
            "description": "No artist with that ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatError"
                },
                "example": {
                  "status": "error",
                  "error": "Artist not found"
                }
              }
            }
          },
          "429": {
            "description": "The question allowance is spent. `code` names it: `visitor_question_quota` (30 questions per visitor per hour) or `question_planning_quota` (200 across the site per rolling day).",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the quota window resets, only when the response carries `retryAfterSeconds`.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "X-MusicNerd-Quota": {
                "description": "`true` on a quota response, so a client can tell it from a transient 429.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatError"
                },
                "examples": {
                  "visitorQuota": {
                    "summary": "The visitor's hourly allowance",
                    "value": {
                      "status": "error",
                      "code": "visitor_question_quota",
                      "error": "You've reached your question limit for this hour. Try again in 42 minutes.",
                      "retryAfterSeconds": 2520,
                      "resetAt": "2026-10-21T15:42:00.000Z"
                    }
                  },
                  "siteQuota": {
                    "summary": "The site's daily allowance",
                    "value": {
                      "status": "error",
                      "code": "question_planning_quota",
                      "error": "Music Nerd has reached its daily chat allowance. Try again in 3 minutes.",
                      "retryAfterSeconds": 180,
                      "resetAt": "2026-10-21T15:03:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ChatRequest": {
        "type": "object",
        "required": [
          "messages"
        ],
        "properties": {
          "messages": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/UIMessage"
            },
            "description": "The conversation so far, oldest first. The last message is the question; at most the last 12 are read."
          }
        }
      },
      "ChatError": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "const": "error"
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "visitor_question_quota",
              "question_planning_quota"
            ]
          },
          "retryAfterSeconds": {
            "type": "integer",
            "minimum": 1,
            "maximum": 86400
          },
          "resetAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UIMessage": {
        "type": "object",
        "required": [
          "id",
          "role",
          "parts"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant"
            ]
          },
          "parts": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "type"
              ],
              "properties": {
                "type": {
                  "type": "string"
                }
              }
            },
            "description": "Message 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."
          }
        }
      }
    },
    "securitySchemes": {
      "privyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Access token",
        "description": "Optional. The signed-in user's access token, so the allowance counts per account. Copy it at [musicnerd.net/access](https://musicnerd.net/access) after signing in."
      }
    }
  }
}
```
