How do I search for emoji by name or slug?

Call GET /emoji/v1/search with a q parameter. The match is case-insensitive and partial, applied against both the emoji name and its slug — so q=grin will return grinning_face, grinning_face_with_big_eyes, and more. You can optionally scope results to a single Unicode group with the group parameter and cap the number of results with limit (1-200, default 50). An empty q or an invalid limit returns a 400 error; an unknown group simply returns no results.

What is the difference between lookup by emoji and by slug?

The GET /emoji/v1/lookup endpoint resolves the full record for a single emoji. You can provide either the exact emoji character via the emoji parameter (URL-encoded) or a slug like grinning_face via the slug parameter. At least one is required. If you supply both, the emoji character takes precedence. If neither is provided you get a 400, and if no emoji matches you get a 404 with an explicit error message.

How does the random endpoint work?

GET /emoji/v1/random returns random emoji using the count parameter (1-50, default 1). Sampling is done without replacement, so you will never get duplicate emoji within a single response, and the selection varies on every call. You can also pass an optional case-insensitive group filter to draw only from a specific category, such as group=Food & Drink. A count outside the 1-50 range returns a 400 error; an unknown group simply returns no results. Random results are never cached.

What are codepoints and why are they included?

The codepoints field is an array of Unicode codepoint strings in U+XXXX form that make up the emoji. Many emoji are not a single codepoint — they may combine a base character with a variation selector (like U+FE0F) or join multiple codepoints with a zero-width joiner (ZWJ). The API precomputes and correctly expands these sequences so you can reconstruct, analyze, or compare emoji precisely without parsing the raw string yourself.

How fast is the API and how is it hosted?

The entire emoji dataset is bundled into a Cloudflare Worker and served from memory at the edge, so there are no upstream calls or third-party hops. Typical compute time is well under a millisecond, and latency is dominated by the network round-trip to the nearest of Cloudflare's 300+ edge locations. This makes the API ideal for high-throughput autocomplete and latency-sensitive UIs. Authentication is a simple apikey query parameter on every request.

Search, look up, and randomize ~1,914 emoji at the edge

Emoji API

The Emoji API is a blazing-fast, fully self-contained emoji metadata service. It bundles nearly 1,914 emoji directly into a Cloudflare Worker, so every request is served from memory at the edge with no upstream calls, no rate-limit surprises, and no flaky third parties.

Each emoji is enriched with its name, URL-friendly slug, Unicode group, skin-tone support flag, the Unicode version it was introduced in, and precomputed codepoints — correctly handling multi-codepoint sequences like variation selectors and ZWJ joins. Ideal for emoji pickers, chat products, content pipelines, and any latency-sensitive UI.

Get a free API key Read the docs

Free tier included, no credit card required. One key works across every API.

Free calls / month: 1,000
Emoji Bundled: 1,914
Compute Time: <1ms
Endpoints: 4

Get your free API key

1,000 free calls on the free plan

Key features

Partial, case-insensitive search by name or slug
Exact lookup by emoji character or slug
Group index with live per-group counts
Random sampling without replacement, varying per call
Precomputed codepoints with ZWJ and variation selector support
Skin-tone support flag and Unicode version metadata
Fully bundled dataset served from the edge — no upstream calls

Built for

Emoji pickers and autocomplete widgets
Chat and messaging product features
Content-moderation and parsing pipelines
Trivia games and educational apps
Mapping slugs like grinning_face to real emoji
Slack/Discord bot emoji integrations
Localization and Unicode tooling
Random emoji generators and creative apps

MCP · for your agent

Hand the Emoji API to your agent

Connect Claude, Cursor or any MCP client once, then ask in plain words. Your agent finds this API, reads its docs and makes the call: 1 credit per call, the same as REST, from your team's balance.

Connect your agent

Pick emoji for release notes

“Suggest emoji for our release notes headings: new features, bug fixes, performance and security.”

list_apis · get_api_docsfree

api_request GET /emoji/v1/search?q=rocket&limit=5 1 cr

A matching emoji for each heading, with names and codepoints, ready to paste.

Render emoji codes from a chat export

“Our chat export shows codes like :party_popper: and :thumbs_up: instead of emoji. Convert them to the real characters.”

list_apis · get_api_docsfree

api_request GET /emoji/v1/lookup?slug=party_popper 1 cr

The emoji character, name and codepoints for each code, so the export renders properly.

Seed a random emoji picker

“Give me 5 random emoji from the Activities group for our loading screen. A different set each time, please.”

list_apis · get_api_docsfree

api_request GET /emoji/v1/random?count=5&group=Activities 1 cr

Five random Activities emoji with names; every call returns a fresh set.

$ claude mcp add --transport http apicodex https://mcp.apicodex.io

Illustrative asks; the calls and prices are real. Claude, Cursor, VS Code and Windsurf setup: mcp.apicodex.io

Try it

Build the request for your data

Edit the parameters below and see the exact request and curl command you'd send. No key required to preview.

GET /emoji/v1/search

Open in Playground

Parameters

q

limit

apikey

Request · HTTP

GET /emoji/v1/search?q=grin&limit=2&apikey=YOUR_KEY HTTP/1.1
Host: api.apicodex.io

Response · JSON 200 OK

