**Version: 202607**

# Theme Session

Edit a theme through an edit session, the same way the theme editor in the admin does

An edit session, identified by `oseid`, is one opening of the theme editor. Changes made in a session are isolated from other sessions and take effect only after they are saved to the theme's draft; saving checks whether the draft has changed since the session began.

Provides endpoints to create an edit session, check it for conflicts, and save it to the draft; read and write the session's files and apply batch edits; read and update the theme's global configuration (theme settings and global cards such as the header and footer); work with the cards on a page: list the cards added to a template, get a card's details, set card and block properties, add and remove blocks, and remove cards from a page; create cards in the session: list the session's card library, create and manage AI cards (block cards created from liquid code, where every write can be reverted), look up page-builder block definitions, and save a page-builder block into the session; and list, enable, and disable app embeds and script tags. To browse the cards available to add and work with page-builder templates, see Theme Card.

- [Create theme edit session](/api/theme-edit-session-create) `POST /openapi/2026-07/themes/:theme_id/edit-sessions`: Open a temporary edit session (oseid) for the specified theme.

- [Check edit session conflict](/api/theme-edit-session-conflict) `GET /openapi/2026-07/themes/edit-sessions/:oseid/conflict`: Check whether the draft has been changed by another session since this edit session started.

- [Save edit session as draft](/api/theme-edit-session-promote) `POST /openapi/2026-07/themes/edit-sessions/:oseid/promote`: Save an edit session as the draft.

- [Get edit session file](/api/theme-edit-session-file-get) `GET /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id`: Read a single file within a theme edit session.

- [Update edit session file](/api/theme-edit-session-file-update) `PATCH /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id`: Overwrite a template file in the edit session with the given card configs; cards missing from

- [Batch edit operations](/api/theme-edit-session-batch-operations) `POST /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id/operations`: Execute multiple edit operations in one request; each operation runs and is saved

- [Get theme global config](/api/theme-global-config) `GET /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id/global`: Get the current values of the theme settings within an edit session, plus the configuration

- [Update theme global config](/api/theme-global-config-update) `PATCH /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id/global`: Partially update the theme's global config within an edit session: pass only the settings to

- [List cards added to a template](/api/theme-section-cards-list) `GET /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id/sections`: List all cards added to a template within an edit session, including global card groups such

- [Get card details](/api/theme-section-card-detail) `GET /openapi/2026-07/themes/edit-sessions/:oseid/files/:doc_id/sections/:section_id`: Render the specified card with its current config and return the rendered HTML, the card

- [Set card properties](/api/theme-section-set-props) `PATCH /openapi/2026-07/themes/edit-sessions/:oseid/sections/:section_id/props`: Set/merge properties into a card's settings within an edit session.

- [Set block properties in a card](/api/theme-section-set-slot) `PATCH /openapi/2026-07/themes/edit-sessions/:oseid/sections/:section_id/slot`: Set/merge properties into a specific block's settings within a card.

- [Add block to a card](/api/theme-section-add-block) `POST /openapi/2026-07/themes/edit-sessions/:oseid/sections/:section_id/blocks`: Append/insert a block into a card within an edit session.

- [Remove block from a card](/api/theme-section-remove-block) `DELETE /openapi/2026-07/themes/edit-sessions/:oseid/sections/:section_id/blocks`: Remove a block from a card by index within an edit session.

- [Remove card from page](/api/theme-section-remove) `DELETE /openapi/2026-07/themes/edit-sessions/:oseid/sections/:section_id`: Remove a card from the page within an edit session.

- [List edit-session card library](/api/theme-edit-session-card-list) `GET /openapi/2026-07/themes/edit-sessions/:oseid/card-list`: List the cards available in the theme: regular cards (`card_list`, `block_list`) come from the

- [Get AI card details](/api/theme-gen-block-detail) `GET /openapi/2026-07/themes/edit-sessions/:oseid/gen-blocks`: Get an AI card's file info and its usage in the current session (whether it is saved, how many

- [Create AI card](/api/theme-gen-block-create) `POST /openapi/2026-07/themes/edit-sessions/:oseid/gen-blocks`: Create an AI card from liquid code (must contain a `{% schema %}` tag) within an edit session.

- [Delete AI card](/api/theme-gen-block-delete) `DELETE /openapi/2026-07/themes/edit-sessions/:oseid/gen-blocks`: Delete an AI card and remove it from every page of the theme.

- [Update AI card](/api/theme-gen-block-update) `PATCH /openapi/2026-07/themes/edit-sessions/:oseid/gen-blocks`: Update an AI card with new source code and its full settings. If the card is unused or used in

- [Revert AI card operation](/api/theme-gen-block-revert) `POST /openapi/2026-07/themes/edit-sessions/:oseid/gen-blocks/revert`: Restore the card to its state before the operation identified by `revert_id` (returned by any

- [Get page-builder block details](/api/theme-pb-single-blocks) `GET /openapi/2026-07/themes/page-builder/blocks`: Batch-fetch page-builder blocks by `source_ids`: each returns its name, full block `type`, and

- [Save page-builder block](/api/theme-pb-block-save) `POST /openapi/2026-07/themes/page-builder/blocks`: Apply edit operations (`ops`) to a page-builder template and save the result as a new card,

- [List app embeds](/api/theme-apps-list) `GET /openapi/2026-07/themes/apps`: List the embed cards (app embeds) provided by the store's installed apps, plus injected script

- [Enable app embed](/api/theme-app-enable) `POST /openapi/2026-07/themes/edit-sessions/:oseid/apps/enable`: Enable a specific app-embed block or script tag within an edit session.

- [Disable app embed](/api/theme-app-disable) `POST /openapi/2026-07/themes/edit-sessions/:oseid/apps/disable`: Disable a specific app-embed block or script tag within an edit session.