# Interview history

Source: https://musicnerd-docs.vercel.app/api-reference/knowledge/history

Read answers and corrections

## GET /api/artist/{id}/knowledge/history

Full OpenAPI specification: https://musicnerd-docs.vercel.app/spec/knowledge.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://musicnerd-docs.vercel.app/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Music Nerd shared artist knowledge — draft contract",
    "version": "1.0.0",
    "description": "Shared stored-evidence reads for approved claimants and administrators. Implementation preview contract; not released. No read initiates collection. Legacy extraction coverage is explicit; durable boundary storage and historical source versions remain unavailable."
  },
  "servers": [
    {
      "url": "https://musicnerd-api.vercel.app",
      "description": "Current API project; proposed routes are NOT available yet."
    }
  ],
  "paths": {
    "/api/artist/{id}/knowledge/history": {
      "get": {
        "operationId": "getInterviewHistory",
        "summary": "Read answers and corrections",
        "description": "Artist-scoped exact answer/correction field slices, corrections first, then offer order and ID. Current correction traversal completeness is separate from unavailable durable boundaries. The client supplies the latest exact unsaved answer independently.",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Artist ID in this deployment environment. Authorize claimant/admin on each call.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum records; response character/byte budgets may require an earlier continuation.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque artist/filter-bound continuation. A changed ordered corpus returns 409.",
            "schema": {
              "type": "string",
              "maxLength": 4096
            }
          },
          {
            "name": "maxChars",
            "in": "query",
            "required": false,
            "description": "Text budget; a long entry returns explicit continuation.",
            "schema": {
              "type": "integer",
              "minimum": 1000,
              "maximum": 20000,
              "default": 12000
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Filter history; defaults to all. Answer-only traversal cannot claim current constraints are loaded.",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "answers",
                "corrections"
              ]
            }
          },
          {
            "name": "sitting",
            "in": "query",
            "required": false,
            "description": "Restrict answers to this sitting; current corrections remain included unless kind=answers.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded stored evidence; Cache-Control: private, no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/History"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not the approved claimant or an admin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Source unavailable after artist authorization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Evidence revision or ordered corpus changed; restart from current metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "The stored corpus or one response exceeds the supported bounds; no partial successful corpus is returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Storage unavailable; never represented as an empty successful corpus.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "History": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HistoryEntry"
            },
            "maxItems": 50
          },
          "budget": {
            "$ref": "#/components/schemas/Budget"
          },
          "constraintsComplete": {
            "type": "boolean",
            "const": false,
            "description": "False while persistent boundaries are unavailable. The client must not assume readiness from empty corrections."
          },
          "memory": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "boundaryState",
              "latestAnswer"
            ],
            "properties": {
              "boundaryState": {
                "type": "string",
                "const": "not_implemented"
              },
              "latestAnswer": {
                "anyOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "entryId",
                      "revision"
                    ],
                    "properties": {
                      "entryId": {
                        "type": "string"
                      },
                      "revision": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{64}$"
                      }
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "correctionsComplete": {
            "type": "boolean",
            "description": "All current corrections traversed for this filter; does not include unavailable boundary records."
          }
        },
        "required": [
          "status",
          "entries",
          "budget",
          "constraintsComplete",
          "memory",
          "correctionsComplete"
        ],
        "description": "Verbatim history with bounded field continuations. source=offered is pending, other null-answer rows are skipped. latestAnswer identifies the newest saved non-null answer independent of the requested history filter. Durable topic boundaries are not implemented; constraintsComplete stays false."
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "invalid_input",
              "unauthenticated",
              "forbidden",
              "not_found",
              "revision_changed",
              "corpus_changed",
              "throttled",
              "storage_unavailable",
              "corpus_too_large",
              "response_too_large"
            ]
          }
        },
        "required": [
          "status",
          "error",
          "code"
        ]
      },
      "HistoryEntry": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "entryId": {
            "type": "string"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "kind": {
            "type": "string",
            "enum": [
              "answer",
              "correction"
            ]
          },
          "questionKey": {
            "type": [
              "string",
              "null"
            ]
          },
          "answerState": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "answered",
                  "skipped",
                  "offered"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "sitting": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          },
          "offeredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "answerUpdatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "correctionKind": {
            "type": [
              "string",
              "null"
            ]
          },
          "fields": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "field",
                "text",
                "start",
                "end",
                "totalChars",
                "complete"
              ],
              "properties": {
                "field": {
                  "type": "string",
                  "enum": [
                    "question",
                    "answer",
                    "claim",
                    "correction"
                  ]
                },
                "text": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "start": {
                  "type": "integer",
                  "minimum": 0
                },
                "end": {
                  "type": "integer",
                  "minimum": 0
                },
                "totalChars": {
                  "type": "integer",
                  "minimum": 0
                },
                "complete": {
                  "type": "boolean"
                }
              }
            },
            "description": "Verbatim field slices. Normal answers include question and answer; corrections include claim and correction. Continuation may contain one field only. Null answer remains explicit. All field text counts toward the total character budget. The cursor resumes the same entry revision and unfinished field before the next entry."
          }
        },
        "required": [
          "entryId",
          "revision",
          "kind",
          "questionKey",
          "answerState",
          "sitting",
          "offeredAt",
          "answerUpdatedAt",
          "source",
          "correctionKind",
          "fields"
        ],
        "description": "Exact question/answer or claim/correction field slices with explicit continuation for long fields. Do not infer skipped versus offered status from null alone. Never summarize or silently truncate the artist’s text."
      },
      "Budget": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "returnedChars": {
            "type": "integer",
            "minimum": 0
          },
          "truncated": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "returnedChars",
          "truncated",
          "nextCursor"
        ]
      }
    },
    "securitySchemes": {
      "privyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Access token",
        "description": "Existing authenticated Music Nerd user, approved artist claimant or admin. Credentials remain outside model arguments."
      }
    }
  }
}
```