The API

Everything the CLI does, over HTTP, with a token that can reach themes and nothing else.

Authentication

A theme token, in an Authorization header. Get one from the Eldorados admin under Websites → the site → Themes.

Authorization: Bearer eld_theme_...

A token is scoped to one organisation, optionally pinned to a single site, and carries only read_themes and write_themes. It cannot read form submissions, leads or page drafts — not because a check refuses it, but because the credential has no way to ask. Hand one to a contractor without handing over the account.

Endpoints

Endpoint	Scope	Purpose
`GET /api/v1/themes?site=`	`read_themes`	Themes on a site, with their snapshots
`GET /api/v1/themes/:snapshot`	`read_themes`	The manifest: every path, hash and size
`GET /api/v1/themes/:snapshot/files?path=`	`read_themes`	One file, ETag’d on its content hash
`POST /api/v1/themes/push`	`write_themes`	Upload a theme, sending only what is new
`POST /api/v1/themes/:snapshot/publish`	`write_themes`	Make a snapshot live

Pushing

Send a hash per file. If the server is missing any blob it answers 409 with missing, and you resend with the content of exactly those files.

POST /api/v1/themes/push
{
  "siteId": "site_abc123",
  "label": "from CI",
  "files": {
    "layout/theme.liquid": { "hash": "a1b2…", "content": "<!doctype html>…" },
    "sections/hero.liquid": { "hash": "c3d4…" }
  }
}

Content is re-hashed on arrival and a mismatched claim is refused. A push is atomic: the whole theme is validated first and nothing is written if it fails, so a half-pushed theme cannot exist and therefore cannot be published.

Errors

Status	Means
`401`	No valid token. The message is the same whatever is wrong with it.
`403`	The token lacks the scope, which the message names.
`404`	No such site, theme or snapshot — or it is not yours. Deliberately the same answer.
`409`	Missing blobs, or the theme changed since you pulled.
`422`	The theme did not validate. The body lists every offense with file and line.