REST API reference

Authentication

Create a key on the dashboard. The key is shown once, at creation, and only a hash of it is stored, so if you lose it nobody can recover it for you and you will need to mint a new one. Send it as a bearer token:

Authorization: Bearer sk_your_key_here

An x-api-key: sk_your_key_here header works too. A missing, unknown, or revoked key returns 401.

Generate an icon package

POST /api/generate
Content-Type: multipart/form-data

One call takes one image and returns one package. The plan check happens before any pixels are read, so an over-limit request is refused up front and costs you nothing.

curl -X POST https://faviconize.com/api/generate \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@logo.png" \
  -F "name=Acme" \
  -F "themeColor=#0b5cff"

The response is JSON. It carries the signed download link, what we read from your source, the exact list of files in the package with their measured dimensions, a paste-ready head snippet, and your usage standing. The dimensions are read back from the encoded bytes, so they are a measurement of the output rather than an echo of the request.

{
  "downloadUrl": "https://faviconize.com/api/download/eyJrIjoi...9Q.Ab3d",
  "downloadName": "favicons.zip",
  "expiresInSeconds": 900,
  "deletedAfterHours": 24,
  "source": { "format": "png", "width": 512, "height": 512 },
  "files": [
    { "name": "favicon.ico", "bytes": 15086, "width": 48, "height": 48, "layers": 3 },
    { "name": "favicon-32x32.png", "bytes": 1210, "width": 32, "height": 32 },
    { "name": "apple-touch-icon.png", "bytes": 8842, "width": 180, "height": 180 },
    { "name": "icon-maskable.png", "bytes": 9310, "width": 512, "height": 512 },
    { "name": "site.webmanifest", "bytes": 263 }
  ],
  "zipBytes": 34714,
  "headSnippet": "<link rel=\"icon\" href=\"/favicon.ico\" sizes=\"any\">\n...",
  "warnings": [],
  "metered": true,
  "usage": { "used": 3, "remaining": 97 }
}

An image we cannot decode returns 422 with a sentence you can show a user. When that happens the reserved unit is handed back, so a failed call is not billed. Anything we had to change that you might not expect, such as padding a non-square source, is reported in warnings rather than done silently.

Download the package

GET /api/download/{token}

The downloadUrl in the response already points here. No key is needed on this request: the signed token is the credential, so the link can be handed straight to a browser or a build step that holds no key. It is bound to one package and it expires, currently after 15 minutes.

curl -L -o favicons.zip https://faviconize.com/api/download/$TOKEN

The body is the ZIP, served with a Content-Disposition: attachment header. A package is deleted 24 hours after it is created, under the retention policy, so download promptly or generate again. An expired link returns 410; a link whose package has already been swept returns 410 as well; a token that does not verify returns 403.

Metering

One image is one package is one unit. The API has no browser session, so every call uploads one image and reserves one unit before the work starts. Calling again with the same key and the same bytes in the same period is the same billable image, and the second call is free.

Errors

Errors are always JSON with an error field carrying a sentence you can show a user.