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.

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

{
  "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) 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.