openapi: 3.1.0
info:
  title: Emoji Favicon API
  description: Free emoji favicon, badge, avatar, banner, and search service. 3,773 emojis, 11,550 keywords.
  version: 6.0.0
  contact:
    email: contact@findutils.com
    url: https://emoji.findutils.com
servers:
  - url: https://emoji.findutils.com
paths:
  /api/search:
    get:
      operationId: searchEmojis
      summary: Search emojis by keyword
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
          description: Search query (name or keyword, max 100 chars)
      responses:
        '200':
          description: Matching emojis with scores
          content:
            application/json:
              schema:
                type: object
                properties:
                  query: { type: string }
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        emoji: { type: string }
                        name: { type: string }
                        slug: { type: string }
                        category: { type: string }
                        url: { type: string }
  /api/suggest:
    get:
      operationId: suggestEmoji
      summary: Suggest the best emoji for a website or topic
      parameters:
        - name: url
          in: query
          schema: { type: string }
          description: URL to analyze for emoji suggestion
        - name: text
          in: query
          schema: { type: string }
          description: Text/topic to suggest emojis for
      responses:
        '200':
          description: Emoji suggestions with confidence scores
          content:
            application/json:
              schema:
                type: object
                properties:
                  query: { type: string }
                  suggestions:
                    type: array
                    items:
                      type: object
                      properties:
                        emoji: { type: string }
                        name: { type: string }
                        slug: { type: string }
                        score: { type: integer }
  /api/eotd:
    get:
      operationId: emojiOfTheDay
      summary: Get today's featured emoji (deterministic, same worldwide)
      responses:
        '200':
          description: Today's emoji with URLs
          content:
            application/json:
              schema:
                type: object
                properties:
                  emoji: { type: string }
                  name: { type: string }
                  slug: { type: string }
                  category: { type: string }
                  date: { type: string }
                  svg_url: { type: string }
                  badge_url: { type: string }
  /api/stats:
    get:
      operationId: getStats
      summary: Get public usage statistics
      responses:
        '200':
          description: Top emojis, referrers, countries
          content:
            application/json:
              schema:
                type: object
                properties:
                  topEmojis: { type: array }
                  countryEmojis: { type: array }
                  totalServed: { type: integer }
                  topReferrers: { type: array }
                  topCountries: { type: array }
  /api/emojis:
    get:
      operationId: getAllEmojis
      summary: Get all 3,773 emojis with categories
      responses:
        '200':
          description: Full emoji catalog
  /{emoji}:
    get:
      operationId: getFavicon
      summary: Get an emoji as an SVG/PNG favicon
      parameters:
        - name: emoji
          in: path
          required: true
          schema: { type: string }
          description: Emoji name, keyword, or URL-encoded character
        - name: size
          in: query
          schema: { type: integer, default: 48, minimum: 16, maximum: 512 }
          description: SVG size in pixels
        - name: bg
          in: query
          schema: { type: string }
          description: Background color (hex without #)
        - name: darkbg
          in: query
          schema: { type: string }
          description: Dark mode background color (hex without #)
        - name: shape
          in: query
          schema: { type: string, enum: [square, circle, rounded, hexagon, diamond, shield, star, heart, triangle, pentagon, octagon, drop, egg, cross, cloud, badge] }
          description: Background shape (16 shapes)
        - name: animate
          in: query
          schema: { type: string, enum: [pulse, bounce, spin, shake, float, flip, tada, swing, wobble, heartbeat, jello, rubberband, flash, pop, squeeze, nod, glitch, breathe, rotate360, wave, zoom, blink, slide-in, rainbow, typing, bounce-in, attention] }
          description: Animation type (27 animations)
        - name: og
          in: query
          schema: { type: boolean }
          description: Return 1200x630 OG image for social sharing
        - name: svg
          in: query
          schema: { type: boolean }
          description: Force SVG format
        - name: png
          in: query
          schema: { type: boolean }
          description: Force PNG format (Twemoji)
      responses:
        '200':
          description: SVG or PNG emoji favicon
  /badge/{emoji}:
    get:
      operationId: getBadge
      summary: Get a shields.io-style SVG badge with emoji
      parameters:
        - name: emoji
          in: path
          required: true
          schema: { type: string }
          description: Emoji name or keyword
        - name: label
          in: query
          schema: { type: string }
          description: Left side text
        - name: status
          in: query
          schema: { type: string }
          description: Right side text
        - name: color
          in: query
          schema: { type: string, default: blue }
          description: Right side color (green, red, yellow, blue, or hex)
        - name: labelColor
          in: query
          schema: { type: string }
          description: Left side background (hex)
        - name: style
          in: query
          schema: { type: string, enum: [rounded, flat], default: rounded }
      responses:
        '200':
          description: SVG badge image
  /avatar/{identifier}:
    get:
      operationId: getAvatar
      summary: Get a deterministic emoji avatar (Gravatar-style)
      parameters:
        - name: identifier
          in: path
          required: true
          schema: { type: string }
          description: Email, username, or any string
        - name: size
          in: query
          schema: { type: integer, default: 128 }
          description: Avatar size in pixels
        - name: shape
          in: query
          schema: { type: string, enum: [square, circle, rounded], default: square }
      responses:
        '200':
          description: SVG avatar image
  /readme/{emoji}:
    get:
      operationId: getReadmeBanner
      summary: Get an 800x200 SVG banner for GitHub READMEs
      parameters:
        - name: emoji
          in: path
          required: true
          schema: { type: string }
        - name: title
          in: query
          schema: { type: string }
          description: Project title
        - name: subtitle
          in: query
          schema: { type: string }
        - name: theme
          in: query
          schema: { type: string, enum: [dark, light], default: dark }
      responses:
        '200':
          description: SVG banner image
  /status/{state}:
    get:
      operationId: getStatusIcon
      summary: Get a status icon (up/down/degraded/maintenance)
      parameters:
        - name: state
          in: path
          required: true
          schema: { type: string, enum: [up, down, degraded, maintenance] }
        - name: emoji
          in: query
          schema: { type: string }
          description: Override default emoji
        - name: size
          in: query
          schema: { type: integer, default: 32 }
      responses:
        '200':
          description: SVG status icon
  /sig/{emoji}:
    get:
      operationId: getEmailSignature
      summary: Get emoji as PNG for email signatures
      parameters:
        - name: emoji
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: PNG image with Content-Disposition inline
  /embed/{emoji}:
    get:
      operationId: getEmbed
      summary: Get a minimal HTML page with centered emoji (for Notion/iframe)
      parameters:
        - name: emoji
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: HTML page
  /oembed:
    get:
      operationId: getOembed
      summary: oEmbed discovery for rich embed previews
      parameters:
        - name: url
          in: query
          required: true
          schema: { type: string }
          description: URL of an /embed/:emoji page
      responses:
        '200':
          description: oEmbed JSON
  /text/{chars}:
    get:
      operationId: getTextFavicon
      summary: Generate a text favicon from 1-3 characters
      parameters:
        - name: chars
          in: path
          required: true
          schema: { type: string, maxLength: 3 }
          description: 1-3 characters for the favicon
      responses:
        '200':
          description: SVG text favicon
  /stack/{bg}+{fg}:
    get:
      operationId: getStackedEmoji
      summary: Layer one emoji on top of another
      parameters:
        - name: bg
          in: path
          required: true
          schema: { type: string }
          description: Background emoji (larger)
        - name: fg
          in: path
          required: true
          schema: { type: string }
          description: Foreground emoji (smaller, overlaid)
      responses:
        '200':
          description: SVG stacked emoji
  /apple-touch-icon/{emoji}:
    get:
      operationId: getAppleTouchIcon
      summary: Get a 180x180 iOS home screen icon
      parameters:
        - name: emoji
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: 180x180 PNG icon
  /manifest/{emoji}:
    get:
      operationId: getPwaManifest
      summary: Auto-generate PWA manifest.json with all icon sizes
      parameters:
        - name: emoji
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: manifest.json with icon URLs
  /download/{emoji}:
    get:
      operationId: downloadFavicon
      summary: Download ZIP with all favicon sizes
      parameters:
        - name: emoji
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: ZIP file with favicon images
  /sprite:
    get:
      operationId: getSpriteSheet
      summary: Generate a multi-emoji grid SVG sprite sheet
      parameters:
        - name: emojis
          in: query
          required: true
          schema: { type: string }
          description: Comma-separated emoji names
        - name: size
          in: query
          schema: { type: integer, default: 48 }
        - name: cols
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: SVG sprite sheet
  /react/{emoji}:
    get:
      operationId: getReactionWidget
      summary: Embeddable reaction widget with counter
      parameters:
        - name: emoji
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: HTML reaction widget
  /preview/{url}:
    get:
      operationId: getLinkPreview
      summary: Generate OG-image-style preview card with emoji
      parameters:
        - name: url
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: SVG preview card
  /ab/{emojiA}/{emojiB}:
    get:
      operationId: getAbTest
      summary: A/B test two emoji variants (random serving with stats)
      parameters:
        - name: emojiA
          in: path
          required: true
          schema: { type: string }
        - name: emojiB
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: SVG of randomly selected variant
  /api/trending:
    get:
      operationId: getTrending
      summary: Get top trending emojis with sparkline charts
      responses:
        '200':
          description: Trending emojis with usage counts
          content:
            application/json:
              schema:
                type: object
                properties:
                  trending: { type: array }
                  period: { type: string }
  /api/webhooks:
    post:
      operationId: createWebhook
      summary: Subscribe to emoji event notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url: { type: string, description: Webhook callback URL }
                events: { type: array, items: { type: string }, description: 'Event types: trending, milestone' }
      responses:
        '200':
          description: Webhook subscription created
    get:
      operationId: listWebhooks
      summary: List active webhook subscriptions
      responses:
        '200':
          description: Active webhooks
    delete:
      operationId: deleteWebhook
      summary: Remove a webhook subscription
      responses:
        '200':
          description: Webhook removed