# Read question preparation

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

Read question preparation

## GET /api/artist/{artistId}/interview/session/{sessionId}/prepare

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/{artistId}/interview/session/{sessionId}/prepare": {
      "get": {
        "summary": "Read question preparation",
        "description": "Read-only status for the session’s next question. Does not generate, enqueue or write. Stale means the session, claim, next ordinal or mandatory memory no longer matches the prepared candidate. A consumed preparation returns idle without jobId. A ready candidate is not a saved offer. Actual current approved claimant only; administrator status alone is insufficient. Bearer authentication is verified on every request; bearer tokens are never stored in the job. Private/no-store. Approved claims may automatically queue private question preparation after source research. The artist still explicitly chooses Start before any question is offered. Existing jobs wait for readable approved originals or artist-owned social text; pending Lore alone is not usable evidence. Existing readable artist context can proceed without waiting for unrelated Latest or ongoing research jobs. Waiting runs no model or scrape. Automatic waiting stops after 24 hours, and the same job becomes eligible again when usable evidence appears. Exact claimant ownership is rechecked before preparing. Reading pages or GET status never queues this work.",
        "security": [
          {
            "PrivyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "artistId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current preparation status. A ready candidate has not been offered yet.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "status",
                    "preparation"
                  ],
                  "properties": {
                    "status": {
                      "const": "ok"
                    },
                    "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."
                        }
                      }
                    }
                  }
                },
                "example": {
                  "status": "ok",
                  "preparation": {
                    "status": "idle"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "code"
                  ],
                  "properties": {
                    "status": {
                      "const": "error"
                    },
                    "code": {
                      "enum": [
                        "invalid_input"
                      ]
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Sign in required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "code"
                  ],
                  "properties": {
                    "status": {
                      "const": "error"
                    },
                    "code": {
                      "enum": [
                        "unauthenticated"
                      ]
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Actual approved claimant required.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "code"
                  ],
                  "properties": {
                    "status": {
                      "const": "error"
                    },
                    "code": {
                      "enum": [
                        "forbidden"
                      ]
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Artist or session unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "code"
                  ],
                  "properties": {
                    "status": {
                      "const": "error"
                    },
                    "code": {
                      "enum": [
                        "not_found"
                      ]
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Candidate is not ready or session, ordinal, memory or evidence changed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "code"
                  ],
                  "properties": {
                    "status": {
                      "const": "error"
                    },
                    "code": {
                      "enum": [
                        "preparation_stale",
                        "preparation_not_ready"
                      ]
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Required memory or persistence unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "code"
                  ],
                  "properties": {
                    "status": {
                      "const": "error"
                    },
                    "code": {
                      "enum": [
                        "memory_unavailable"
                      ]
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PrivyAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```
