Emoji Score

API Documentation

The Emoji Score REST API provides programmatic access to emoji scoring, inventory search, timeline data, and proposal submission. All endpoints accept and return JSON. No authentication required for read operations.

Base URL
https://emoji.platphormnews.com

OpenAPI 3.1 spec aligned. v1 endpoints under /api/v1/ follow the USL Emoji Validation specification. Download OpenAPI spec (YAML)

Sections
SystemEmoji ScoringInventory & DatasetsExplorer & UtilitiesTimeline & RecentProposalsMCP Integration

System

Health checks and system status.

GET
/api/v1/health

Health check

Returns server status, current time, uptime, version, network, and MCP registry info. No authentication required.

Response

{
  "status": "ok",
  "time": "2026-02-14T12:00:00.000Z",
  "uptime_seconds": 3600,
  "version": "17.0",
  "name": "Emoji Score",
  "network": "platphormnews.com",
  "url": "https://emoji.platphormnews.com",
  "mcp_registry": "https://mcp.platphormnews.com/api/mcp",
  "emoji_count": 3900
}
200OK

Emoji Scoring

Score emoji characters and concepts against the local database.

GET
/api/emoji/score

Score an emoji character

Scores a single emoji character for popularity and relevance. Uses the local Unicode database as the primary source, falling back to emoji-api.com for coverage of skin-tone variants and other sequences not in the local DB.

Parameters

NameInTypeRequiredDescription
emojiquerystringYesThe emoji character to score (URL-encoded).

Response

{
  "emoji": "\ud83d\ude02",
  "unicodeName": "face with tears of joy",
  "codePoint": "1F602",
  "group": "Smileys & Emotion",
  "subGroup": "face-smiling",
  "version": "1.0",
  "overall": 88,
  "breakdown": {
    "category": { "score": 38, "max": 40, "label": "Category Popularity" },
    "versatility": { "score": 25, "max": 25, "label": "Versatility" },
    "complexity": { "score": 20, "max": 20, "label": "Platform Support" },
    "specificity": { "score": 15, "max": 15, "label": "Semantic Richness" }
  },
  "tier": "Highly Popular",
  "tierColor": "#22c55e",
  "summary": "..."
}
200Score returned.
400Missing emoji parameter.
404Emoji not found in any source.
POST
/api/v1/emoji/score

Score an emoji concept proposal (stateless)

Scores a concept proposal without storing it. Runs schema validation, gate checks, feature scoring, and returns recommendations. Follows the USL Emoji Validation OpenAPI spec.

Request Body

{
  "type": "score_request",
  "created_at": "2026-02-14T12:00:00Z",
  "proposal": {
    "concept_name": "Yawning Face",
    "short_name": "yawning_face",
    "category": "smileys_emotion",
    "concept_description": "A face with a wide open mouth...",
    "keywords": ["tired", "sleepy", "bored", "exhausted"],
    "usage_examples": [
      { "text": "I'm so tired after that meeting" },
      { "text": "Can't stop yawning during lectures" }
    ],
    "nearest_existing_emoji": [
      { "emoji": "\ud83d\ude34", "reason": "Sleeping face" }
    ],
    "visual_spec": {
      "description": "A yellow face with closed eyes..."
    }
  }
}

Response

{
  "type": "score_response",
  "created_at": "2026-02-14T12:00:00.000Z",
  "proposal_short_name": "yawning_face",
  "score_0_100": 68,
  "p_accept": 0.68,
  "confidence_interval": { "low": 0.53, "high": 0.83 },
  "breakdown": {
    "demand": 0.3, "universality": 0.4,
    "semantic_gap": 0.8, "longevity": 0.7,
    "visual_distinctiveness": 0.6,
    "neutrality": 0.7, "completeness": 0.5
  },
  "gates": [
    { "name": "minimum_quality", "status": "pass", "details": "..." },
    { "name": "redundancy_check", "status": "pass", "details": "..." }
  ],
  "nearest_existing_emoji_ranked": [...],
  "top_drivers": [...],
  "recommendations": [
    "Add more usage examples to strengthen demand signal."
  ]
}
200Score response with breakdown and recommendations.
400Invalid request body or missing required fields.

Inventory & Datasets

