Emoji API Docs Pro mode

Read-only API with server-side search & pagination. No bulk dump is exposed to prevent cloning. Responses include ETag and public caching headers.

Base URL: /api

Authentication

Public access is allowed (Free tier) and daily-capped (~30 distinct page‑1 queries per IP). Pro unlocks higher limits and fields using a license key from Gumroad or Mayar.

Authorization: Bearer YOUR_LICENSE_KEY

?key=YOUR_LICENSE_KEY

Endpoints

Available endpoints:

/api/emojis — search & paginate
/api/emoji?slug=<slug> — single emoji (query)
/api/emoji/<slug> — single emoji (pretty URL)
/api/categories — categories → subcategories

GET `/api/emojis`

Search and paginate emojis.

Query Param	Type	Description	Default
`q` / `query`	string	Search across name, category, subcategory, aliases, shortcodes, and EN/ID keywords. Multi‑word terms use AND match.	empty
`category`	string	Filter by top-level category (exact label, e.g. `Smileys & Emotion`).	`all`
`subcategory`	string	Filter by subcategory (canonical slug, e.g. `face-smiling`).	empty
`page`	number	1-based page index.	`1`
`limit`	number	Items per page (max 50).	`50`

curl "/api/emojis?q=love&category=Smileys%20%26%20Emotion&limit=50&page=1"

const res = await fetch('/api/emojis?q=love&category=Smileys%20%26%20Emotion&limit=50&page=1');
        const data = await res.json();
        console.log(data.items);

{
        "total": 1234,
        "page": 1,
        "limit": 50,
        "items": [
            { "emoji": "😀", "name": "grinning face", "category": "Smileys & Emotion", "subcategory": "face-smiling" },
            { "emoji": "😃", "name": "grinning face with big eyes", "category": "Smileys & Emotion", "subcategory": "face-smiling" }
        ]
        }

Free: compact payload (no full keyword lists, variants only when needed).
Pro / Whitelist: may include keywords_en (trimmed), related, and variants for skin tones where applicable.

GET `/api/emoji` and `/api/emoji/<slug>`

Return a single emoji by slug. Both query and pretty URL styles are supported.

curl "/api/emoji/smiling-face-with-smiling-eyes"

const res = await fetch('/api/emoji/smiling-face-with-smiling-eyes');
        const data = await res.json();
        console.log(data);

{
        "emoji": "😊",
        "name": "Smiling Face with Smiling Eyes",
        "slug": "smiling-face-with-smiling-eyes",
        "category": "Smileys & Emotion",
        "subcategory": "face-smiling",
        "unified": "U+1F60A",
        "supports_skin_tone": false,
        "summary": "Friendly, warm smile often used to show thanks or appreciation."
        }

GET `/api/categories`

List categories and their subcategories.

curl "/api/categories"

const cats = await (await fetch('/api/categories')).json();
        console.log(Object.keys(cats));

{
        "Smileys & Emotion": ["face-smiling", "face-affection", "..."],
        "People & Body": ["hand-fingers-open", "..."]
        }

Try it

Call the API directly from this page. For demo purposes, the request is limited to page=1 and limit=10.

Keyword

Errors & Caching

400 — invalid_request
401 — invalid_key
404 — not_found
429 — rate_limited

Responses may include ETag and Cache-Control: public, max-age=300. Use conditional requests to get 304 Not Modified when content hasn’t changed.