{"openapi":"3.1.0","info":{"title":"Costumbre (Custom) API","version":"0.1.0","description":"A fully local Spanish social customs & etiquette guide: everyday customs, meal times, greetings, punctuality, gift-giving, business etiquette, regional variation, and a glossary.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://costumbre.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/costumbre/docs"},"termsOfService":"https://connectorbay.com/costumbre/terms"},"servers":[{"url":"https://costumbre.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/costumbre/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/custom_info":{"post":{"operationId":"custom_info","summary":"A single Spanish social custom's description and significance, plus a modern-day note where a once-common","description":"A single Spanish social custom's description and significance, plus a modern-day note where a once-common\n    practice (like the siesta) has genuinely shifted. Covers siesta, sobremesa, paseo, dos besos, Sunday family\n    lunch, tapeo, and late meal times. Use for \"what is sobremesa\", \"is the siesta still practiced\", \"what is\n    tapeo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A Spanish social custom's name, or a close alias.","examples":["siesta","sobremesa","paseo","dos besos","tapeo"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"custom_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/custom_search":{"post":{"operationId":"custom_search","summary":"Search Spanish social customs by keyword across their name, category, summary and description. Use for","description":"Search Spanish social customs by keyword across their name, category, summary and description. Use for\n    \"which customs involve eating\", \"find customs about greetings\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"A keyword to search across custom names, categories, summaries and descriptions.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"custom_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/meal_time_guide":{"post":{"operationId":"meal_time_guide","summary":"The typical Spanish meal schedule — breakfast, lunch (often 2-3pm), an afternoon merienda, and dinner","description":"The typical Spanish meal schedule — breakfast, lunch (often 2-3pm), an afternoon merienda, and dinner\n    (often 9-10pm or later) — contrasted with earlier northern-European/US mealtimes. A genuine, well-documented\n    cultural difference. Use for \"what time do people eat dinner in Spain\", \"when is lunch in Spain\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"meal_time_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/greeting_guide":{"post":{"operationId":"greeting_guide","summary":"Formal (handshake) vs. informal (dos besos) greeting conventions, who typically initiates, and a regional","description":"Formal (handshake) vs. informal (dos besos) greeting conventions, who typically initiates, and a regional\n    variation note. Pass a context to get just that one, or omit it for both. Use for \"how do you greet someone\n    in Spain\", \"do you shake hands or kiss in a Spanish business meeting\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"context":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Which greeting context to cover: 'formal'/'business' or 'informal'/'social'. Omit for both.","examples":["formal","informal","business","social"],"title":"Context"}},"title":"greeting_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/punctuality_norms":{"post":{"operationId":"punctuality_norms","summary":"General tendencies around social vs. business punctuality in Spain, with an explicit caveat that these","description":"General tendencies around social vs. business punctuality in Spain, with an explicit caveat that these\n    vary by region, generation and setting rather than being a fixed national trait. Use for \"are Spaniards\n    punctual\", \"is it okay to be late to a party in Spain\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"punctuality_normsArguments","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/gift_giving_etiquette":{"post":{"operationId":"gift_giving_etiquette","summary":"General Spanish gift-giving norms for home visits, celebrations and business contexts — what's common,","description":"General Spanish gift-giving norms for home visits, celebrations and business contexts — what's common,\n    what to avoid (like chrysanthemums), and how modest business gift-giving typically is. Use for \"what should\n    I bring to a Spanish dinner party\", \"is gift-giving common in Spanish business\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"gift_giving_etiquetteArguments","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/business_etiquette":{"post":{"operationId":"business_etiquette","summary":"General Spanish business etiquette — professional greeting customs, business-card and meeting norms,","description":"General Spanish business etiquette — professional greeting customs, business-card and meeting norms,\n    typical business-meal conventions, and the emphasis on relationship-building before deals move forward. Use\n    for \"what's business etiquette like in Spain\", \"how long do Spanish business lunches run\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"business_etiquetteArguments","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/regional_custom_variation":{"post":{"operationId":"regional_custom_variation","summary":"A Spanish region's overview and distinctive cultural/linguistic notes — Catalonia, the Basque Country","description":"A Spanish region's overview and distinctive cultural/linguistic notes — Catalonia, the Basque Country\n    (Euskadi), Andalusia, or Galicia. Regional and linguistic facts are described factually and respectfully;\n    where a region has a notable regional-identity or self-governance movement, that is stated as a fact of its\n    public life without taking any political position. Use for \"what's different about Catalonia\", \"tell me\n    about Basque culture\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"A Spanish autonomous region/community.","examples":["Catalonia","Basque Country","Andalusia","Galicia"],"minLength":1,"title":"Region","type":"string"}},"required":["region"],"title":"regional_custom_variationArguments","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/etiquette_glossary":{"post":{"operationId":"etiquette_glossary","summary":"Definitions of common Spanish social/etiquette terms (sobremesa, paseo, tapeo, siesta, propina, dos","description":"Definitions of common Spanish social/etiquette terms (sobremesa, paseo, tapeo, siesta, propina, dos\n    besos, and more). Use for \"what does sobremesa mean\", \"what's propina\".","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":"etiquette_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}}}}