# Artist brief

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

Get artist orientation

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

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/brief": {
      "get": {
        "operationId": "getArtistBrief",
        "summary": "Get artist orientation",
        "description": "Use stored facts and a generated navigation summary to choose evidence to inspect; no generation, source fetch or job enqueue. Current history/constraints must be loaded separately.",
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded stored evidence; Cache-Control: private, no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Brief"
                }
              }
            }
          },
          "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": {
      "Brief": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "artistId": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "bio": {
            "type": [
              "string",
              "null"
            ]
          },
          "generatedLoreSummary": {
            "type": [
              "string",
              "null"
            ]
          },
          "summaryIsEvidence": {
            "type": "boolean",
            "const": false
          },
          "coverage": {
            "$ref": "#/components/schemas/Coverage"
          },
          "historyRequired": {
            "type": "boolean",
            "const": true
          },
          "returnedChars": {
            "type": "integer",
            "minimum": 0,
            "maximum": 6000
          },
          "truncated": {
            "type": "boolean"
          }
        },
        "required": [
          "status",
          "artistId",
          "name",
          "bio",
          "generatedLoreSummary",
          "summaryIsEvidence",
          "coverage",
          "historyRequired",
          "returnedChars",
          "truncated"
        ],
        "description": "Stored profile and bounded generated orientation only. No synthesis or refresh. Load history/corrections before drafting. A generated summary is never independent cited evidence."
      },
      "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"
        ]
      },
      "Coverage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "eligibleSources": {
            "type": "integer",
            "minimum": 0
          },
          "readableSources": {
            "type": "integer",
            "minimum": 0
          },
          "searchedSources": {
            "type": "integer",
            "minimum": 0
          },
          "complete": {
            "type": "boolean"
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "eligibleSources",
          "readableSources",
          "searchedSources",
          "complete",
          "limitations"
        ],
        "description": "Coverage of stored eligible records, not a claim that all external material or PDF pages were extracted. For non-search reads, searchedSources is zero. Legacy extraction limits must be explicit."
      }
    },
    "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."
      }
    }
  }
}
```