# Read an original source

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

Read an original passage

## GET /api/artist/{id}/knowledge/sources/{sourceId}

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/sources/{sourceId}": {
      "get": {
        "operationId": "readArtistSource",
        "summary": "Read an original passage",
        "description": "Released original-source retention: read the exact requested current or retained source revision. Current eligibility and claimant/admin access are rechecked in one read-only snapshot. Older retained text includes version.state=historical, currentRevision and capturedAt; no silent substitution. Captures begin when the migration is deployed and are deleted with the source. Unknown/pre-retention revisions return 409. No arbitrary URL fetch, model call or write. Set includeVersion=true to opt in. Without it, preserve the released current-only response shape and 409 behavior.",
        "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": "sourceId",
            "in": "path",
            "required": true,
            "description": "Namespaced source record; must belong to this artist.",
            "schema": {
              "type": "string",
              "pattern": "^(vault:[0-9a-f-]{36}|social:[0-9a-f-]{36}:(caption|transcript))$"
            }
          },
          {
            "name": "revision",
            "in": "query",
            "required": true,
            "description": "Revision returned by source listing or search.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "start",
            "in": "query",
            "required": false,
            "description": "UTF-16 offset; beyond source length is invalid.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "maxChars",
            "in": "query",
            "required": false,
            "description": "Maximum original-text window.",
            "schema": {
              "type": "integer",
              "minimum": 1000,
              "maximum": 20000,
              "default": 6000
            }
          },
          {
            "name": "includeVersion",
            "in": "query",
            "required": false,
            "description": "Opt into retained historical reads and version metadata. Default false preserves the released response shape and 409 on changed content. The updated SDK enables this automatically.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded stored evidence; Cache-Control: private, no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceRead"
                }
              }
            }
          },
          "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": "Requested revision was not retained; revision_changed. Reload current metadata explicitly; never silently substitute it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Response exceeds 128 KiB, or historical lookup exceeds 512 snapshots / 4 million serialized snapshot characters; revision_history_too_large for the latter.",
            "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": {
      "SourceRead": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "passage": {
            "$ref": "#/components/schemas/Passage"
          },
          "totalChars": {
            "type": "integer",
            "minimum": 0
          },
          "nextStart": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          },
          "returnedChars": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20000
          },
          "truncated": {
            "type": "boolean"
          },
          "version": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "state",
              "currentRevision",
              "capturedAt"
            ],
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "current",
                  "historical"
                ]
              },
              "currentRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "capturedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "Retention time, not publication/event time; null for a current read."
              }
            },
            "description": "Required when includeVersion=true; omitted for legacy current-only reads."
          }
        },
        "required": [
          "status",
          "passage",
          "totalChars",
          "nextStart",
          "returnedChars",
          "truncated"
        ],
        "description": "Requested window from the pinned revision. nextStart continues the same revision; null means exhausted. Legacy empty/unreadable extraction is a successful empty window with unknown/failed extraction state where known, not proof of complete extraction."
      },
      "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"
        ]
      },
      "Passage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "start": {
            "type": "integer",
            "minimum": 0
          },
          "end": {
            "type": "integer",
            "minimum": 0
          },
          "text": {
            "type": "string"
          },
          "page": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          },
          "startSeconds": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          },
          "endSeconds": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          }
        },
        "required": [
          "source",
          "revision",
          "start",
          "end",
          "text",
          "page",
          "startSeconds",
          "endSeconds"
        ],
        "description": "Exact original-text window. Offsets are half-open UTF-16 code units into the requested evidence revision; surrogate pairs are not split. Page/audio locations are null without a verified extraction map. end-start equals text.length in JavaScript."
      },
      "Source": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "sourceId": {
            "type": "string",
            "pattern": "^(vault:[0-9a-f-]{36}|social:[0-9a-f-]{36}:(caption|transcript))$"
          },
          "kind": {
            "type": "string",
            "enum": [
              "vault",
              "social_caption",
              "reel_transcript"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 300
          },
          "titleTruncated": {
            "type": "boolean"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "Includes empty stored evidence, so unreadable/unknown sources remain identifiable without claiming readable content."
          },
          "publishedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date"
              },
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "description": "Preserve available precision; do not invent a time for a date-only publication."
          },
          "ingestedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "provenance": {
            "$ref": "#/components/schemas/Provenance"
          },
          "extraction": {
            "$ref": "#/components/schemas/Extraction"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 600,
            "description": "Publisher metadata; not original body text and never sufficient support for a premise."
          },
          "descriptionTruncated": {
            "type": "boolean"
          },
          "uploadedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "eventDate": {
            "type": "null",
            "description": "Unknown in the current schema; never inferred from upload/publication time."
          },
          "originalSourceUrl": {
            "type": "null",
            "description": "No verified original/repost relationship is available in legacy storage."
          }
        },
        "required": [
          "sourceId",
          "kind",
          "title",
          "titleTruncated",
          "url",
          "revision",
          "publishedAt",
          "ingestedAt",
          "provenance",
          "extraction",
          "description",
          "descriptionTruncated",
          "uploadedAt",
          "eventDate",
          "originalSourceUrl"
        ]
      },
      "Provenance": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "origin": {
            "type": "string",
            "enum": [
              "vault_link",
              "vault_upload",
              "social_caption",
              "provider_transcript"
            ]
          },
          "provider": {
            "type": [
              "string",
              "null"
            ]
          },
          "method": {
            "type": [
              "string",
              "null"
            ]
          },
          "speaker": {
            "type": "string",
            "enum": [
              "not_applicable",
              "unverified",
              "verified"
            ]
          },
          "publisher": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stored social account username, not a verified speaker identity; null for unestablished publisher."
          },
          "speakerName": {
            "type": "null"
          },
          "relationship": {
            "type": "string",
            "const": "unknown"
          }
        },
        "required": [
          "origin",
          "provider",
          "method",
          "speaker",
          "publisher",
          "speakerName",
          "relationship"
        ]
      },
      "Extraction": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "readiness": {
            "type": "string",
            "enum": [
              "ready",
              "queued",
              "running",
              "failed",
              "unknown"
            ]
          },
          "storedChars": {
            "type": "integer",
            "minimum": 0
          },
          "truncated": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "readiness",
          "storedChars",
          "truncated",
          "limitations"
        ]
      }
    },
    "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."
      }
    }
  }
}
```