# Read the About

Source: https://docs.musicnerd.net/api-reference/artist-bio/read-about

Read the About

## GET /api/artistBio/{id}

Full OpenAPI specification: https://docs.musicnerd.net/spec/artist-bio.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 bio",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://musicnerd-api.vercel.app",
      "description": "Production"
    },
    {
      "url": "https://musicnerd-api-staging.vercel.app",
      "description": "Staging (staging database)"
    }
  ],
  "paths": {
    "/api/artistBio/{id}": {
      "get": {
        "summary": "Read the About",
        "operationId": "getArtistBio",
        "security": [],
        "description": "The artist's About as the profile shows it: the saved bio for a claimed artist, otherwise the directory's prepared About when it is still current, otherwise the claim prompt. With `regenerate=true` the caller must be the artist's claimant or an admin; the About is rewritten from the artist's Lore and saved, with the previous text kept in the bio history.",
        "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"
          },
          {
            "name": "regenerate",
            "in": "query",
            "required": false,
            "description": "`true` rewrites the About from the Lore document instead of reading it. Requires the claimant's or an admin's token.",
            "schema": {
              "type": "string",
              "enum": [
                "true"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The About. A read carries `Cache-Control: private, no-store`. A regeneration returns the new bio, or the unchanged bio with `pinned: true` when a version is pinned.",
            "headers": {
              "Cache-Control": {
                "description": "`private, no-store` on a read.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ArtistAbout"
                    },
                    {
                      "$ref": "#/components/schemas/RegeneratedBio"
                    }
                  ]
                },
                "examples": {
                  "claimed": {
                    "summary": "A claimed artist's saved About",
                    "value": {
                      "status": "ok",
                      "bio": "Bio Ritmo is a 10-piece salsa band from Richmond, Virginia.",
                      "publicAbout": null
                    }
                  },
                  "directory": {
                    "summary": "An unclaimed artist with a current directory About",
                    "value": {
                      "status": "ok",
                      "bio": "Bio Ritmo is a 10-piece salsa band from Richmond, Virginia.",
                      "publicAbout": {
                        "bio": "Bio Ritmo is a 10-piece salsa band from Richmond, Virginia.",
                        "kind": "researched",
                        "sources": [
                          {
                            "id": "7f1c6f0e-2b1a-4b7d-9a0a-1c2d3e4f5a6b",
                            "url": "https://www.bioritmo.com/about",
                            "label": "About · bioritmo.com"
                          }
                        ]
                      }
                    }
                  },
                  "regenerated": {
                    "summary": "`regenerate=true` wrote a new About",
                    "value": {
                      "status": "ok",
                      "bio": "Bio Ritmo is a 10-piece salsa band from Richmond, Virginia, playing since 1991."
                    }
                  },
                  "pinned": {
                    "summary": "`regenerate=true` on a pinned bio",
                    "value": {
                      "status": "ok",
                      "bio": "Bio Ritmo is a 10-piece salsa band from Richmond, Virginia.",
                      "pinned": true,
                      "message": "Bio is pinned. Unpin it before regenerating."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`id` isn't a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "artistId must be a UUID"
                }
              }
            }
          },
          "401": {
            "description": "`regenerate=true` without a token, or with an invalid or expired one.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Not signed in"
                }
              }
            }
          },
          "403": {
            "description": "`regenerate=true` by a user who is neither the artist's claimant nor an admin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Not your artist"
                }
              }
            }
          },
          "404": {
            "description": "No artist with that ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Artist not found"
                }
              }
            }
          },
          "408": {
            "description": "`regenerate=true`: the model did not answer in time. The existing About is kept.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "About generation timed out. Please try again. Your existing About has been kept."
                }
              }
            }
          },
          "409": {
            "description": "`regenerate=true`: there is no Lore document yet (`code: \"LORE_REQUIRED\"`), or the bio changed, was pinned or the artist's claim changed while the About was being written.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BioError"
                },
                "examples": {
                  "loreRequired": {
                    "summary": "No Lore document",
                    "value": {
                      "status": "error",
                      "code": "LORE_REQUIRED",
                      "error": "Build your Lore document before generating About. Your existing About has been kept."
                    }
                  },
                  "conflict": {
                    "summary": "The bio changed during generation",
                    "value": {
                      "status": "error",
                      "error": "Your bio changed or was pinned while generation was running. Your current bio is safe; review it before trying again."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "The read or the generation failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Unable to read About. Please try again."
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ArtistAbout": {
        "type": "object",
        "required": [
          "status",
          "bio",
          "publicAbout"
        ],
        "additionalProperties": false,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "bio": {
            "type": "string",
            "description": "The saved bio for a claimed artist; otherwise the directory About's text, or the claim prompt when there is nothing verified to show."
          },
          "publicAbout": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PublicArtistAbout"
              },
              {
                "type": "null"
              }
            ],
            "description": "The directory About for an unclaimed artist, or `null`."
          }
        }
      },
      "RegeneratedBio": {
        "type": "object",
        "required": [
          "status",
          "bio"
        ],
        "additionalProperties": false,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "bio": {
            "type": [
              "string",
              "null"
            ],
            "description": "The About now saved."
          },
          "pinned": {
            "type": "boolean",
            "description": "`true` when a pinned version blocked the regeneration; `bio` is the unchanged About."
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "BioError": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "LORE_REQUIRED"
            ],
            "description": "Present when the About cannot be generated because there is no Lore document."
          }
        }
      },
      "PublicArtistAbout": {
        "type": "object",
        "description": "The directory's prepared About for an unclaimed artist, with the sources it cites. Only returned while the artist's links and sources still match what it was written from.",
        "required": [
          "bio",
          "kind",
          "sources"
        ],
        "properties": {
          "bio": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "official",
              "researched"
            ],
            "description": "`official` when it rests on the artist's own page or account; `researched` otherwise."
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "url",
                "label"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}
```
