# ArchLogo API reference

ArchLogo is a stateless favicon and app-icon generator. Agents should call the JSON API directly instead of operating the browser editor.

## Discovery

- OpenAPI 3.1: https://archlogo.com/openapi.json
- Live JSON contract: GET https://archlogo.com/api/icon-package
- Human and embedded machine documentation: https://archlogo.com/api

## Generate icons

POST `https://archlogo.com/api/icon-package` with `Content-Type: application/json`.

```json
{
  "projectName": "my-app",
  "bgColor": "#030816",
  "shape": "rounded",
  "layers": [
    {
      "enabled": true,
      "text": "A",
      "font": "Open Sans",
      "textColor": "#EEEEEE",
      "fontSize": 400,
      "fontWeight": "normal",
      "offsetX": 0,
      "offsetY": 0,
      "rotation": 0,
      "squish": 1,
      "flipHorizontal": false,
      "flipVertical": false
    }
  ]
}
```

Options may also be nested under an `options` key. Omitted fields receive defaults.

## Constraints

- `shape`: `square`, `rounded`, or `circle`; `rounded` means Squircle.
- `layers`: one or two entries. Layer 1 renders above Layer 2.
- `text`: at most four characters per layer.
- Colors: hex, RGB/RGBA, HSL/HSLA, or HSV/HSB forms.
- `fontSize`: integer 1–1024 or `null`.
- `fontWeight`: `normal` or `bold`.
- Default fonts: Layer 1 uses `Open Sans`; a newly added Layer 2 uses `Playfair Display`.
- `offsetX`, `offsetY`: integers -1024–1024.
- `rotation`: integer -360–360.
- `squish`: number 0.1–10 inclusive, default 1; fractional values are allowed.
- Flip values and `enabled`: booleans. Setting a layer to `enabled: false` preserves its other fields but omits it from rendering and `logo.txt`.

## Squish and transforms

Squish multiplies a layer's letter height without changing width, font size, background, or position. `1` preserves normal proportions, `2` doubles height, and `0.5` halves height (making the lettering twice as wide relative to its height). It acts along the text's local vertical axis before rotation and combines with both flip settings. Oversized text is clipped at the icon edges; reduce `fontSize` if necessary.

For taller lettering with room inside the icon:

```json
{"projectName":"tall","layers":[{"text":"A","fontSize":160,"squish":2}]}
```

The same field works under `options.layers` and through the `/api/generate-logo` compatibility endpoint. Omit `squish` for normal proportions. Use a JSON number, not a string; `null`, zero, negative values, and values outside 0.1–10 return HTTP 400 with an issue path identifying the invalid field.

Both layers have independent values. In the browser, Squish appears beside Rotate, and its value survives visibility changes and layer reordering. Canvas previews, font thumbnails, PNGs, ICOs, and API SVGs share the transform. `logo.txt` records `Layer N Squish: <value>` for enabled layers only.

## Responses

- `200 application/zip`: generated package.
- `400 application/json`: invalid JSON or invalid options, including issue paths.
- `500 application/json`: unexpected generation failure.

The ZIP includes `favicon-16x16.png`, `favicon-32x32.png`, `favicon.ico`, `apple-touch-icon.png`, `android-chrome-192x192.png`, `android-chrome-512x512.png`, `manifest.json`, `logo.svg`, and `logo.txt`.