# Search original evidence

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

Find original evidence

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

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/search": {
      "get": {
        "operationId": "searchArtistKnowledge",
        "summary": "Find original evidence",
        "description": "Search all accessible stored source text or declare omitted coverage. Do not search only the start of a long source. Match qualification and source identity survive ranking. History/corrections are loaded with getInterviewHistory, never dependent on a semantic hit.",
        "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": "query",
            "in": "query",
            "required": true,
            "description": "Research question or keywords.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum original passages.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 5
            }
          },
          {
            "name": "maxChars",
            "in": "query",
            "required": false,
            "description": "Maximum total evidence text characters.",
            "schema": {
              "type": "integer",
              "minimum": 1000,
              "maximum": 12000,
              "default": 6000
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Optional source-kind filter.",
            "schema": {
              "type": "string",
              "enum": [
                "vault",
                "social_caption",
                "reel_transcript"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded stored evidence; Cache-Control: private, no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Search"
                }
              }
            }
          },
          "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": {
      "Search": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "passages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Passage"
            },
            "maxItems": 10
          },
          "coverage": {
            "$ref": "#/components/schemas/Coverage"
          },
          "returnedChars": {
            "type": "integer",
            "minimum": 0,
            "maximum": 12000
          },
          "truncated": {
            "type": "boolean"
          }
        },
        "required": [
          "status",
          "passages",
          "coverage",
          "returnedChars",
          "truncated"
        ],
        "description": "Top ranked matches, not an exhaustive archive. Empty matches with accurate coverage is a success. Search may be incomplete only with explicit limitations. Expand a hit by source ID/revision; do not claim no relevant history from no matches."
      },
      "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."
      },
      "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."
      },
      "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."
      }
    }
  }
}
```