Artist knowledge

Read an original source

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.

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

GET

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

Authorization

Authorizationstringrequired

Existing authenticated Music Nerd user, approved artist claimant or admin. Credentials remain outside model arguments. Kept in this tab only.

Bearer

Path

idstringrequired

Artist ID in this deployment environment. Authorize claimant/admin on each call.

sourceIdstringrequired

Namespaced source record; must belong to this artist.

Query

revisionstringrequired

Revision returned by source listing or search.

startinteger

UTF-16 offset; beyond source length is invalid.

maxCharsinteger

Maximum original-text window.

includeVersionboolean

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.

cURL

curl --request GET \
  --url 'https://musicnerd-api.vercel.app/api/artist/{id}/knowledge/sources/{sourceId}?start=0&maxChars=6000&includeVersion=false'

Send the request to see the live response here.

cURL

curl --request GET \
  --url 'https://musicnerd-api.vercel.app/api/artist/YOUR_ID/knowledge/sources/YOUR_SOURCE_ID?revision=YOUR_REVISION' \
  --header 'Authorization: Bearer YOUR_TOKEN'

{
  "status": "ok",
  "passage": {
    "source": {
      "sourceId": "string",
      "kind": "vault",
      "titleTruncated": true,
      "revision": "string",
      "publishedAt": "string",
      "provenance": {
        "origin": "vault_link",
        "speaker": "not_applicable",
        "relationship": "string"
      },
      "extraction": {
        "readiness": "ready",
        "storedChars": 0,
        "limitations": [
          "string"
        ]
      },
      "descriptionTruncated": true
    },
    "revision": "string",
    "start": 0,
    "end": 0,
    "text": "string"
  },
  "totalChars": 0,
  "returnedChars": 0,
  "truncated": true
}

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>. Existing authenticated Music Nerd user, approved artist claimant or admin. Credentials remain outside model arguments.

Path Parameters

idstringrequired

Artist ID in this deployment environment. Authorize claimant/admin on each call.

sourceIdstringrequired

Namespaced source record; must belong to this artist.

Query Parameters

revisionstringrequired

Revision returned by source listing or search.

startinteger

UTF-16 offset; beyond source length is invalid.

Default: 0

maxCharsinteger

Maximum original-text window.

Default: 6000

includeVersionboolean

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.

Default: false

Response

application/json

Bounded stored evidence; Cache-Control: private, no-store.

statusstring · enumrequired

Values: "ok"

passageobjectrequired

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.

Properties

sourceobjectrequired

Properties

sourceIdstringrequired

pattern: ^(vault:[0-9a-f-]{36}|social:[0-9a-f-]{36}:(caption|transcript))$

kindstring · enumrequired

Values: "vault", "social_caption", "reel_transcript"

titlestring | nullrequired

maxLength: 300

titleTruncatedbooleanrequired

urlstring | nullrequired

format: uri

revisionstringrequired

Includes empty stored evidence, so unreadable/unknown sources remain identifiable without claiming readable content.

pattern: ^[a-f0-9]{64}$

publishedAtany ofrequired

Preserve available precision; do not invent a time for a date-only publication.

Properties

anyOf · string 1

string

anyOf · string 2

string

anyOf · null 3

null

ingestedAtstring | nullrequired

format: date-time

provenanceobjectrequired

Properties

originstring · enumrequired

Values: "vault_link", "vault_upload", "social_caption", "provider_transcript"

providerstring | nullrequired

methodstring | nullrequired

speakerstring · enumrequired

Values: "not_applicable", "unverified", "verified"

publisherstring | nullrequired

Stored social account username, not a verified speaker identity; null for unestablished publisher.

speakerNamenullrequired

relationshipstringrequired

extractionobjectrequired

Properties

readinessstring · enumrequired

Values: "ready", "queued", "running", "failed", "unknown"

storedCharsintegerrequired

minimum: 0

truncatedboolean | nullrequired

limitationsarray<string>required

Item properties

string

descriptionstring | nullrequired

Publisher metadata; not original body text and never sufficient support for a premise.

maxLength: 600

descriptionTruncatedbooleanrequired

uploadedAtstring | nullrequired

format: date-time

eventDatenullrequired

Unknown in the current schema; never inferred from upload/publication time.

originalSourceUrlnullrequired

No verified original/repost relationship is available in legacy storage.

revisionstringrequired

pattern: ^[a-f0-9]{64}$

startintegerrequired

minimum: 0

endintegerrequired

minimum: 0

textstringrequired

pageinteger | nullrequired

minimum: 1

startSecondsnumber | nullrequired

minimum: 0

endSecondsnumber | nullrequired

minimum: 0

totalCharsintegerrequired

minimum: 0

nextStartinteger | nullrequired

minimum: 0

returnedCharsintegerrequired

minimum: 0 · maximum: 20000

truncatedbooleanrequired

versionobject

Required when includeVersion=true; omitted for legacy current-only reads.

Properties

statestring · enumrequired

Values: "current", "historical"

currentRevisionstringrequired

pattern: ^[a-f0-9]{64}$

capturedAtstring | nullrequired

Retention time, not publication/event time; null for a current read.

format: date-time