# Themes (/docs/api/gateway/themes)

Public catalogue of curated third-party colour themes, converted from MIT-licensed VS Code themes and contrast-checked.

`GET /v1/themes` returns the curated colour themes every codai app offers under **Settings → Appearance → More themes**. They are converted from their authors' MIT-licensed VS Code themes (Dracula, Catppuccin, GitHub, Tokyo Night, One Dark Pro, Nord, Solarized, Gruvbox, Rosé Pine), pinned to a source commit, and adjusted only where a text colour fell below 4.5:1 contrast on a surface. Nothing is downloaded from the VS Code Marketplace or Open VSX, and nothing is executed: a theme is colour data.

The endpoint is public — no API key — and the same for every caller. Responses carry a strong `ETag` and `Cache-Control: public, max-age=86400`; send the tag back in `If-None-Match` and you get `304 Not Modified` with an empty body. The apps ship the same catalogue bundled, so they work offline and only refresh it from here.

```bash
curl -s https://ai.codai.ro/v1/themes -H 'If-None-Match: "2026.10.30-1-3f2a9c1d"' -i
```

```json
{
  "version": "2026.10.30-1",
  "etag": "\"2026.10.30-1-3f2a9c1d\"",
  "themes": [
    {
      "id": "catalog.dracula",
      "name": "Dracula",
      "base": "dark",
      "accentHue": 278,
      "colors": { "bg": "#282a36", "foreground": "#f8f8f2", "muted": "#7e90c4", "...": "..." },
      "terminal": { "black": "#21222c", "red": "#ff5555", "...": "..." },
      "description": "Dracula by Dracula Theme, converted from the MIT-licensed VS Code theme.",
      "author": "Dracula Theme",
      "license": { "spdx": "MIT", "copyright": "Copyright (c) 2016 Dracula Theme", "url": "https://github.com/dracula/visual-studio-code/blob/…/LICENSE" },
      "source": { "repo": "dracula/visual-studio-code", "commit": "9726e1f…", "path": "…", "url": "…" }
    }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `id` | Stable `catalog.<slug>` id; store it in `appearance.colorTheme` (see [Settings](./settings)) to sync the choice across devices. |
| `base` | `light` or `dark`; `highContrast: true` is present only for high-contrast themes. |
| `accentHue` | OKLCH hue (0–360) of the theme's accent, used for the brand palette. |
| `colors` | Workbench tokens: `bg`, `bgElevated`, `bgPanel`, `border`, `borderStrong`, `foreground`, `muted`, `muted2`, `danger`, `success`, `warning` (opaque `#rrggbb`). |
| `terminal` | The 16 ANSI colours (`black` … `brightWhite`) when the source theme defines them. |
| `license`, `source` | SPDX id, copyright line and licence URL; source repository, pinned commit and file. Show them in your licences screen. |

The catalogue is built by `packages/themes-catalog/scripts/build-catalog.mjs`, which only accepts MIT, Apache-2.0 and BSD licences. Desktop and Android can also import a local `.vsix` or VS Code theme JSON; only the `contributes.themes` colour files are read.