{
"query": "grin",
"count": 2,
"limit": 2,
"results": [
  {
    "char": "😀",
    "name": "grinning face",
    "slug": "grinning_face",
    "group": "Smileys & Emotion",
    "skin_tone_support": false,
    "unicode_version": "1.0",
    "codepoints": ["U+1F600"]
  },
  {
    "char": "😃",
    "name": "grinning face with big eyes",
    "slug": "grinning_face_with_big_eyes",
    "group": "Smileys & Emotion",
    "skin_tone_support": false,
    "unicode_version": "0.6",
    "codepoints": ["U+1F603"]
  }
]
}

Run it with your key

Documentation

Emoji API Documentation

The Emoji API bundles ~1,914 emoji directly at the edge. It offers four clean endpoints: partial search by name or slug (with optional group filtering), exact lookup by character or slug, a groups index with live counts, and a random sampler that draws without replacement and varies on every call.

Base URL

url

https://api.apicodex.io/emoji

Authentication

Authenticate your requests by passing your API key as the apikey query parameter on every call:

headers

https://api.apicodex.io/emoji/v1/search?q=grin&apikey=YOUR_KEY

Request and response

Illustrative values. Confirm current endpoint behavior, quotas, and data freshness in the API documentation before production use.

request · http

GET /emoji/v1/search?q=grin&limit=2&apikey=YOUR_KEY HTTP/1.1
Host: api.apicodex.io

response · json

{
"query": "grin",
"count": 2,
"limit": 2,
"results": [
  {
    "char": "😀",
    "name": "grinning face",
    "slug": "grinning_face",
    "group": "Smileys & Emotion",
    "skin_tone_support": false,
    "unicode_version": "1.0",
    "codepoints": ["U+1F600"]
  },
  {
    "char": "😃",
    "name": "grinning face with big eyes",
    "slug": "grinning_face_with_big_eyes",
    "group": "Smileys & Emotion",
    "skin_tone_support": false,
    "unicode_version": "0.6",
    "codepoints": ["U+1F603"]
  }
]
}

Code examples

cURL

curl --request GET \
  --url 'https://api.apicodex.io/emoji/v1/search?q=grin&limit=2&apikey=YOUR_KEY'

JavaScript/Node.js

const params = new URLSearchParams({
  q: 'grin',
  limit: '2',
  apikey: 'YOUR_KEY'
});

const response = await fetch(
  `https://api.apicodex.io/emoji/v1/search?${params}`
);

const data = await response.json();
console.log(data.results);

Python

import requests

url = "https://api.apicodex.io/emoji/v1/search"

querystring = {"q": "grin", "limit": "2", "apikey": "YOUR_KEY"}

response = requests.get(url, params=querystring)

print(response.json())

Endpoints

GET /v1/search

Case-insensitive partial match on emoji name OR slug, with an optional exact group filter. Results capped at limit.

/v1/search?q=grin&limit=2&apikey=YOUR_KEY

GET /v1/lookup

Resolve full details for a single emoji by exact character (emoji) OR by slug. At least one is required; emoji takes precedence if both are supplied.

/v1/lookup?slug=smiling_face&apikey=YOUR_KEY

GET /v1/groups

List distinct emoji groups with per-group counts and the dataset total.

/v1/groups?apikey=YOUR_KEY

GET /v1/random

Return random emoji (1-50), sampled without replacement and varying per call. Supports an optional group filter.

/v1/random?count=1&group=Food%20%26%20Drink&apikey=YOUR_KEY

Parameters

Required parameters

q Non-empty search string matched against name and slug (required for /v1/search).

Optional parameters

group Optional case-insensitive group name filter, e.g. "Smileys & Emotion" (search and random).
limit Maximum number of search results, 1-200 (default 50).
emoji The exact emoji character to resolve, URL-encoded (lookup).
slug The emoji slug to resolve, e.g. grinning_face (lookup).
count Number of random emoji to return, 1-50 (default 1) for /v1/random.

Pricing

Emoji API Pricing

This API costs 1 credit per request. Credits are shared across every API on your plan.

Estimate your monthly cost

Drag the slider to match your expected request volume. We'll recommend the cheapest plan that covers it.

Requests per month 10,000

Recommended plan

Starter

$29.99 /month

Credits used

Credits included

Cost per 1K requests

Choose Starter

Free

1,000 credits · ~1,000 requests/mo · 2 rps

All APIs included
No credit card required
Full documentation and examples
MCP server for your AI agents
Up to 5 active API keys

Start for free

Starter

Popular

$29.99 /month

50,000 credits · ~50,000 requests/mo · 10 rps

All APIs included
Email support
Usage dashboard and analytics
MCP server for your AI agents
Up to 5 active API keys

Start with Starter

Pro

$99.99 /month

250,000 credits · ~250,000 requests/mo · 25 rps

All APIs included
Priority support
MCP server for your AI agents
Up to 5 active API keys

Start with Pro

FAQ

Emoji API

Key features

Built for

Hand the Emoji API to your agent

Pick emoji for release notes

Render emoji codes from a chat export

Seed a random emoji picker

Build the request for your data

Emoji API Documentation

Base URL

Authentication

Request and response

Code examples

Endpoints

GET /v1/search

GET /v1/lookup

GET /v1/groups

GET /v1/random

Parameters

Required parameters

Optional parameters

Emoji API Pricing

Free

Starter

Pro

Need a different plan?

Frequently asked questions

Related APIs