{"openapi":"3.1.0","info":{"title":"Uud (Oud & Incense) API","version":"0.1.0","description":"A hand-curated, fully local reference on the oud musical instrument and traditional Arab incense/perfume culture: bakhoor, agarwood/oud oil, attar, and mabkhara/majmar burners.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://uud.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/uud/docs"},"termsOfService":"https://connectorbay.com/uud/terms"},"servers":[{"url":"https://uud.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/uud/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/instrument_info":{"post":{"operationId":"instrument_info","summary":"The oud (instrument)'s construction, parts (bowl body, soundboard, pegbox, strings), typical string","description":"The oud (instrument)'s construction, parts (bowl body, soundboard, pegbox, strings), typical string\n    count and tuning approaches — a factual instrument reference. Not to be confused with oud/agarwood, the\n    fragrance material (see agarwood_oud_info). For maqam theory and playing theory, see the Nagham\n    connector. Use for \"what are the parts of an oud\", \"how many strings does an oud have\", \"how is an oud\n    tuned\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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/bakhoor_guide":{"post":{"operationId":"bakhoor_guide","summary":"What bakhoor incense is, how it is traditionally burned (over charcoal in a mabkhara or majmar), and","description":"What bakhoor incense is, how it is traditionally burned (over charcoal in a mabkhara or majmar), and\n    the hospitality and occasion customs around it. Use for \"what is bakhoor\", \"how do you burn bakhoor\",\n    \"why do people burn incense for guests\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"bakhoor_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/agarwood_oud_info":{"post":{"operationId":"agarwood_oud_info","summary":"Agarwood/oud as a fragrance material — what it is, its forms (chips and oil), origin regions, and","description":"Agarwood/oud as a fragrance material — what it is, its forms (chips and oil), origin regions, and\n    grading terminology. No pricing, no medicinal or therapeutic claims. Not to be confused with the oud\n    musical instrument (see instrument_info). Use for \"what is agarwood\", \"where does oud oil come from\",\n    \"what does oud grading mean\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"agarwood_oud_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/attar_perfume_guide":{"post":{"operationId":"attar_perfume_guide","summary":"Traditional non-alcohol perfume-oil (attar) culture and its common traditional note families — rose,","description":"Traditional non-alcohol perfume-oil (attar) culture and its common traditional note families — rose,\n    oud, amber and musk-type notes — including an accurate note that traditional \"musk\" today is\n    essentially always synthetic or plant-based, not animal-derived. Use for \"what is attar\", \"is musk in\n    perfume from an animal\", \"what notes are used in traditional Arab perfume\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"attar_perfume_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/burner_types_guide":{"post":{"operationId":"burner_types_guide","summary":"Mabkhara and majmar incense-burner types, materials and regional styles (wood, ceramic, metal,","description":"Mabkhara and majmar incense-burner types, materials and regional styles (wood, ceramic, metal,\n    electric, and Maghrebi-style burners). Use for \"what's a mabkhara\", \"what's the difference between a\n    mabkhara and a majmar\", \"what are incense burners made of\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"burner":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific burner type or key; omit to list all.","title":"Burner"}},"title":"burner_types_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/occasion_guide":{"post":{"operationId":"occasion_guide","summary":"When bakhoor/incense is traditionally used for a given occasion — welcoming guests, weddings (see","description":"When bakhoor/incense is traditionally used for a given occasion — welcoming guests, weddings (see\n    the Zafaf connector for the wedding traditions themselves), Eid, or everyday use. Use for \"when do\n    people burn incense for guests\", \"is incense used at weddings\", \"do people burn bakhoor for Eid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"occasion":{"description":"An occasion.","examples":["welcoming guests","wedding","Eid","everyday"],"title":"Occasion","type":"string"}},"required":["occasion"],"title":"occasion_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/oud_family_glossary":{"post":{"operationId":"oud_family_glossary","summary":"Definitions of about a dozen core terms, clearly split between the oud instrument's vocabulary","description":"Definitions of about a dozen core terms, clearly split between the oud instrument's vocabulary\n    (risha, pegbox, course) and the oud/agarwood fragrance vocabulary (bakhoor, mabkhara, dahn al-oud).\n    Use for \"what does dahn al-oud mean\", \"what's a risha\", \"what's the difference between oud the\n    instrument and oud the fragrance\".","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":"oud_family_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/care_and_etiquette_guide":{"post":{"operationId":"care_and_etiquette_guide","summary":"General oud-instrument care basics (storage, cleaning, strings, tuning pegs) and incense-offering","description":"General oud-instrument care basics (storage, cleaning, strings, tuning pegs) and incense-offering\n    etiquette for a guest. Use for \"how do I take care of an oud\", \"what do I do if a host offers me\n    incense\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"care_and_etiquette_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/search":{"post":{"operationId":"search","summary":"Search across every reference entry — the instrument, bakhoor, agarwood/oud fragrance, attar, burner","description":"Search across every reference entry — the instrument, bakhoor, agarwood/oud fragrance, attar, burner\n    types, occasions, glossary terms and care/etiquette guidance. Use for a broad query that does not map\n    cleanly onto one specific tool, e.g. \"musk\", \"hospitality\", \"Gulf incense burner\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Free-text search over every reference entry.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"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}}}}