{
  "components": {
    "headers": {
      "Colour": {
        "description": "#rrggbb",
        "schema": {
          "pattern": "^#[0-9a-f]{6}$",
          "type": "string"
        }
      }
    },
    "parameters": {
      "IfNoneMatch": {
        "in": "header",
        "name": "If-None-Match",
        "required": false,
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "Icon": {
        "content": {
          "image/svg+xml": {
            "schema": {
              "type": "string"
            }
          }
        },
        "description": "A real icon, or a generated one when X-Icon-Fallback-Reason is present.",
        "headers": {
          "ETag": {
            "schema": {
              "type": "string"
            }
          },
          "Server-Timing": {
            "schema": {
              "examples": [
                "app;dur=0.83"
              ],
              "type": "string"
            }
          },
          "X-Icon-Accent": {
            "$ref": "#/components/headers/Colour"
          },
          "X-Icon-Blocked": {
            "schema": {
              "enum": [
                "blocklist",
                "dns-filter"
              ],
              "type": "string"
            }
          },
          "X-Icon-Dark-Mono": {
            "$ref": "#/components/headers/Colour"
          },
          "X-Icon-Dark-Mono-Plate": {
            "$ref": "#/components/headers/Colour"
          },
          "X-Icon-Dark-Plate": {
            "$ref": "#/components/headers/Colour"
          },
          "X-Icon-Dark-Text": {
            "$ref": "#/components/headers/Colour"
          },
          "X-Icon-Domain": {
            "schema": {
              "type": "string"
            }
          },
          "X-Icon-Fallback-Reason": {
            "schema": {
              "enum": [
                "queued",
                "overloaded",
                "not-found",
                "fetch-failed",
                "domain-too-new",
                "blocklisted",
                "dns-blocked",
                "invalid-domain",
                "no-monochrome"
              ],
              "type": "string"
            }
          },
          "X-Icon-Fill": {
            "schema": {
              "enum": [
                "bleed",
                "inset"
              ],
              "type": "string"
            }
          },
          "X-Icon-License": {
            "schema": {
              "type": "string"
            }
          },
          "X-Icon-Light-Mono": {
            "$ref": "#/components/headers/Colour"
          },
          "X-Icon-Light-Mono-Plate": {
            "$ref": "#/components/headers/Colour"
          },
          "X-Icon-Light-Plate": {
            "$ref": "#/components/headers/Colour"
          },
          "X-Icon-Light-Text": {
            "$ref": "#/components/headers/Colour"
          },
          "X-Icon-Mono-Source": {
            "schema": {
              "enum": [
                "mask-icon",
                "derived"
              ],
              "type": "string"
            }
          },
          "X-Icon-Provenance": {
            "schema": {
              "enum": [
                "site",
                "bimi",
                "thesvg",
                "upstream",
                "catalog"
              ],
              "type": "string"
            }
          },
          "X-Icon-Shape": {
            "schema": {
              "enum": [
                "square",
                "rounded",
                "circle",
                "none"
              ],
              "type": "string"
            }
          },
          "X-Icon-Source": {
            "schema": {
              "enum": [
                "cache",
                "origin",
                "generated"
              ],
              "type": "string"
            }
          },
          "X-Icon-Style": {
            "schema": {
              "enum": [
                "color",
                "mono"
              ],
              "type": "string"
            }
          },
          "X-Icon-Vector": {
            "schema": {
              "enum": [
                "original",
                "traced",
                "generated"
              ],
              "type": "string"
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Full HTTP contract",
    "url": "https://github.com/peleda-app/favicons/blob/main/docs/API.md"
  },
  "info": {
    "description": "One GET returns a site's icon as an edge-to-edge SVG, in colour or as a black monochrome mask. No key, no query parameters, CORS open. The response is an SVG even when the site has no usable icon; the headers explain why.",
    "license": {
      "identifier": "MIT",
      "name": "MIT"
    },
    "summary": "Website icons as sanitized SVG, with theme colours in the headers.",
    "title": "favicons.page",
    "version": "1.2.1"
  },
  "openapi": "3.1.0",
  "paths": {
    "/": {
      "get": {
        "operationId": "page",
        "responses": {
          "200": {
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "HTML"
          }
        },
        "summary": "The demo page"
      }
    },
    "/catalogs.json": {
      "get": {
        "operationId": "listCatalogs",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "JSON array"
          }
        },
        "summary": "Configured catalogs: id, name, license, attribution, count"
      }
    },
    "/catalogs/{file}": {
      "get": {
        "operationId": "catalogItems",
        "parameters": [
          {
            "description": "{id}.json",
            "in": "path",
            "name": "file",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "JSON object"
          },
          "404": {
            "description": "Unknown catalog."
          }
        },
        "summary": "Every slug in a catalog with its name, category and tags"
      }
    },
    "/config.example.toml": {
      "get": {
        "operationId": "configExample",
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "TOML"
          }
        },
        "summary": "Every server option, commented"
      }
    },
    "/docker-compose.yml": {
      "get": {
        "operationId": "compose",
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "YAML"
          }
        },
        "summary": "Hardened two-container setup"
      }
    },
    "/healthz": {
      "get": {
        "operationId": "health",
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "ok"
          }
        },
        "summary": "Liveness"
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "llms",
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Markdown"
          }
        },
        "summary": "How to use the API, for language models"
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "openapi",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "OpenAPI 3.1"
          }
        },
        "summary": "This description"
      }
    },
    "/robots.txt": {
      "get": {
        "operationId": "robots",
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "robots.txt"
          }
        },
        "summary": "Crawler rules"
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "sitemap",
        "responses": {
          "200": {
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "XML"
          }
        },
        "summary": "Sitemap of the page"
      }
    },
    "/{style}/{catalog}/{slug}": {
      "get": {
        "operationId": "getCatalogIcon",
        "parameters": [
          {
            "description": "color: the icon in its own colours. mono: one black shape for CSS masks.",
            "in": "path",
            "name": "style",
            "required": true,
            "schema": {
              "enum": [
                "color",
                "mono"
              ],
              "type": "string"
            }
          },
          {
            "description": "Catalog id; /catalogs.json lists them.",
            "in": "path",
            "name": "catalog",
            "required": true,
            "schema": {
              "enum": [
                "selfhst",
                "simple-icons",
                "dashboard-icons",
                "devicon",
                "thesvg",
                "fluent-emoji",
                "twemoji",
                "noto",
                "emojione",
                "fxemoji",
                "fluent-color",
                "withicons-soft3d",
                "iconito",
                "vscode-icons",
                "catppuccin",
                "cryptocurrency",
                "web3"
              ],
              "type": "string"
            }
          },
          {
            "description": "Icon slug; /catalogs/{id}.json lists them.",
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "examples": [
                "jellyfin"
              ],
              "pattern": "^[a-z0-9-]{1,64}$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Icon"
          },
          "301": {
            "description": "Non-canonical slug."
          },
          "404": {
            "description": "Unknown style, catalog or slug."
          },
          "503": {
            "description": "The catalog index is still loading."
          }
        },
        "summary": "Icon from an optional catalog, by slug"
      }
    },
    "/{style}/{catalog}/{slug}/{shape}": {
      "get": {
        "operationId": "getAutoPlatedCatalogIcon",
        "parameters": [
          {
            "description": "color: the icon in its own colours. mono: one black shape for CSS masks.",
            "in": "path",
            "name": "style",
            "required": true,
            "schema": {
              "enum": [
                "color",
                "mono"
              ],
              "type": "string"
            }
          },
          {
            "description": "Catalog id; /catalogs.json lists them.",
            "in": "path",
            "name": "catalog",
            "required": true,
            "schema": {
              "enum": [
                "selfhst",
                "simple-icons",
                "dashboard-icons",
                "devicon",
                "thesvg",
                "fluent-emoji",
                "twemoji",
                "noto",
                "emojione",
                "fxemoji",
                "fluent-color",
                "withicons-soft3d",
                "iconito",
                "vscode-icons",
                "catppuccin",
                "cryptocurrency",
                "web3"
              ],
              "type": "string"
            }
          },
          {
            "description": "Icon slug; /catalogs/{id}.json lists them.",
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "examples": [
                "jellyfin"
              ],
              "pattern": "^[a-z0-9-]{1,64}$",
              "type": "string"
            }
          },
          {
            "description": "rounded: 22.5% corner radius. superellipse: n = 5, like iOS app icons.",
            "in": "path",
            "name": "shape",
            "required": true,
            "schema": {
              "enum": [
                "rounded",
                "superellipse"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Icon"
          },
          "301": {
            "description": "Non-canonical slug."
          },
          "404": {
            "description": "Unknown style, catalog or slug."
          },
          "503": {
            "description": "The catalog index is still loading."
          }
        },
        "summary": "Catalog icon on its plate, following the system light or dark scheme"
      }
    },
    "/{style}/{catalog}/{slug}/{shape}/{theme}": {
      "get": {
        "operationId": "getPlatedCatalogIcon",
        "parameters": [
          {
            "description": "color: the icon in its own colours. mono: one black shape for CSS masks.",
            "in": "path",
            "name": "style",
            "required": true,
            "schema": {
              "enum": [
                "color",
                "mono"
              ],
              "type": "string"
            }
          },
          {
            "description": "Catalog id; /catalogs.json lists them.",
            "in": "path",
            "name": "catalog",
            "required": true,
            "schema": {
              "enum": [
                "selfhst",
                "simple-icons",
                "dashboard-icons",
                "devicon",
                "thesvg",
                "fluent-emoji",
                "twemoji",
                "noto",
                "emojione",
                "fxemoji",
                "fluent-color",
                "withicons-soft3d",
                "iconito",
                "vscode-icons",
                "catppuccin",
                "cryptocurrency",
                "web3"
              ],
              "type": "string"
            }
          },
          {
            "description": "Icon slug; /catalogs/{id}.json lists them.",
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "examples": [
                "jellyfin"
              ],
              "pattern": "^[a-z0-9-]{1,64}$",
              "type": "string"
            }
          },
          {
            "description": "rounded: 22.5% corner radius. superellipse: n = 5, like iOS app icons.",
            "in": "path",
            "name": "shape",
            "required": true,
            "schema": {
              "enum": [
                "rounded",
                "superellipse"
              ],
              "type": "string"
            }
          },
          {
            "description": "Which theme's plate and mask colours to use.",
            "in": "path",
            "name": "theme",
            "required": true,
            "schema": {
              "enum": [
                "light",
                "dark"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Icon"
          },
          "301": {
            "description": "Non-canonical slug."
          },
          "404": {
            "description": "Unknown style, catalog or slug."
          },
          "503": {
            "description": "The catalog index is still loading."
          }
        },
        "summary": "Catalog icon drawn on its themed plate"
      }
    },
    "/{style}/{domain}": {
      "get": {
        "operationId": "getIcon",
        "parameters": [
          {
            "description": "color: the icon in its own colours. mono: one black shape for CSS masks.",
            "in": "path",
            "name": "style",
            "required": true,
            "schema": {
              "enum": [
                "color",
                "mono"
              ],
              "type": "string"
            }
          },
          {
            "description": "Registrable domain, e.g. github.com. Any other form gets a 301 to it.",
            "in": "path",
            "name": "domain",
            "required": true,
            "schema": {
              "examples": [
                "discord.com"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Icon"
          },
          "301": {
            "description": "Non-canonical domain or path; Location holds the canonical URL."
          },
          "304": {
            "description": "If-None-Match matched."
          },
          "404": {
            "description": "Unknown style or path."
          },
          "429": {
            "description": "Rate limit for this network; retry after Retry-After seconds."
          },
          "503": {
            "description": "Overloaded or timed out; retry shortly."
          }
        },
        "summary": "Icon of a website, as an edge-to-edge SVG"
      }
    },
    "/{style}/{domain}/{shape}": {
      "get": {
        "description": "Both themes' plate and mask colours are in the SVG; a prefers-color-scheme media query picks one.",
        "operationId": "getAutoPlatedIcon",
        "parameters": [
          {
            "description": "color: the icon in its own colours. mono: one black shape for CSS masks.",
            "in": "path",
            "name": "style",
            "required": true,
            "schema": {
              "enum": [
                "color",
                "mono"
              ],
              "type": "string"
            }
          },
          {
            "description": "Registrable domain, e.g. github.com. Any other form gets a 301 to it.",
            "in": "path",
            "name": "domain",
            "required": true,
            "schema": {
              "examples": [
                "discord.com"
              ],
              "type": "string"
            }
          },
          {
            "description": "rounded: 22.5% corner radius. superellipse: n = 5, like iOS app icons.",
            "in": "path",
            "name": "shape",
            "required": true,
            "schema": {
              "enum": [
                "rounded",
                "superellipse"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Icon"
          },
          "301": {
            "description": "Non-canonical domain."
          },
          "404": {
            "description": "Unknown style or shape."
          }
        },
        "summary": "Icon on its plate, following the system light or dark scheme"
      }
    },
    "/{style}/{domain}/{shape}/{theme}": {
      "get": {
        "operationId": "getPlatedIcon",
        "parameters": [
          {
            "description": "color: the icon in its own colours. mono: one black shape for CSS masks.",
            "in": "path",
            "name": "style",
            "required": true,
            "schema": {
              "enum": [
                "color",
                "mono"
              ],
              "type": "string"
            }
          },
          {
            "description": "Registrable domain, e.g. github.com. Any other form gets a 301 to it.",
            "in": "path",
            "name": "domain",
            "required": true,
            "schema": {
              "examples": [
                "discord.com"
              ],
              "type": "string"
            }
          },
          {
            "description": "rounded: 22.5% corner radius. superellipse: n = 5, like iOS app icons.",
            "in": "path",
            "name": "shape",
            "required": true,
            "schema": {
              "enum": [
                "rounded",
                "superellipse"
              ],
              "type": "string"
            }
          },
          {
            "description": "Which theme's plate and mask colours to use.",
            "in": "path",
            "name": "theme",
            "required": true,
            "schema": {
              "enum": [
                "light",
                "dark"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Icon"
          },
          "301": {
            "description": "Non-canonical domain."
          },
          "404": {
            "description": "Unknown style, shape or theme."
          }
        },
        "summary": "Icon drawn on its themed plate"
      }
    }
  },
  "servers": [
    {
      "url": "https://favicons.page"
    }
  ]
}