Search the canonical emoji inventory, check codepoint existence, and lookup keywords.

GET
/api/v1/datasets/emoji/inventory/search

Search emoji inventory (local + optional external)

Searches the canonical emoji inventory using Unicode data files. Optionally augments results using emoji-api.com if include_external=true.

Parameters

NameInTypeRequiredDescription
qquerystringYesSearch query.
limitqueryintegerNoMax results (1-50, default 20).
include_externalquerybooleanNoInclude emoji-api.com results (default false).

Response

{
  "items": [
    {
      "sequence": "1F525",
      "codepoints": ["1F525"],
      "is_emoji": true,
      "properties": ["Emoji_Presentation"],
      "cldr_short_name": "fire",
      "keywords": ["fire", "flame", "hot"],
      "sources": ["local_ucd"]
    }
  ]
}
200Search results.
400Missing or invalid query.
POST
/api/v1/datasets/emoji/inventory/exists

Check if a codepoint sequence exists

Checks the Unicode emoji inventory for existence of a codepoint or sequence and returns the canonical record if found.

Request Body

{
  "sequence": "1F600"
}

Response

{
  "exists": true,
  "record": {
    "sequence": "1F600",
    "codepoints": ["1F600"],
    "is_emoji": true,
    "properties": ["Emoji_Presentation"],
    "cldr_short_name": "grinning face",
    "keywords": ["grinning", "face", "happy"],
    "sources": ["local_ucd"]
  }
}
200Exists result with record if found.
400Invalid sequence format.
GET
/api/v1/datasets/emoji/keywords/search

Search keywords (Emoji List v17.0)

Convenience endpoint for UI keyword lookup from Emoji List v17.0. Non-authoritative; use Unicode data files for production.

Parameters

NameInTypeRequiredDescription
qquerystringYesKeyword search query.
limitqueryintegerNoMax results (1-50, default 20).

Response

{
  "source": {
    "note": "Derived from Emoji List v17.0 for UI convenience."
  },
  "items": [
    {
      "code": "U+1F525",
      "cldr_short_name": "fire",
      "matched": ["fire", "flame"]
    }
  ]
}
200Keyword search results.
400Missing query.
GET
/api/v1/emoji/from-description

Get emoji from natural-language description

Find emoji that match a natural-language description. Designed for MCP tool ingestion — other AI agents and tools can call this endpoint to ingest emoji based on what they describe.

Parameters

NameInTypeRequiredDescription
descriptionquerystringYesNatural-language description (e.g. 'a happy face', 'animals that fly').
limitqueryintegerNoMax results (1-50, default 10).
include_scorequerybooleanNoInclude popularity score for each emoji (default false).

Response

{
  "description": "a happy face",
  "count": 3,
  "emojis": [
    {
      "character": "😀",
      "name": "grinning face",
      "group": "Smileys & Emotion",
      "subGroup": "face-smiling",
      "version": "1.0",
      "codePoints": "1F600",
      "keywords": ["grinning", "face"],
      "matchedTerms": ["happy", "face"]
    }
  ]
}
200Matched emoji results.
400Missing or too-short description.

Explorer & Utilities

Browse emoji by group, version, and text search. Auto-suggest for typeahead.

GET
/api/emoji/all

Get full emoji dataset

Returns the complete Unicode emoji dataset (3,900+ entries) in compact JSON form. Designed for client-side caching and offline use. Clients should store the response keyed by the returned version field.

Response

{
  "version": "17.0",
  "count": 3944,
  "source": "unicode.org/Public/emoji/latest/emoji-test.txt",
  "generatedAt": "2026-02-14T12:00:00.000Z",
  "emojis": [
    {
      "c": "\ud83d\ude00",
      "n": "grinning face",
      "cp": "1F600",
      "g": "Smileys & Emotion",
      "sg": "face-smiling",
      "v": "1.0",
      "z": 0,
      "cpc": 1
    }
  ]
}
200Full emoji dataset.
500Failed to load emoji database.
GET
/api/emoji/categories

Get emoji categories

Returns all Unicode emoji category groups with emoji counts and sample characters. Uses the local database as primary source with emoji-api.com as fallback.

Response

