{"openapi":"3.1.0","info":{"title":"ProofProfile Bot API","description":"Schema.org JSON-LD endpoints optimized for AI bot and search engine consumption. All responses use `application\/ld+json` content type.","version":"1.0.0","contact":{"name":"ProofProfile Support","url":"https:\/\/artists.proofprofile.net\/support"}},"servers":[{"url":"https:\/\/artists.proofprofile.net\/api\/v1"}],"paths":{"\/bot\/artist\/{artist}":{"get":{"operationId":"getBotArtist","summary":"Get artist as Schema.org MusicGroup JSON-LD","parameters":[{"name":"artist","in":"path","required":true,"schema":{"type":"integer"},"description":"Artist ID"}],"responses":{"200":{"description":"Schema.org MusicGroup JSON-LD","content":{"application\/ld+json":{"schema":{"$ref":"#\/components\/schemas\/MusicGroup"}}}},"404":{"description":"Artist not found"},"429":{"description":"Rate limit exceeded"}}}},"\/bot\/album\/{album}":{"get":{"operationId":"getBotAlbum","summary":"Get album as Schema.org MusicAlbum JSON-LD","parameters":[{"name":"album","in":"path","required":true,"schema":{"type":"integer"},"description":"Album ID"}],"responses":{"200":{"description":"Schema.org MusicAlbum JSON-LD","content":{"application\/ld+json":{"schema":{"$ref":"#\/components\/schemas\/MusicAlbum"}}}},"404":{"description":"Album not found"},"429":{"description":"Rate limit exceeded"}}}},"\/bot\/track\/{track}":{"get":{"operationId":"getBotTrack","summary":"Get track as Schema.org MusicRecording JSON-LD","parameters":[{"name":"track","in":"path","required":true,"schema":{"type":"integer"},"description":"Track ID"}],"responses":{"200":{"description":"Schema.org MusicRecording JSON-LD","content":{"application\/ld+json":{"schema":{"$ref":"#\/components\/schemas\/MusicRecording"}}}},"404":{"description":"Track not found"},"429":{"description":"Rate limit exceeded"}}}},"\/bot\/track\/by-isrc\/{isrc}":{"get":{"operationId":"getBotTrackByIsrc","summary":"Get a track by its public recording identity","description":"ISRC joins the pre-2022 source recording to the authoritative cc-db-prod notarized record.","parameters":[{"name":"isrc","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9]{12}$"},"description":"12-character International Standard Recording Code"}],"responses":{"200":{"description":"Schema.org MusicRecording JSON-LD","content":{"application\/ld+json":{"schema":{"$ref":"#\/components\/schemas\/MusicRecording"}}}},"404":{"description":"Track not found or invalid identifier"},"429":{"description":"Rate limit exceeded"}}}},"\/bot\/playlist\/{playlist}":{"get":{"operationId":"getBotPlaylist","summary":"Get playlist as Schema.org MusicPlaylist JSON-LD","parameters":[{"name":"playlist","in":"path","required":true,"schema":{"type":"integer"},"description":"Playlist ID"}],"responses":{"200":{"description":"Schema.org MusicPlaylist JSON-LD","content":{"application\/ld+json":{"schema":{"$ref":"#\/components\/schemas\/MusicPlaylist"}}}},"404":{"description":"Playlist not found"},"429":{"description":"Rate limit exceeded"}}}},"\/bot\/search":{"get":{"operationId":"searchBot","summary":"Search catalog and return Schema.org SearchResultsPage JSON-LD","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":500},"description":"Search query string"},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["keyword","semantic"],"default":"keyword"},"description":"Search type: keyword (local DB) or semantic (AI vector search)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum number of results"}],"responses":{"200":{"description":"Schema.org SearchResultsPage JSON-LD","content":{"application\/ld+json":{"schema":{"$ref":"#\/components\/schemas\/SearchResultsPage"}}}},"400":{"description":"Invalid query parameters"},"429":{"description":"Rate limit exceeded"}}}},"\/bot\/ots\/verify\/{entityType}\/{entityId}":{"get":{"operationId":"verifyOtsProof","summary":"Pre-computed 6-check OpenTimestamps verification result","description":"Server-side dual-chain verification: canonical-record existence, proof existence, SHA-256 hash match, OTS attestation, Bitcoin block existence, and timestamp consistency. Tracks are keyed by public ISRC; artist, album, and playlist proofs are keyed by ProofProfile UUID.","parameters":[{"name":"entityType","in":"path","required":true,"schema":{"type":"string","enum":["artist","album","playlist","track"]},"description":"Entity type of the proof to verify"},{"name":"entityId","in":"path","required":true,"schema":{"type":"string"},"description":"Track: 12-character ISRC. Artist\/album\/playlist: ProofProfile entity UUID (found in OTSVerificationAPI on the entity JSON-LD)."}],"responses":{"200":{"description":"Verification result with per-check booleans, content hash, Bitcoin block, and timestamps","content":{"application\/json":{"schema":{"type":"object","properties":{"verified":{"type":"boolean"},"entity_type":{"type":"string"},"entity_id":{"type":"string"},"checks":{"type":"object"},"external_reachable":{"type":"boolean"},"content_hash":{"type":"string"},"bitcoin_block":{"type":"integer"},"bitcoin_time":{"type":"string","format":"date-time"},"confirmed_at":{"type":"string","format":"date-time"}}}}}},"404":{"description":"No confirmed proof for this entity"},"429":{"description":"Rate limit exceeded"}}}}},"components":{"schemas":{"MusicGroup":{"type":"object","properties":{"@context":{"type":"string","example":"https:\/\/schema.org"},"@type":{"type":"string","example":"MusicGroup"},"name":{"type":"string"},"image":{"type":"string","format":"uri"},"genre":{"type":"array","items":{"type":"string"}},"sameAs":{"type":"array","items":{"type":"string","format":"uri"}},"album":{"type":"array","items":{"type":"object"}},"track":{"type":"array","items":{"type":"object"}}}},"MusicAlbum":{"type":"object","properties":{"@context":{"type":"string","example":"https:\/\/schema.org"},"@type":{"type":"string","example":"MusicAlbum"},"name":{"type":"string"},"image":{"type":"string","format":"uri"},"datePublished":{"type":"string","format":"date"},"byArtist":{"type":"array","items":{"type":"object"}},"track":{"type":"array","items":{"type":"object"}}}},"MusicRecording":{"type":"object","properties":{"@context":{"type":"string","example":"https:\/\/schema.org"},"@type":{"type":"string","example":"MusicRecording"},"name":{"type":"string"},"duration":{"type":"string","description":"ISO 8601 duration, e.g. PT3M45S"},"byArtist":{"type":"array","items":{"type":"object"}},"inAlbum":{"type":"object"},"isrcCode":{"type":"string"}}},"MusicPlaylist":{"type":"object","properties":{"@context":{"type":"string","example":"https:\/\/schema.org"},"@type":{"type":"string","example":"MusicPlaylist"},"name":{"type":"string"},"numTracks":{"type":"integer"},"track":{"type":"array","items":{"type":"object"}}}},"SearchResultsPage":{"type":"object","properties":{"@context":{"type":"string","example":"https:\/\/schema.org"},"@type":{"type":"string","example":"SearchResultsPage"},"name":{"type":"string"},"query":{"type":"string"},"mainEntity":{"type":"object"}}}}}}