openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Sednicon API",
    "description": "Sednicon is a lightweight, headless icon rendering API that generates customizable SVG icons on the fly via a single URL. No installation, no dependencies, no API key — just a URL. Backed by Iconify's 200,000+ icon network with a multi-set fallback chain, so a valid SVG is always returned.",
    "version": "3.0.0",
    "contact": {
      "name": "Sednium",
      "url": "https://sednium.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://github.com/AnkushDas4/IconFlow/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "https://sednicon.sednium.com",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "Icons", "description": "Render dynamic SVG icons" },
    { "name": "Status", "description": "API health and version information" }
  ],
  "paths": {
    "/api/render": {
      "get": {
        "tags": ["Icons"],
        "summary": "Render an icon as SVG",
        "description": "Returns an SVG image for the requested icon name, with optional color and size customization. Always returns a valid SVG with HTTP 200 — if the requested icon name cannot be matched in any icon set, a generic placeholder icon is returned instead.",
        "operationId": "renderIcon",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Icon name to render. Accepts names from Material Symbols, Lucide, Simple Icons (brand logos), and 12+ other icon sets via automatic fallback. An explicit set can be specified using `set:name` syntax (e.g. `lucide:home`).",
            "required": false,
            "schema": {
              "type": "string",
              "default": "circle",
              "examples": ["rocket", "github", "home", "lucide:home"]
            }
          },
          {
            "name": "color",
            "in": "query",
            "description": "Icon color as a hex code (with or without leading `#`) or a CSS color keyword.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "000000",
              "examples": ["000000", "ff6600", "2563eb", "red"]
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "Icon width and height in pixels. Clamped to the range 1–2048.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 24,
              "minimum": 1,
              "maximum": 2048,
              "examples": [24, 48, 64, 128]
            }
          },
          {
            "name": "set",
            "in": "query",
            "description": "Optional explicit Iconify icon set prefix to force (e.g. `lucide`, `tabler`, `mdi`). Overrides automatic fallback for this request.",
            "required": false,
            "schema": {
              "type": "string",
              "examples": ["lucide", "tabler", "mdi", "phosphor"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SVG icon, styled with the requested color and size.",
            "headers": {
              "Content-Type": {
                "schema": { "type": "string", "example": "image/svg+xml; charset=utf-8" }
              },
              "Cache-Control": {
                "schema": { "type": "string", "example": "public, max-age=86400, s-maxage=604800, stale-while-revalidate=2592000, immutable" }
              },
              "Access-Control-Allow-Origin": {
                "schema": { "type": "string", "example": "*" }
              },
              "X-Sednicon-Source": {
                "description": "Indicates which icon set ultimately served the request (e.g. `iconify:material-symbols`, `custom-brand`, `iconify:search`, `generic-fallback`).",
                "schema": { "type": "string", "example": "iconify:material-symbols" }
              }
            },
            "content": {
              "image/svg+xml": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          },
          "204": {
            "description": "CORS preflight response (OPTIONS request)."
          }
        }
      },
      "options": {
        "tags": ["Icons"],
        "summary": "CORS preflight for /api/render",
        "operationId": "renderIconPreflight",
        "responses": {
          "204": { "description": "Preflight OK" }
        }
      }
    },
    "/api/status": {
      "get": {
        "tags": ["Status"],
        "summary": "API health and version information",
        "description": "Returns the current operational status of the Sednicon API, version metadata, and the health of upstream dependencies (Iconify).",
        "operationId": "getStatus",
        "responses": {
          "200": {
            "description": "Service is operational.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StatusResponse" },
                "example": {
                  "status": "operational",
                  "version": "3.0.0",
                  "released": "2026-06-14",
                  "timestamp": "2026-06-15T02:00:00.000Z",
                  "dependencies": { "iconify": "operational" },
                  "upstream_check_ms": 142,
                  "endpoints": {
                    "render": "/api/render",
                    "status": "/api/status"
                  },
                  "region": "iad1"
                }
              }
            }
          },
          "503": {
            "description": "Service is degraded — an upstream dependency (Iconify) is unreachable.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StatusResponse" },
                "example": {
                  "status": "degraded",
                  "version": "3.0.0",
                  "released": "2026-06-14",
                  "timestamp": "2026-06-15T02:00:00.000Z",
                  "dependencies": { "iconify": "unreachable" },
                  "upstream_check_ms": 3001,
                  "endpoints": {
                    "render": "/api/render",
                    "status": "/api/status"
                  },
                  "region": "iad1"
                }
              }
            }
          }
        }
      },
      "options": {
        "tags": ["Status"],
        "summary": "CORS preflight for /api/status",
        "operationId": "getStatusPreflight",
        "responses": {
          "204": { "description": "Preflight OK" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "StatusResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["operational", "degraded"]
          },
          "version": { "type": "string" },
          "released": { "type": "string", "format": "date" },
          "timestamp": { "type": "string", "format": "date-time" },
          "dependencies": {
            "type": "object",
            "properties": {
              "iconify": {
                "type": "string",
                "enum": ["operational", "degraded", "unreachable", "unknown"]
              }
            }
          },
          "upstream_check_ms": { "type": "integer" },
          "endpoints": {
            "type": "object",
            "properties": {
              "render": { "type": "string" },
              "status": { "type": "string" }
            }
          },
          "region": { "type": "string" }
        }
      }
    }
  }
}