[
  {
    "slug": "smileys-emotion",
    "name": "Smileys & Emotion",
    "count": 185,
    "sample": ["\ud83d\ude00", "\ud83d\ude02", "\ud83d\ude0d", "\ud83e\udd29", "\ud83e\udd23"]
  },
  {
    "slug": "animals-nature",
    "name": "Animals & Nature",
    "count": 160,
    "sample": ["\ud83d\udc36", "\ud83d\udc31", "\ud83d\udc2d", "\ud83d\udc39", "\ud83d\udc30"]
  }
]
200Array of category objects.
500Failed to fetch categories.
GET
/api/emoji/suggest

Auto-suggest emoji (typeahead)

Returns emoji suggestions matching a partial text query. Designed for real-time typeahead in search bars. Debounce recommended at 150-300ms.

Parameters

NameInTypeRequiredDescription
qquerystringYesPartial text query (minimum 1 character).
limitqueryintegerNoMax suggestions (1-20, default 8).

Response

[
  { "character": "\ud83d\udd25", "name": "fire", "group": "Travel & Places" },
  { "character": "\ud83e\udde8", "name": "firecracker", "group": "Activities" }
]
200Array of suggestions (may be empty).
GET
/api/emoji/local-search

Search local emoji database

Full-text search against the local Unicode emoji database. Supports search by name, keyword, group, or codepoint. Returns scored results ranked by relevance.

Parameters

NameInTypeRequiredDescription
qquerystringNoSearch text.
groupquerystringNoFilter by group name.
limitqueryintegerNoMax results (default 50).

Response

{
  "emojis": [
    {
      "character": "\ud83d\ude00",
      "name": "grinning face",
      "codePoints": "1F600",
      "group": "Smileys & Emotion",
      "subGroup": "face-smiling",
      "version": "1.0",
      "isZwj": false,
      "codePointCount": 1,
      "keywords": ["grinning", "face", "happy"]
    }
  ],
  "query": "grinning"
}
200Search results with metadata.
GET
/api/emoji/search

Search emoji (external API with local fallback)

Searches emoji-api.com first, then falls back to the local database if the external API is unavailable. Returns normalized results from either source.

Parameters

NameInTypeRequiredDescription
qquerystringYesSearch query (minimum 2 characters).

Response

[
  {
    "slug": "grinning-face",
    "character": "\ud83d\ude00",
    "unicodeName": "grinning face",
    "codePoint": "1F600",
    "group": "Smileys & Emotion",
    "subGroup": "face-smiling"
  }
]
200Array of search results.
400Query too short.

Timeline & Recent

Emoji additions by year and recently added emoji.

GET
/api/emoji/timeline

Get emoji timeline by year

Returns all emoji grouped by the year they were added, with version labels, counts, and sample characters for each year from 2010 to present.

Response

{
  "totalEmoji": 3944,
  "version": "17.0",
  "timeline": [
    {
      "year": 2010,
      "versions": ["0.6", "0.7"],
      "count": 722,
      "samples": ["\ud83d\ude00", "\u2764\ufe0f", "..."]
    },
    { "year": 2015, "versions": ["1.0", "2.0"], "count": 475, "samples": [...] },
    ...
  ]
}
200Timeline data.
GET
/api/emoji/recent

Get recently added emoji

Returns emoji added in Unicode Emoji 16.0 (2024) and 17.0 (2025), grouped by version.

Response

{
  "totalRecent": 246,
  "grouped": {
    "17.0": [
      { "character": "...", "name": "...", "group": "...", "subGroup": "..." }
    ],
    "16.0": [...]
  }
}
200Recent emoji grouped by version.

Proposals

Submit and score new emoji proposals.

POST
/api/score

Score an emoji proposal (full form)

Submit a complete emoji proposal with all 7 scoring factors. Returns a weighted score, tier classification, and factor-by-factor breakdown with suggestions.

Request Body

{
  "emojiName": "Yawning Face",
  "shortDescription": "A face with a wide open mouth...",
  "category": "smileys-emotion",
  "keywords": "tired, sleepy, bored",
  "justification": "There is no existing emoji that...",
  "existingAlternatives": "None directly",
  "targetAudience": "Young adults on social media",
  "culturalContext": "Universally understood...",
  "searchEvidence": "Google Trends shows...",
  "usageScenarios": "Texting friends about being tired...",
  "imageDescription": "A simple yellow face with..."
}

