REST JSON API

Choose your integration

For a fixed image, use a direct image URL. For a dynamic asset ID, use the JSON resolver. Both are package-free.

Endpoint and parameters

GET https://softhoursdiary-emojis.pages.dev/[api/v1/asset?type=emoji&id=1f632&quality=svg

Aliases: emojis maps to emoji; flag-icon and flagicon map to flags.

Simple option — direct image URL

For a fixed emoji, no API request is needed:

<img
  src="https://softhoursdiary-emojis.pages.dev/[emojis/svg/1f632.svg"
  alt="Surprised face"
  width="36"
  height="36"
  loading="lazy"
  decoding="async"
/>

This is the lightest option for fixed assets. See the URL reference for all exact paths.

Call the JSON API with fetch

const params = new URLSearchParams({
  type: "emoji",
  id: "1f632",
  quality: "svg"
});

const response = await fetch(
  "https://softhoursdiary-emojis.pages.dev/[api/v1/asset?" + params
);
const result = await response.json();

if (!response.ok || !result.ok) {
  throw new Error(result.error?.message || "Asset lookup failed.");
}

document.querySelector("#reaction").src = result.data.url;

Use URLSearchParams when IDs contain Unicode so the query string is encoded correctly.

Successful response

{
  "ok": true,
  "data": {
    "type": "emoji",
    "id": "1f632",
    "quality": "svg",
    "path": "/emojis/svg/1f632.svg",
    "url": "https://softhoursdiary-emojis.pages.dev/[emojis/svg/1f632.svg",
    "mimeType": "image/svg+xml"
  },
  "meta": {
    "apiVersion": "1.0.0"
  }
}

The mimeType is image/png for PNG emoji assets and image/svg+xml for SVG assets.

Error responses

{
  "ok": false,
  "error": {
    "code": "invalid_quality",
    "message": "Emoji quality must be \"svg\" or \"png\"."
  },
  "meta": {
    "apiVersion": "1.0.0"
  }
}

Missing or invalid parameters return HTTP 400. Unsupported methods return 405. Unexpected failures return 500. Check both response.ok and result.ok.

Methods, CORS and caching

The endpoint supports GET, HEAD and OPTIONS. It is public and read-only, returns no user data and allows cross-origin reads. Successful URL resolutions use short public caching.

The JSON API only constructs a URL. It does not make another request to confirm that the image file exists. A valid response can still point to an asset that returns 404 if the filename is not in the published collection.

Static image files keep their separately configured CORS policy. See CORS & crawlers for the difference.

Try the playground

Open the interactive playground to preview an asset and copy either a direct image snippet or a JSON API fetch example.