MattersimpleDocs

API reference

The theme CLI talks to the platform through this API. You can use it directly, e.g. from a CI pipeline.

  • Base URL: https://<platform address>/api/theme/v1/
  • Authentication: Authorization: Bearer rtk_…, a token from Website → Themes → Developer tools → Developer access. The token picks the firm.
  • Format: JSON (send Accept: application/json); uploads are multipart/form-data.
  • Rate limit: 120 requests a minute per token.

Endpoints

Method and path Purpose
GET /me The token's firm (id, name, subdomain, site_url), user and token name.
GET /starter-kit?name=<name> The starter kit zip.
GET /themes The firm's themes: id, name, role (main, unpublished, development), source, version, files_hash, created_at, updated_at. Other developers' development themes aren't listed.
POST /themes Install a zip (theme). role=unpublished (default) adds it to the library; role=development creates or overwrites your development theme. Optional name. Returns the theme, 201.
POST /themes/check Validate a zip (theme) without installing it. Returns ignored, the development files that would be skipped.
GET /themes/{id} One theme.
GET /themes/{id}/files Every file: path, checksum, size; documents also have pushed_checksum (see below).
GET /themes/{id}/files/{path} One file's contents. Documents come back as the editor's current version.
PUT /themes/{id}/files Change files (below).
GET /themes/{id}/preview preview_url (signed, valid 12 hours) and editor_url.
POST /themes/{id}/publish Make the theme live. Development themes can't be published.

Changing files

HTTP
PUT /api/theme/v1/themes/{id}/files
Content-Type: application/json

{
    "upsert": [
        { "path": "sections/hero.liquid", "content": "<base64>" },
        { "path": "templates/index.json", "content": "<base64>" }
    ],
    "delete": ["snippets/old.liquid"],
    "allow_live": false
}
  • The changes are applied to the theme's files and the whole result is validated like an upload. If anything is wrong, nothing changes.
  • Documents you send (templates/*.json, sections/*-group.json, config/settings_data.json) replace the editor's versions. On the live theme they replace the unpublished draft only. Documents you don't send keep the firm's edits.
  • Only themes uploaded by the firm can be changed, not the bundled themes.
  • The live theme needs "allow_live": true.

Checksums are SHA-256, of the file's bytes, or for documents of their compact JSON (JSON.stringify(JSON.parse(text))), so formatting doesn't count as a change. checksum is of the editor's current version; pushed_checksum of the version last uploaded or pushed. Compare your files with pushed_checksum to find what you changed.

Errors

Status Meaning
401 Missing, unknown, expired or revoked token.
403 The token's user no longer has the Manage themes permission on the firm.
404 No such theme for this token.
409 Pushing to the live theme without allow_live.
422 Invalid request, or the theme has problems: { "message": "…", "problems": ["sections/hero.liquid (line 3): …", …] }.
429 Too many requests.

Still need help?

Send a request to the Mattersimple team and we'll reply by email.

Sign in to contact support