Response

{
  "id": "evse-1700000000-abc1234",
  "proposal": { ... },
  "factors": [
    {
      "key": "demand",
      "rawScore": 75,
      "weightedScore": 15,
      "reasoning": "...",
      "suggestions": ["..."]
    }
  ],
  "totalWeightedScore": 68,
  "tier": "Strong",
  "tierColor": "#3b82f6",
  "overallSummary": "...",
  "timestamp": "2026-02-14T..."
}
200Proposal scored successfully.
400Missing required fields.
GET
/api/factors

Get scoring factor definitions

Returns the scoring factor definitions (weights, labels, max scores) and tier configuration used by the scoring engine.

Response

{
  "factors": [
    {
      "key": "demand",
      "label": "Expected Usage (Demand)",
      "weight": 0.20,
      "maxScore": 100,
      "description": "..."
    }
  ],
  "tiers": [
    { "tier": "Excellent", "min": 80, "max": 100, ... },
    { "tier": "Strong", "min": 65, "max": 79, ... }
  ]
}
200Factor and tier configuration.

MCP Integration

Emoji Score is discoverable by AI agents via the PlatPhorm MCP Registry. The MCP tools manifest lists all available tools with typed input schemas so any MCP-compatible client can invoke them without manual configuration.

Discovery Endpoints
Static manifestGET https://emoji.platphormnews.com/.well-known/mcp.json
Dynamic manifest (runtime URL)GET https://emoji.platphormnews.com/api/mcp
Registry link tag (in <head>)<link rel="mcp-registry" href="https://mcp.platphormnews.com/api/mcp" />
LLM discovery filesGET https://emoji.platphormnews.com/llms.txtGET https://emoji.platphormnews.com/llms-full.txt
MCP Client EndpointsGET https://emoji.platphormnews.com/api/v1/mcp/tools — List all tools (network format)POST https://emoji.platphormnews.com/api/v1/mcp/register — Register tools with registryGET https://emoji.platphormnews.com/api/v1/mcp/discover — Discover remote tools
Available MCP Tools
Tool NameMethodEndpointDescription
score_emoji
GET
/api/emoji/scoreScore a Unicode emoji character.
score_proposal
POST
/api/v1/emoji/scoreScore a new emoji concept proposal (stateless).
search_emoji
GET
/api/emoji/local-searchFull-text search of the local emoji database.
suggest_emoji
GET
/api/emoji/suggestTypeahead suggestions for a partial query.
get_timeline
GET
/api/emoji/timelineEmoji additions grouped by year.
get_recent_emoji
GET
/api/emoji/recentRecently added emoji (v16.0 + v17.0).
inventory_search
GET
/api/v1/datasets/emoji/inventory/searchSearch the canonical Unicode inventory.
inventory_exists
POST
/api/v1/datasets/emoji/inventory/existsCheck codepoint/sequence existence.
get_emoji_from_description
GET
/api/v1/emoji/from-descriptionFind emoji matching a natural-language description.
health_check
GET
/api/v1/healthServer health and uptime.
Data Sources & Fallback Strategy

Primary: Local Unicode emoji database parsed from emoji-test.txt and emoji-zwj-sequences.txt. Contains 3,900+ fully-qualified emoji with groups, versions, and keyword indices.

Fallback: Open Emoji API (emoji-api.com) used as secondary source for skin-tone variants, regional flags, and any characters not yet in the local database. Cached with 1-hour TTL.

Runtime Bootstrap: If local JSON files are unavailable at startup, the database is fetched directly from unicode.org and cached in memory for the server lifetime.

Rate Limiting & Notes
  • - All read endpoints are publicly accessible with no authentication required.
  • - v1 endpoints follow the USL Emoji Validation OpenAPI 3.1 specification.
  • - The local database is the primary data source; external APIs are used only as fallback.
  • - Scoring is deterministic for the same input -- no randomness involved.
  • - Suggest endpoint is designed for typeahead; debounce at 150-300ms recommended.
  • - For production integrations, prefer the /api/v1/ endpoints.