# Restore the interview

Source: https://docs.musicnerd.net/api-reference/interview/restore-interview

Restore the interview

## GET /api/artist/{id}/interview

Full OpenAPI specification: https://docs.musicnerd.net/spec/interview-sessions.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://docs.musicnerd.net/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Durable interview sessions",
    "version": "0.1.0",
    "description": "Draft fifth-slice contract; not released."
  },
  "servers": [
    {
      "url": "https://musicnerd-api.vercel.app"
    }
  ],
  "paths": {
    "/api/artist/{id}/interview": {
      "get": {
        "summary": "Restore the interview",
        "operationId": "restoreInterview",
        "security": [
          {
            "PrivyAuth": []
          }
        ],
        "description": "The saved interview state, and for an active sitting with nothing offered and no legacy offers, its current preparation. Nothing is generated, queued or written.",
        "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"
          }
        ],
        "responses": {
          "200": {
            "description": "The saved interview. `Cache-Control: private, no-store`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InterviewState"
                }
              }
            }
          },
          "400": {
            "description": "`Invalid artist.` when `id` isn't a UUID; `Unexpected interview query.` when the URL has a query string.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InterviewError"
                },
                "example": {
                  "status": "error",
                  "error": "Invalid artist."
                }
              }
            }
          },
          "401": {
            "description": "No `Authorization: Bearer` header, or the token is invalid or has no Music Nerd user.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InterviewError"
                },
                "example": {
                  "status": "error",
                  "error": "Sign in to continue the interview."
                }
              }
            }
          },
          "403": {
            "description": "The user is neither the artist's claimant nor an admin; preparation also needs the claimant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InterviewError"
                },
                "example": {
                  "status": "error",
                  "error": "This account cannot edit this artist."
                }
              }
            }
          },
          "404": {
            "description": "The artist, session, offered question, source or boundary is unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InterviewError"
                },
                "example": {
                  "status": "error",
                  "error": "I could not complete that interview step. Your saved interview is still available; reload and try again."
                }
              }
            }
          },
          "409": {
            "description": "The saved interview, answer revision, boundary revision or source revision changed, or the sitting already has three questions (`This session is complete. Finish when you’re ready.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InterviewError"
                },
                "example": {
                  "status": "error",
                  "error": "The interview changed. Reload the saved interview."
                }
              }
            }
          },
          "413": {
            "description": "A supported limit was exceeded (interview offers, boundaries, source size).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InterviewError"
                },
                "example": {
                  "status": "error",
                  "error": "I could not complete that interview step. Your saved interview is still available; reload and try again."
                }
              }
            }
          },
          "503": {
            "description": "Persistence is unavailable, or the saved context exceeds its budget (a distinct message asks the artist to review topic instructions).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InterviewError"
                },
                "example": {
                  "status": "error",
                  "error": "I could not complete that interview step. Your saved interview is still available; reload and try again."
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "InterviewState": {
        "type": "object",
        "properties": {
          "status": {
            "const": "ok"
          },
          "session": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "sitting": {
                "type": "integer"
              },
              "state": {
                "type": "string",
                "enum": [
                  "active",
                  "finished"
                ]
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "closedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "questions": {
                "type": "array",
                "maxItems": 3,
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "questionKey": {
                      "type": "string"
                    },
                    "question": {
                      "type": "string"
                    },
                    "answer": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "offered",
                        "answered",
                        "skipped"
                      ]
                    },
                    "revision": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    },
                    "sitting": {
                      "type": "integer"
                    },
                    "offeredAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "answerUpdatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "ordinal": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "references": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "kind",
                          "revision",
                          "start",
                          "end",
                          "quote"
                        ],
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": [
                              "original",
                              "answer"
                            ]
                          },
                          "sourceId": {
                            "type": "string",
                            "description": "Required for original evidence: full vault/social source identity."
                          },
                          "entryId": {
                            "type": "string",
                            "description": "Required for answer evidence: full answer identity."
                          },
                          "revision": {
                            "type": "string",
                            "pattern": "^[a-f0-9]{64}$"
                          },
                          "start": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "UTF-16 offset."
                          },
                          "end": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "quote": {
                            "type": "string",
                            "minLength": 8,
                            "maxLength": 1600
                          }
                        }
                      }
                    }
                  }
                }
              },
              "interviewInvalidated": {
                "type": "boolean",
                "description": "True after changed instructions invalidate the fixed offered bank. Saved answers remain intact; finish explicitly before starting a new sitting."
              },
              "needsPreparedBankResume": {
                "type": "boolean",
                "description": "Read-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."
              }
            }
          },
          "legacyOffers": {
            "type": "array",
            "maxItems": 3,
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "questionKey": {
                  "type": "string"
                },
                "question": {
                  "type": "string"
                },
                "answer": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "offered",
                    "answered",
                    "skipped"
                  ]
                },
                "revision": {
                  "type": "string",
                  "pattern": "^[a-f0-9]{64}$"
                },
                "sitting": {
                  "type": "integer"
                },
                "offeredAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "answerUpdatedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "ordinal": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "references": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "kind",
                      "revision",
                      "start",
                      "end",
                      "quote"
                    ],
                    "properties": {
                      "kind": {
                        "type": "string",
                        "enum": [
                          "original",
                          "answer"
                        ]
                      },
                      "sourceId": {
                        "type": "string",
                        "description": "Required for original evidence: full vault/social source identity."
                      },
                      "entryId": {
                        "type": "string",
                        "description": "Required for answer evidence: full answer identity."
                      },
                      "revision": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{64}$"
                      },
                      "start": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "UTF-16 offset."
                      },
                      "end": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "quote": {
                        "type": "string",
                        "minLength": 8,
                        "maxLength": 1600
                      }
                    }
                  }
                }
              }
            }
          },
          "preparation": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "status"
            ],
            "properties": {
              "jobId": {
                "type": "string",
                "format": "uuid",
                "description": "Present when a preparation job exists."
              },
              "status": {
                "type": "string",
                "enum": [
                  "idle",
                  "pending",
                  "running",
                  "ready",
                  "failed",
                  "stale"
                ]
              },
              "errorCode": {
                "type": "string",
                "enum": [
                  "preparation_failed",
                  "model_output_invalid",
                  "timeout_or_cancelled",
                  "external_outcome_unknown"
                ],
                "description": "Safe failure classification only; never raw provider errors or private job payloads."
              },
              "readyCount": {
                "type": "integer",
                "minimum": 0,
                "maximum": 3,
                "description": "Number of independently checked available questions. Zero while initial preparation or eligibility checking is pending."
              },
              "totalCount": {
                "type": "integer",
                "minimum": 1,
                "maximum": 3,
                "description": "Questions targeted by this preparation bank; a new sitting targets three, an existing sitting only remaining slots."
              },
              "phase": {
                "type": "string",
                "enum": [
                  "preparing",
                  "checking"
                ],
                "description": "Preparing generates the initial bank; checking revalidates saved questions after an answer or changed instructions without generating replacements."
              }
            },
            "description": "Present after `start` and `prepare` (the queued preparation), and on a restore of an active sitting with no offered question (its current preparation)."
          },
          "savedQuestion": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "questionKey": {
                "type": "string"
              },
              "question": {
                "type": "string"
              },
              "answer": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "state": {
                "type": "string",
                "enum": [
                  "offered",
                  "answered",
                  "skipped"
                ]
              },
              "revision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "sitting": {
                "type": "integer"
              },
              "offeredAt": {
                "type": "string",
                "format": "date-time"
              },
              "answerUpdatedAt": {
                "type": "string",
                "format": "date-time"
              },
              "ordinal": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "references": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "kind",
                    "revision",
                    "start",
                    "end",
                    "quote"
                  ],
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "original",
                        "answer"
                      ]
                    },
                    "sourceId": {
                      "type": "string",
                      "description": "Required for original evidence: full vault/social source identity."
                    },
                    "entryId": {
                      "type": "string",
                      "description": "Required for answer evidence: full answer identity."
                    },
                    "revision": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    },
                    "start": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "UTF-16 offset."
                    },
                    "end": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "quote": {
                      "type": "string",
                      "minLength": 8,
                      "maxLength": 1600
                    }
                  }
                }
              }
            },
            "description": "Present after `answer`: the question as saved."
          }
        },
        "required": [
          "status",
          "session",
          "legacyOffers"
        ]
      },
      "InterviewError": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "error": {
            "type": "string",
            "description": "A message to show the artist as is."
          }
        }
      }
    },
    "securitySchemes": {
      "PrivyAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```
