# Read research original Source: https://docs.musicnerd.net/api-reference/research/research-evidence Read a public research original ## GET /api/artist/{id}/research/evidence/{evidenceId} Full OpenAPI specification: https://docs.musicnerd.net/spec/question-research.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": "Question-directed artist research", "version": "0.1.0", "description": "Preview contract. Apply the Web-owned research schema before enabling the matching API implementation. Web Ask About reserves a bounded planning slot before its model call: at most 10 new question plans per artist and 200 globally over rolling 24 hours, recorded without question or conversation text. This is separate from the API research ledgers; polling existing jobs does not plan again. Rejected reservations perform no model call. Planning uses no automatic model retries." }, "servers": [ { "url": "https://musicnerd-api.vercel.app" } ], "paths": { "/api/artist/{id}/research/evidence/{evidenceId}": { "get": { "summary": "Read a public research original", "description": "Reopen an exact source/revision/window. A URL-encoded discovery:UUID, vault:UUID public_answer:UUID or social:UUID:caption|transcript sourceId is accepted; a bare evidence UUID remains supported. Saved Lore/social reads use the current eligible public revision and return 409 on change. Retained discovery versions remain readable while current curation and access permit them. Published responses already visible in Latest are eligible with exact response text; edited responses invalidate old revisions and unpublished/deleted responses become unavailable. Uploaded/private material, private interview sessions and correction history are excluded. Current claimant/admin may inspect unresolved discoveries for review.", "security": [ { "PrivyAuth": [] }, { "ResearchService": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "evidenceId", "in": "path", "required": true, "schema": { "type": "string", "description": "URL-encoded sourceId from a returned reference, or a discovery evidence UUID" } }, { "name": "revision", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, { "name": "start", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0, "maximum": 4000000 } }, { "name": "maxChars", "in": "query", "schema": { "type": "integer", "minimum": 256, "maximum": 12000, "default": 4000 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "passage", "totalChars", "nextStart" ], "properties": { "status": { "const": "ok" }, "passage": { "$ref": "#/components/schemas/Reference" }, "totalChars": { "type": "integer" }, "nextStart": { "type": [ "integer", "null" ] } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current claimant/admin required for private operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable artist, job or evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or revision changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Evidence exceeds supported bounds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Research quota or active-work limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "For a quota response, matches retryAfterSeconds from its actual rolling-window boundary. Active-work conflicts retain a short retry hint.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Storage, credential or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Reference": { "type": "object", "required": [ "sourceId", "revision", "start", "end", "text", "url", "curation" ], "properties": { "sourceId": { "type": "string", "description": "Stable current source reference, including latest::<64hex> provider snapshot originals. Removing/changing the connected account or successfully refreshing away a hidden/removed item makes its old reference unavailable; changed originals have a different revision." }, "revision": { "type": "string" }, "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 }, "text": { "type": "string" }, "url": { "type": "string" }, "curation": { "type": "string", "enum": [ "approved", "pending" ] }, "evidenceKind": { "type": "string", "enum": [ "original_text", "caption", "provider_transcript" ] }, "speaker": { "type": "string", "enum": [ "not_applicable", "unverified" ] }, "publishedAt": { "type": [ "string", "null" ] }, "retrievedAt": { "type": [ "string", "null" ] }, "truncated": { "type": [ "boolean", "null" ] }, "activityDate": { "type": "string", "description": "Optional provider activity date. Preserves YYYY, YYYY-MM or full date/time precision. Never substitutes for source publication time." }, "activityDateKind": { "type": "string", "enum": [ "release", "moment" ], "description": "Meaning of activityDate. Exact catalog release-date claims require original catalog text, not publishedAt." } } }, "Error": { "type": "object", "required": [ "status", "error", "code" ], "properties": { "status": { "const": "error" }, "error": { "type": "string" }, "code": { "type": "string" }, "quotaScope": { "type": "string", "enum": [ "saved_global", "outside_artist", "outside_global" ], "description": "Shared operational budget that blocked this work, never a personal visitor limit." }, "retryAfterSeconds": { "type": "integer", "minimum": 0, "description": "Seconds until resetAt, rounded up. A current status read recomputes this duration; new traffic can consume later capacity." }, "resetAt": { "type": "string", "format": "date-time", "description": "Actual rolling-window boundary calculated when the quota was checked." } } } }, "securitySchemes": { "PrivyAuth": { "type": "http", "scheme": "bearer", "description": "Current artist claimant or administrator Privy access token." }, "ResearchService": { "type": "apiKey", "in": "header", "name": "X-MusicNerd-Research-Key", "description": "Server-only MUSICNERD_RESEARCH_API_KEY. Public evidence research only; never grants review or interview-history access." } } } } ```