{"openapi":"3.1.0","info":{"title":"Emoji API","version":"0.1.0","description":"A fully local emoji reference and search connector: search, exact lookup, category browsing, shortcode resolution both ways, skin-tone variants, a text-to-emoji translator, and mood/theme combos, all from bundled Unicode CLDR data.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://emoji.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/emoji/docs"},"termsOfService":"https://connectorbay.com/emoji/terms"},"servers":[{"url":"https://emoji.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/emoji/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/emoji_search":{"post":{"operationId":"emoji_search","summary":"Search all bundled emoji by name, keyword, shortcode, or category substring, ranked by","description":"Search all bundled emoji by name, keyword, shortcode, or category substring, ranked by\n    relevance. Use for \"find an emoji for birthday\", \"search emoji for cat\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Name, keyword, or category substring to search for.","examples":["party","dog","heart","flag"],"minLength":1,"title":"Query","type":"string"},"limit":{"default":20,"description":"Maximum number of results.","maximum":100,"minimum":1,"title":"Limit","type":"integer"}},"required":["query"],"title":"emoji_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/emoji_lookup":{"post":{"operationId":"emoji_lookup","summary":"Full detail for one emoji — name, codepoint, category, subgroup, keywords, shortcode, and","description":"Full detail for one emoji — name, codepoint, category, subgroup, keywords, shortcode, and\n    whether it supports skin-tone modifiers — looked up by the literal character, its name, or a\n    shortcode. Use for \"what is 🥲 called\", \"look up the emoji named shrug\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"emoji_or_name":{"description":"The literal emoji character, its official name, or a shortcode.","examples":["😀","grinning face","joy",":thumbsup:"],"minLength":1,"title":"Emoji Or Name","type":"string"}},"required":["emoji_or_name"],"title":"emoji_lookupArguments","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/emoji_by_category":{"post":{"operationId":"emoji_by_category","summary":"Every emoji in one Unicode category/group. Use for \"list all food emoji\", \"show me every","description":"Every emoji in one Unicode category/group. Use for \"list all food emoji\", \"show me every\n    flag emoji\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"A Unicode emoji group.","examples":["Smileys & Emotion","Animals & Nature","Food & Drink","Activities","Travel & Places","Objects","Symbols","Flags","People & Body"],"minLength":1,"title":"Category","type":"string"}},"required":["category"],"title":"emoji_by_categoryArguments","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/category_list":{"post":{"operationId":"category_list","summary":"Every available emoji category with how many emoji are in each. Use for \"what emoji","description":"Every available emoji category with how many emoji are in each. Use for \"what emoji\n    categories are there\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"category_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/random_emoji":{"post":{"operationId":"random_emoji","summary":"One random emoji, optionally scoped to a category. Use for \"give me a random emoji\", \"pick a","description":"One random emoji, optionally scoped to a category. Use for \"give me a random emoji\", \"pick a\n    random animal emoji\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optionally restrict to one category (see category_list).","title":"Category"}},"title":"random_emojiArguments","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/shortcode_lookup":{"post":{"operationId":"shortcode_lookup","summary":"Resolve a GitHub/Slack-style `:shortcode:` to its emoji and full detail. Use for \"what emoji","description":"Resolve a GitHub/Slack-style `:shortcode:` to its emoji and full detail. Use for \"what emoji\n    is :joy:\", \"what does :fire: look like\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shortcode":{"description":"A GitHub/Slack-style shortcode, with or without colons.","examples":[":joy:","thumbsup",":+1:","fire"],"minLength":1,"title":"Shortcode","type":"string"}},"required":["shortcode"],"title":"shortcode_lookupArguments","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/emoji_to_shortcode":{"post":{"operationId":"emoji_to_shortcode","summary":"The reverse of shortcode_lookup: given a literal emoji character, its primary and alternate","description":"The reverse of shortcode_lookup: given a literal emoji character, its primary and alternate\n    GitHub/Slack-style shortcodes. Use for \"what's the shortcode for 🔥\", \"how do I type this emoji\n    on Slack\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"emoji":{"description":"The literal emoji character.","examples":["😂","👍","🔥"],"minLength":1,"title":"Emoji","type":"string"}},"required":["emoji"],"title":"emoji_to_shortcodeArguments","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/skin_tone_variants":{"post":{"operationId":"skin_tone_variants","summary":"For emoji that support Fitzpatrick skin-tone modifiers, the actual variant characters from","description":"For emoji that support Fitzpatrick skin-tone modifiers, the actual variant characters from\n    light through dark. `skin_tone_capable: false` if the emoji has no tone variants. Use for\n    \"does the wave emoji have skin tones\", \"show me the thumbs up in different skin tones\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"emoji":{"description":"The base emoji character, its name, or a shortcode.","examples":["👋","waving hand","thumbsup"],"minLength":1,"title":"Emoji","type":"string"}},"required":["emoji"],"title":"skin_tone_variantsArguments","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/text_to_emoji":{"post":{"operationId":"text_to_emoji","summary":"A fun, best-effort word-by-word emoji translator for a short phrase, using this connector's","description":"A fun, best-effort word-by-word emoji translator for a short phrase, using this connector's\n    own keyword index — no external API. Words with no good match are skipped. Use for \"translate\n    this sentence into emoji\", \"turn this into emoji\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"text":{"description":"A short phrase or sentence to translate.","examples":["I love pizza and dogs","happy birthday to you"],"maxLength":500,"minLength":1,"title":"Text","type":"string"}},"required":["text"],"title":"text_to_emojiArguments","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/emoji_combo_search":{"post":{"operationId":"emoji_combo_search","summary":"A small curated set of emoji (3-6) that together represent a mood or theme — birthday,","description":"A small curated set of emoji (3-6) that together represent a mood or theme — birthday,\n    celebration, sad, love, congratulations, and about 15 more. Use for \"emoji for a birthday\n    message\", \"give me some sad emoji\", \"emoji combo for a party invite\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mood_or_theme":{"description":"A mood or theme.","examples":["birthday","celebration","sad","love","halloween"],"minLength":1,"title":"Mood Or Theme","type":"string"}},"required":["mood_or_theme"],"title":"emoji_combo_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}}}}