{"openapi":"3.1.0","info":{"title":"Nagham (Melody) API","version":"0.1.0","description":"A hand-curated, fully local Arabic music reference: the maqam system, traditional instruments, regional styles, the takht ensemble, rhythmic patterns, a glossary, a region map, and historical-figure biographies.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://nagham.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/nagham/docs"},"termsOfService":"https://connectorbay.com/nagham/terms"},"servers":[{"url":"https://nagham.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/nagham/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/maqam_info":{"post":{"operationId":"maqam_info","summary":"One maqam's tonal character, mood/association and related maqamat. Use for \"what is maqam Hijaz\",","description":"One maqam's tonal character, mood/association and related maqamat. Use for \"what is maqam Hijaz\",\n    \"describe maqam Saba\", \"what mood does Nahawand have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A maqam name.","examples":["Rast","Bayati","Hijaz","Saba"],"title":"Name","type":"string"}},"required":["name"],"title":"maqam_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/maqam_search":{"post":{"operationId":"maqam_search","summary":"Search maqamat by a free-text query. Use for \"which maqamat sound sad\", \"what maqamat use quarter","description":"Search maqamat by a free-text query. Use for \"which maqamat sound sad\", \"what maqamat use quarter\n    tones\", \"maqamat related to Nahawand\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Free-text search over maqam names, families, moods and descriptions.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"maqam_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/instrument_info":{"post":{"operationId":"instrument_info","summary":"A traditional instrument's family, construction, playing technique and role in the ensemble. Use for","description":"A traditional instrument's family, construction, playing technique and role in the ensemble. Use for\n    \"how is an oud played\", \"what is a qanun\", \"what family is the nay in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"An instrument name.","examples":["oud","qanun","nay","darbuka","riq"],"title":"Name","type":"string"}},"required":["name"],"title":"instrument_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/music_style_info":{"post":{"operationId":"music_style_info","summary":"One major regional Arabic music style's history and characteristics — Khaleeji, Tarab/Egyptian","description":"One major regional Arabic music style's history and characteristics — Khaleeji, Tarab/Egyptian\n    classical, Andalusian/Maghrebi, Levantine, or Iraqi maqam. Use for \"what is Tarab\", \"tell me about\n    Khaleeji music\", \"what's the Andalusian music tradition\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"style":{"description":"A regional music style.","examples":["Khaleeji","Tarab","Andalusian","Levantine","Iraqi maqam"],"title":"Style","type":"string"}},"required":["style"],"title":"music_style_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/historical_figure_info":{"post":{"operationId":"historical_figure_info","summary":"Strictly biographical/encyclopedic facts — years active, genre, significance — for a historically","description":"Strictly biographical/encyclopedic facts — years active, genre, significance — for a historically\n    significant Arab musician or composer. Never lyrics or copyrighted material. Use for \"who was Umm\n    Kulthum\", \"tell me about Fairuz\", \"when did Ziryab live\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A historically significant Arab musician or composer.","examples":["Umm Kulthum","Fairuz","Ziryab","Mohammed Abdel Wahab"],"title":"Name","type":"string"}},"required":["name"],"title":"historical_figure_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/ensemble_guide":{"post":{"operationId":"ensemble_guide","summary":"The traditional takht chamber ensemble's makeup and how its instruments combine. Use for \"what","description":"The traditional takht chamber ensemble's makeup and how its instruments combine. Use for \"what\n    instruments are in a takht\", \"how does a traditional Arabic ensemble work\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"ensemble_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/rhythm_pattern_info":{"post":{"operationId":"rhythm_pattern_info","summary":"A common Arabic rhythmic pattern's (iqa') beat structure, described in words and counts, not audio.","description":"A common Arabic rhythmic pattern's (iqa') beat structure, described in words and counts, not audio.\n    Use for \"how does the Maqsum rhythm go\", \"what is the Baladi beat\", \"describe the Malfuf rhythm\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A rhythmic pattern (iqa').","examples":["Maqsum","Baladi","Malfuf","Saidi"],"title":"Name","type":"string"}},"required":["name"],"title":"rhythm_pattern_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/music_glossary":{"post":{"operationId":"music_glossary","summary":"Definitions of core Arabic music terms (maqam, taqsim, mawwal, quarter tone, takht, tarab, layali,","description":"Definitions of core Arabic music terms (maqam, taqsim, mawwal, quarter tone, takht, tarab, layali,\n    sama'i, muwashshah, and more). Use for \"what does taqsim mean\", \"what's tarab\".","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/region_music_map":{"post":{"operationId":"region_music_map","summary":"Which music styles and instruments are most associated with a given region (the Gulf, Egypt, the","description":"Which music styles and instruments are most associated with a given region (the Gulf, Egypt, the\n    Levant, the Maghreb, Iraq); omit to list all regions. Use for \"what music comes from the Gulf\", \"what\n    styles are associated with the Levant\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A region.","examples":["Gulf","Egypt","Levant","Maghreb","Iraq"],"title":"Region"}},"title":"region_music_mapArguments","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}}}}