{"openapi":"3.1.0","info":{"title":"Souq (Market) API","version":"0.1.0","description":"A hand-curated reference to traditional Arab souq (marketplace) culture: generic souq-type profiles, the bargaining custom explained respectfully, common transliterated marketplace phrases, a gold-souq pricing primer with no live prices, historical/architectural context, and a glossary.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://souq.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/souq/docs"},"termsOfService":"https://connectorbay.com/souq/terms"},"servers":[{"url":"https://souq.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/souq/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/souq_type_info":{"post":{"operationId":"souq_type_info","summary":"A generic profile of one traditional souq category -- typical goods sold, common layout, and a few","description":"A generic profile of one traditional souq category -- typical goods sold, common layout, and a few\n    signature features -- described typologically (\"a gold souq typically...\") rather than as a listing of any\n    specific real, currently-operating market. Covers gold, spice, textile, fish, livestock (historical),\n    copper/metalwork, and perfume/incense souqs. Use for \"tell me about a gold souq\", \"what's a spice souq\n    like\", \"what is a livestock souq\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"description":"A souq category.","examples":["gold","spice","textile","fish","livestock","copper","perfume"],"minLength":1,"title":"Type","type":"string"}},"required":["type"],"title":"souq_type_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/bargaining_etiquette_guide":{"post":{"operationId":"bargaining_etiquette_guide","summary":"The customary back-and-forth of bargaining (haggling) in a traditional souq: when it's expected versus","description":"The customary back-and-forth of bargaining (haggling) in a traditional souq: when it's expected versus\n    when prices are fixed (independent stalls vs. marked-price shops, supermarkets and malls), the general\n    process from opening price to settling or parting ways, starting-offer and walking-away conventions, and a\n    few practical tips -- framed respectfully throughout as a legitimate, long-practiced commercial custom, not\n    a stereotype. Use for \"how does haggling work in a souq\", \"is bargaining rude\", \"how do I start negotiating\n    a price\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"bargaining_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/common_phrases_guide":{"post":{"operationId":"common_phrases_guide","summary":"A handful of well-attested, commonly used transliterated Arabic marketplace phrases -- a greeting, a","description":"A handful of well-attested, commonly used transliterated Arabic marketplace phrases -- a greeting, a\n    seller's welcome, asking the price, saying something is too expensive, asking for a final price, agreeing\n    to a deal, declining politely, and thank you -- each with its transliteration, Arabic script, and a short\n    usage note. Use for \"how do you say 'how much' in Arabic\", \"what's 'too expensive' in Arabic\", \"phrases for\n    bargaining in a souq\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"common_phrases_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/gold_souq_reference":{"post":{"operationId":"gold_souq_reference","summary":"How gold is traditionally sold in a souq: pricing by weight and karat, the common karats and their","description":"How gold is traditionally sold in a souq: pricing by weight and karat, the common karats and their\n    typical uses, the separate \"making charge\" for workmanship (the part that is usually negotiable), and\n    purity-mark hallmarks to look for. Explicitly does not, and never should be read to, state a current gold\n    price -- gold's underlying price is set by the international spot market and fluctuates daily. Use for \"how\n    is gold priced in a souq\", \"what's a making charge\", \"what karat is Gulf gold jewelry\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"gold_souq_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/spice_souq_reference":{"post":{"operationId":"spice_souq_reference","summary":"The spices, herbs and related goods commonly found in a traditional spice souq (cumin, cardamom,","description":"The spices, herbs and related goods commonly found in a traditional spice souq (cumin, cardamom,\n    saffron, sumac, za'atar, dried lime, incense and more), at the level of what's typically sold there. For\n    how these ingredients are actually used in specific dishes, cross-references the Matbakh (Cuisine)\n    connector's ingredient_info and dish_info tools. Use for \"what's sold in a spice souq\", \"what is loomi\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"spice_souq_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/textile_souq_reference":{"post":{"operationId":"textile_souq_reference","summary":"The fabrics and traditional garments commonly found in a textile souq (cotton, silk, wool, thobe and","description":"The fabrics and traditional garments commonly found in a textile souq (cotton, silk, wool, thobe and\n    abaya fabric, keffiyeh cloth, embroidery materials), at the level of what's typically sold there. For\n    garment-specific detail -- cuts, regional styles, embroidery meaning -- cross-references the Malabis\n    (Attire) connector's garment_info and fabric_and_craft_info tools. Use for \"what fabric is sold in a\n    textile souq\", \"where would I buy keffiyeh cloth\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"textile_souq_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/historical_context_info":{"post":{"operationId":"historical_context_info","summary":"The souq's historical role in trade and urban life, and general architecture patterns -- covered or","description":"The souq's historical role in trade and urban life, and general architecture patterns -- covered or\n    vaulted alleys, craft-by-street organization, and the khan/caravanserai concept of combined trade-and-\n    lodging buildings for traveling merchants. Optionally filter to one topic (trade, urban_life, architecture,\n    evolution/today). Use for \"why were souqs important historically\", \"what is a khan\", \"how are souqs laid\n    out architecturally\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"trade | urban_life | architecture | evolution. Omit to see all.","title":"Topic"}},"title":"historical_context_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/souq_glossary":{"post":{"operationId":"souq_glossary","summary":"Definitions of souq-related terms: souq/souk, khan, wikala, qaysariyya (covered arcade), dallal","description":"Definitions of souq-related terms: souq/souk, khan, wikala, qaysariyya (covered arcade), dallal\n    (auctioneer/crier), samsar (broker), sarraf (money-changer), attar (perfumer), mithqal and ratl (traditional\n    weight units), bakhoor (incense), hisba (historical market oversight), and caravanserai. Use for \"what does\n    khan mean\", \"what is a dallal\", \"what's a qaysariyya\".","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 (souq, khan, wikala, qaysariyya, dallal, samsar, sarraf, attar, mithqal, ratl, bakhoor, hisba, caravanserai); omit to list all.","title":"Term"}},"title":"souq_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/search":{"post":{"operationId":"search","summary":"Keyword search across every souq type, marketplace phrase, glossary term, and reference section (gold,","description":"Keyword search across every souq type, marketplace phrase, glossary term, and reference section (gold,\n    spice, textile, bargaining etiquette, historical context) in this connector. Use for \"find anything about\n    incense\", \"search for making charge\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"A word, phrase or concept to search for across souq types, phrases, and reference sections.","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}}}}