{"openapi":"3.1.0","info":{"title":"Shelf API","version":"0.1.0","description":"Books, authors, free ebooks, podcasts and music (previews, artists, albums) from open catalogues — keyless, nothing stored.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://shelf.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/shelf/docs"},"termsOfService":"https://connectorbay.com/shelf/terms"},"servers":[{"url":"https://shelf.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/shelf/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/book_search":{"post":{"operationId":"book_search","summary":"Search Open Library's catalogue of ~40 million books: title, authors, first publication year, editions, median pages,","description":"Search Open Library's catalogue of ~40 million books: title, authors, first publication year, editions, median pages,\n    readers' rating, subjects, languages, ISBNs, cover, whether it is free to read online with the link. Use for \"who wrote\n    X\", \"books by Ursula Le Guin\", \"Spanish books about astronomy\", \"free classics about the sea\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Words from the title or anything: 'the hobbit', 'left hand of darkness'.","examples":["the hobbit"],"title":"Query"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Exact-ish title.","title":"Title"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Author name.","title":"Author"},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Subject: 'beekeeping', 'science fiction'.","title":"Subject"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"3-letter language code: eng, spa, fre, ger, hin, ara…","title":"Language"},"free_only":{"default":false,"description":"Only books free to read online (public domain scans).","title":"Free Only","type":"boolean"},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"'rating', 'new', 'old', 'editions' (default relevance).","title":"Sort"},"limit":{"default":10,"description":"Max results (1–30).","maximum":30,"minimum":1,"title":"Limit","type":"integer"}},"title":"book_searchArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/book":{"post":{"operationId":"book","summary":"One edition by ISBN: title, authors, publisher and date, pages, format, languages, description, subjects, first","description":"One edition by ISBN: title, authors, publisher and date, pages, format, languages, description, subjects, first\n    publication of the work, cover, identifiers (Goodreads, LCCN…), and a read-online link if the Internet Archive has a\n    scan. Use for \"what is this ISBN\", \"details of the book with barcode 978…\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"isbn":{"description":"ISBN-10 or ISBN-13, hyphens optional.","examples":["9780547928227"],"title":"Isbn","type":"string"}},"required":["isbn"],"title":"bookArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/author":{"post":{"operationId":"author","summary":"An author from Open Library: dates, bio, number of works, top subjects, links, and their most-published books with","description":"An author from Open Library: dates, bio, number of works, top subjects, links, and their most-published books with\n    ratings. Use for \"who is Ursula Le Guin\", \"what did Chinua Achebe write\", \"when was Tolkien born\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Author's name.","examples":["Ursula K. Le Guin"],"title":"Name","type":"string"}},"required":["name"],"title":"authorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/books_by_subject":{"post":{"operationId":"books_by_subject","summary":"The most-held books on a subject in Open Library (by number of editions): title, authors, year, cover, and free","description":"The most-held books on a subject in Open Library (by number of editions): title, authors, year, cover, and free\n    read-online links where a public scan exists. Use for \"classic science fiction\", \"good books about beekeeping\",\n    \"free books on Roman history\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subject":{"description":"A subject: 'science fiction', 'beekeeping', 'Roman history'.","examples":["science fiction"],"title":"Subject","type":"string"},"free_only":{"default":false,"description":"Only books with a free online scan.","title":"Free Only","type":"boolean"},"limit":{"default":12,"description":"Max results (1–30).","maximum":30,"minimum":1,"title":"Limit","type":"integer"}},"required":["subject"],"title":"books_by_subjectArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/free_ebooks":{"post":{"operationId":"free_ebooks","summary":"Books that are free to read online right now — public-domain scans on the Internet Archive via Open Library — with","description":"Books that are free to read online right now — public-domain scans on the Internet Archive via Open Library — with\n    the read link, authors and year. Use for \"is Moby-Dick free\", \"free Jane Austen\", \"public-domain books about\n    gardening\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Title, author or topic.","examples":["Jane Austen"],"title":"Query","type":"string"},"limit":{"default":10,"description":"Max results (1–30).","maximum":30,"minimum":1,"title":"Limit","type":"integer"}},"required":["query"],"title":"free_ebooksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/isbn_check":{"post":{"operationId":"isbn_check","summary":"Validate an ISBN's check digit and convert between ISBN-10 and ISBN-13, with the registration group (language area)","description":"Validate an ISBN's check digit and convert between ISBN-10 and ISBN-13, with the registration group (language area)\n    decoded. Local, instant. Use for \"is this ISBN valid\", \"convert this ISBN-10 to 13\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"isbn":{"description":"An ISBN-10 or ISBN-13.","examples":["0-547-92822-7"],"title":"Isbn","type":"string"}},"required":["isbn"],"title":"isbn_checkArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/reading_time":{"post":{"operationId":"reading_time","summary":"How long a book takes to read from its page or word count at a chosen speed (adult average ≈ 238 wpm, ~275 words per","description":"How long a book takes to read from its page or word count at a chosen speed (adult average ≈ 238 wpm, ~275 words per\n    page), and how many days at a daily budget. Use for \"how long is a 400-page novel\", \"can I finish this in a week at 30\n    minutes a day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"pages":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Page count.","title":"Pages"},"words":{"anyOf":[{"maximum":5000000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Word count (instead of pages).","title":"Words"},"words_per_minute":{"default":238,"description":"Reading speed (150 slow – 400 fast; 238 is the adult average).","maximum":1000,"minimum":100,"title":"Words Per Minute","type":"integer"},"minutes_per_day":{"anyOf":[{"maximum":1440,"minimum":5,"type":"integer"},{"type":"null"}],"default":null,"description":"Daily reading budget to estimate days to finish.","title":"Minutes Per Day"}},"title":"reading_timeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/podcast_search":{"post":{"operationId":"podcast_search","summary":"Find podcasts in the Apple Podcasts directory: name, publisher, genre, episode count, latest release, artwork, Apple","description":"Find podcasts in the Apple Podcasts directory: name, publisher, genre, episode count, latest release, artwork, Apple\n    page and the RSS feed URL (pass it to podcast_episodes). Use for \"find the Hardcore History podcast\", \"podcasts about\n    Roman history\", \"Hindi news podcasts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Show name or topic.","examples":["Hardcore History"],"title":"Query","type":"string"},"country":{"default":"US","description":"Store country code for the directory (US, GB, IN, BR…).","title":"Country","type":"string"},"limit":{"default":8,"description":"Max results (1–30).","maximum":30,"minimum":1,"title":"Limit","type":"integer"}},"required":["query"],"title":"podcast_searchArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/podcast_episodes":{"post":{"operationId":"podcast_episodes","summary":"A podcast's latest episodes from its own feed: title, date, duration, season/episode numbers, summary, audio URL and","description":"A podcast's latest episodes from its own feed: title, date, duration, season/episode numbers, summary, audio URL and\n    link, plus the show's description and website. Use for \"latest episode of X\", \"what has Y released this month\", \"get\n    the audio link for the newest episode\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"feed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The show's RSS feed URL (from podcast_search).","title":"Feed Url"},"show":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Or the show name — Shelf finds the feed for you.","title":"Show"},"limit":{"default":10,"description":"Max results (1–30).","maximum":30,"minimum":1,"title":"Limit","type":"integer"}},"title":"podcast_episodesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/music_search":{"post":{"operationId":"music_search","summary":"Search music: tracks (with artist, album, length, explicit flag, ISRC and a 30-second preview MP3), artists (fans,","description":"Search music: tracks (with artist, album, length, explicit flag, ISRC and a 30-second preview MP3), artists (fans,\n    album count) or albums. Use for \"find the song Creep\", \"preview Blinding Lights\", \"albums called Rumours\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Song, artist and/or album words: 'radiohead creep', 'blinding lights'.","examples":["radiohead creep"],"title":"Query","type":"string"},"kind":{"default":"track","description":"'track' (default), 'artist' or 'album'.","title":"Kind","type":"string"},"limit":{"default":8,"description":"Max results (1–30).","maximum":30,"minimum":1,"title":"Limit","type":"integer"}},"required":["query"],"title":"music_searchArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/artist":{"post":{"operationId":"artist","summary":"An artist's profile: type (person/group), country, active years, genre tags and official links (MusicBrainz), plus","description":"An artist's profile: type (person/group), country, active years, genre tags and official links (MusicBrainz), plus\n    top tracks with previews and studio albums with dates (Deezer). Use for \"tell me about Radiohead\", \"what are Adele's\n    biggest songs\", \"list Nirvana's albums\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Artist or band name.","examples":["Radiohead"],"title":"Name","type":"string"}},"required":["name"],"title":"artistArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/album":{"post":{"operationId":"album","summary":"An album's details and full tracklist: release date, label, genres, length, UPC, cover, and every track with duration","description":"An album's details and full tracklist: release date, label, genres, length, UPC, cover, and every track with duration\n    and a 30-second preview. Use for \"what's on OK Computer\", \"when did Rumours come out\", \"tracklist of Thriller\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"description":"Album title.","examples":["OK Computer"],"title":"Title","type":"string"},"artist":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Artist, to disambiguate.","examples":["Radiohead"],"title":"Artist"}},"required":["title"],"title":"albumArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}