{"openapi":"3.1.0","info":{"title":"Gift Finder API","version":"0.1.0","description":"A category-level gift-idea generator: a hand-curated idea bank scored and filtered by occasion, relationship, budget and interests, plus occasion/relationship etiquette guides and a gift-etiquette reference. Never a live product database or a real product link.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://giftfinder.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/giftfinder/docs"},"termsOfService":"https://connectorbay.com/giftfinder/terms"},"servers":[{"url":"https://giftfinder.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/giftfinder/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/gift_ideas":{"post":{"operationId":"gift_ideas","summary":"The main gift-idea generator: scores a hand-curated bank of about 70 ideas against any combination of","description":"The main gift-idea generator: scores a hand-curated bank of about 70 ideas against any combination of\n    occasion, relationship, budget tier, and interests you give it, and returns the best-matching category-level\n    ideas — never a specific real product, brand, or price. Use for \"gift ideas for my coworker's birthday under\n    $30\", \"what should I get my partner who's into cooking and wine for our anniversary\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"occasion":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"e.g. birthday, holiday, housewarming, wedding, graduation, new_baby, anniversary, retirement, get_well, thank_you, just_because, coworker_exchange, secret_santa.","title":"Occasion"},"relationship":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"e.g. partner, close_friend, friend, family, parent, sibling, coworker, boss, acquaintance, neighbor, teacher, child.","title":"Relationship"},"budget_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"token (<$15), small ($15-40), medium ($40-100), large ($100-250), or splurge ($250+).","title":"Budget Tier"},"interests":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Any of: cooking, reading, fitness, gaming, gardening, tech, art_crafts, music, outdoors, coffee_tea, home_decor, fashion, wellness, kids, pets, sports, movies_tv, wine_cocktails, diy_tools, photography, travel, board_games, writing.","title":"Interests"},"count":{"default":6,"description":"How many ideas to return.","maximum":15,"minimum":1,"title":"Count","type":"integer"}},"title":"gift_ideasArguments","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_ideas_by_interest":{"post":{"operationId":"gift_ideas_by_interest","summary":"Every gift idea tagged to one interest, unfiltered by occasion or budget. Use for \"gift ideas for someone","description":"Every gift idea tagged to one interest, unfiltered by occasion or budget. Use for \"gift ideas for someone\n    into gardening\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"interest":{"description":"A single interest.","examples":["gardening"],"minLength":1,"title":"Interest","type":"string"},"count":{"default":10,"maximum":15,"minimum":1,"title":"Count","type":"integer"}},"required":["interest"],"title":"gift_ideas_by_interestArguments","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_ideas_by_budget":{"post":{"operationId":"gift_ideas_by_budget","summary":"Every gift idea tagged to one budget tier. Use for \"gift ideas under $40\", \"splurge gift ideas\".","description":"Every gift idea tagged to one budget tier. Use for \"gift ideas under $40\", \"splurge gift ideas\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"budget_tier":{"description":"token, small, medium, large, or splurge.","examples":["small"],"minLength":1,"title":"Budget Tier","type":"string"},"count":{"default":10,"maximum":15,"minimum":1,"title":"Count","type":"integer"}},"required":["budget_tier"],"title":"gift_ideas_by_budgetArguments","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/diy_experience_gift_ideas":{"post":{"operationId":"diy_experience_gift_ideas","summary":"Only non-physical gift ideas — experiences (a class, tickets, a spa day) and DIY/handmade gestures (a","description":"Only non-physical gift ideas — experiences (a class, tickets, a spa day) and DIY/handmade gestures (a\n    letter, a memory jar) — optionally narrowed by occasion and budget. Use for \"experience gift ideas for an\n    anniversary\", \"a DIY gift idea that doesn't cost much\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"occasion":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optionally narrow by occasion.","title":"Occasion"},"budget_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optionally narrow by budget tier.","title":"Budget Tier"},"count":{"default":6,"maximum":15,"minimum":1,"title":"Count","type":"integer"}},"title":"diy_experience_gift_ideasArguments","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":"Etiquette for one occasion: timing, appropriate tone, and what to watch out for. Use for \"what's the","description":"Etiquette for one occasion: timing, appropriate tone, and what to watch out for. Use for \"what's the\n    etiquette for a housewarming gift\", \"when should I give a graduation gift\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"occasion":{"description":"An occasion.","examples":["housewarming"],"minLength":1,"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/relationship_guide":{"post":{"operationId":"relationship_guide","summary":"Etiquette for one relationship type: what's appropriate, the typical budget norm, and what to avoid. Use","description":"Etiquette for one relationship type: what's appropriate, the typical budget norm, and what to avoid. Use\n    for \"what's appropriate to give a coworker\", \"how much should I spend on my boss's gift\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"relationship":{"description":"A relationship type.","examples":["coworker"],"minLength":1,"title":"Relationship","type":"string"}},"required":["relationship"],"title":"relationship_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/budget_tiers_list":{"post":{"operationId":"budget_tiers_list","summary":"The budget tiers this reference understands, with their dollar ranges. Use for \"what budget tiers do you","description":"The budget tiers this reference understands, with their dollar ranges. Use for \"what budget tiers do you\n    support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"budget_tiers_listArguments","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/interest_list":{"post":{"operationId":"interest_list","summary":"Every interest category this reference understands. Use for \"what interests can I filter gift ideas by\".","description":"Every interest category this reference understands. Use for \"what interests can I filter gift ideas by\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"interest_listArguments","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_etiquette_tips":{"post":{"operationId":"gift_etiquette_tips","summary":"General gift-giving etiquette: thank-you notes, gift receipts, regifting norms, White Elephant/Secret Santa","description":"General gift-giving etiquette: thank-you notes, gift receipts, regifting norms, White Elephant/Secret Santa\n    conventions, and politely declining or returning a gift. Use for \"is it okay to regift\", \"how soon should I\n    send a thank-you note\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"gift_etiquette_tipsArguments","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}}}}