{"openapi":"3.1.0","info":{"title":"Raag (Melody) API","version":"0.1.0","description":"A hand-curated Hindustani and Carnatic classical raga reference: thaat/melakarta, aroha/avaroha, vadi/samvadi, time-of-day and mood, talas, swaras, instruments, a Hindustani/Carnatic comparison, and a glossary.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://raag.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/raag/docs"},"termsOfService":"https://connectorbay.com/raag/terms"},"servers":[{"url":"https://raag.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/raag/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/raga_info":{"post":{"operationId":"raga_info","summary":"One raga's parent thaat (Hindustani) or melakarta (Carnatic), aroha/avaroha, vadi/samvadi where","description":"One raga's parent thaat (Hindustani) or melakarta (Carnatic), aroha/avaroha, vadi/samvadi where\n    established, traditional time of day, mood/rasa, and season if any. Use for \"tell me about raga Yaman\",\n    \"what's the parent scale of Kalyani\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A raga name.","examples":["Yaman","Bhairavi","Kalyani","Darbari Kanada"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"raga_infoArguments","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/raga_search":{"post":{"operationId":"raga_search","summary":"Keyword search across every raga's name, thaat/melakarta, tradition and mood. Use for \"find ragas with a","description":"Keyword search across every raga's name, thaat/melakarta, tradition and mood. Use for \"find ragas with a\n    romantic mood\", \"which ragas are in the Kafi thaat\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search across raga name, thaat, tradition and mood.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"raga_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/ragas_by_time":{"post":{"operationId":"ragas_by_time","summary":"Ragas traditionally associated with a time of day. This time theory is a largely Hindustani convention;","description":"Ragas traditionally associated with a time of day. This time theory is a largely Hindustani convention;\n    most Carnatic ragas in this dataset are not tied to a fixed daily slot and won't appear here. Use for \"which\n    ragas are performed in the evening\", \"what should I listen to late at night\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"time_of_day":{"description":"early morning | morning | afternoon | evening | night | late night","title":"Time Of Day","type":"string"}},"required":["time_of_day"],"title":"ragas_by_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/ragas_by_thaat":{"post":{"operationId":"ragas_by_thaat","summary":"Hindustani ragas grouped under one of the ten parent thaats (Bilawal, Kalyan, Khamaj, Bhairav, Bhairavi,","description":"Hindustani ragas grouped under one of the ten parent thaats (Bilawal, Kalyan, Khamaj, Bhairav, Bhairavi,\n    Kafi, Asavari, Marwa, Purvi, Todi). Use for \"which ragas belong to the Bhairav thaat\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"thaat":{"description":"One of the ten Hindustani thaats.","examples":["Bilawal","Kalyan","Khamaj","Bhairav","Bhairavi","Kafi","Asavari","Marwa","Purvi","Todi"],"title":"Thaat","type":"string"}},"required":["thaat"],"title":"ragas_by_thaatArguments","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/swar_reference":{"post":{"operationId":"swar_reference","summary":"The seven swaras (Sa Re Ga Ma Pa Dha Ni) with an approximate Western note-name mapping and their","description":"The seven swaras (Sa Re Ga Ma Pa Dha Ni) with an approximate Western note-name mapping and their\n    komal (flat)/shuddha (natural)/tivra (sharp) variants. Use for \"what are the Indian classical notes\",\n    \"what does komal mean\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"swar_referenceArguments","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/tala_info":{"post":{"operationId":"tala_info","summary":"A tala's beat count and vibhag (division) structure, or the full list of common talas. Use for \"how many","description":"A tala's beat count and vibhag (division) structure, or the full list of common talas. Use for \"how many\n    beats in Teentaal\", \"explain Rupak tala\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A tala name, e.g. Teentaal, Jhaptaal, Ektaal, Rupak, Dadra, Keherwa. Omit to list all.","title":"Name"}},"title":"tala_infoArguments","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/instrument_guide":{"post":{"operationId":"instrument_guide","summary":"A classical instrument's family, how it's played, and its typical role. Use for \"how is a sitar played\",","description":"A classical instrument's family, how it's played, and its typical role. Use for \"how is a sitar played\",\n    \"what's the difference between tabla and mridangam\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"An instrument name, e.g. sitar, tabla, sarod, bansuri, harmonium, tanpura, veena, mridangam, violin. Omit to list all.","title":"Name"}},"title":"instrument_guideArguments","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/carnatic_hindustani_compare":{"post":{"operationId":"carnatic_hindustani_compare","summary":"A short, factual explainer of the key structural differences between the Hindustani and Carnatic","description":"A short, factual explainer of the key structural differences between the Hindustani and Carnatic\n    classical systems (parent-scale system, gamaka, compositional forms, tala system, concert structure) —\n    non-judgmental about either tradition. Use for \"how is Carnatic music different from Hindustani\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"carnatic_hindustani_compareArguments","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_glossary":{"post":{"operationId":"music_glossary","summary":"Definitions of common Hindustani/Carnatic classical-music terms (raga, tala, gharana, gamaka, alap,","description":"Definitions of common Hindustani/Carnatic classical-music terms (raga, tala, gharana, gamaka, alap,\n    bandish, sargam, shruti, laya, sam, khali, tihai). Use for \"what does gamaka mean\", \"what's a gharana\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"music_glossaryArguments","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/random_raga":{"post":{"operationId":"random_raga","summary":"A random raga from this dataset — good for a \"raga of the day\" prompt. Use for \"give me a raga of the","description":"A random raga from this dataset — good for a \"raga of the day\" prompt. Use for \"give me a raga of the\n    day\", \"surprise me with a raga\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional seed for a reproducible pick.","title":"Seed"}},"title":"random_ragaArguments","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}}}}