openapi: 3.2.0
info:
  title: Hosted Pages API
  version: 2.1.0
  contact:
    name: cidaas support
    url: 'https://support.cidaas.com'
    email: support@cidaas.de
  description: |
    The APIs on this page help manage hosted page groups that implement various cidaas flows for registration, login, verification methods, consent approvals, etc.

    cidaas allows managing multiple hosted pages of different types in a group. As a customer, you can assign one hosted page group per client.

    **Learn more:** [Hosted Pages Overview](/guides/hosted-pages/hosted-pages-management)

    _Management of hosted pages_

    * **Create and update** a hosted page group - Use `POST /hostedpages-srv/hpgroup` to create or update a hosted pages group
    * **Delete** a hosted page group - Use `DELETE /hostedpages-srv/hpgroup/{id}` to remove an entire group
    * **Find** hosted pages groups based on hosted page IDs and owner types - Use `GET /hostedpages-srv/hpgroup` with query parameters
    * **Manage individual hosted pages** - Add, update, or remove specific pages within a group using `POST /hostedpages-srv/hpgroup/{id}` and `DELETE /hostedpages-srv/hpgroup/{id}/{hpid}`
    * **Manage hosted page themes** - Customize the visual appearance using theme APIs (see [Theming Guide](../../../guides/hosted-pages/hosted-pages-theming))
    * **Manage translations** - Add custom translations for different locales (see [Translation Guide](../../../guides/hosted-pages/hosted-pages-translation))

    _Determining hosted pages_

    * Determine the hosted page when ID and current locale values are passed using `GET /hostedpages-srv/hpgroup/{id}/{hpid}` with optional locale parameter.

    _CRUD Operations Overview_

    **Hosted Pages Groups:**
    - **Create:** `POST /hostedpages-srv/hpgroup` - Creates a new hosted pages group or updates existing one
    - **Read:** `GET /hostedpages-srv/hpgroup` (list all) or `GET /hostedpages-srv/hpgroup/{id}` (get by ID)
    - **Update:** `POST /hostedpages-srv/hpgroup` (same as create, updates if ID exists)
    - **Delete:** `DELETE /hostedpages-srv/hpgroup/{id}` - Removes the entire hosted pages group

    **Individual Hosted Pages:**
    - **Create:** `POST /hostedpages-srv/hpgroup/{id}` - Adds a new hosted page to an existing group
    - **Read:** `GET /hostedpages-srv/hpgroup/{id}/{hpid}` - Retrieves a specific hosted page with locale support
    - **Update:** `POST /hostedpages-srv/hpgroup/{id}` - Updates an existing hosted page in the group
    - **Delete:** `DELETE /hostedpages-srv/hpgroup/{id}/{hpid}` - Removes a specific hosted page from the group

    **Themes:**
    - **Create:** `POST /hostedpages-srv/themes` - Uploads a new theme CSS file
    - **Read:** `GET /hostedpages-srv/themes` (list all) or `GET /hostedpages-srv/themes/{filename}` (get specific theme)
    - **Update:** Upload a new version with the same filename using `POST /hostedpages-srv/themes`
    - **Delete:** `DELETE /hostedpages-srv/themes/{filename}` - Removes a theme file
    - **Learn more:** [Theming Guide](../../../guides/hosted-pages/hosted-pages-theming)

    **Translations:**
    - **Create:** `POST /hostedpages-srv/translations` - Creates a new translation for a locale
    - **Read:** `GET /hostedpages-srv/translations` (list all) or `GET /hostedpages-srv/translations/{localeId}` (get specific)
    - **Update:** `PUT /hostedpages-srv/translations/{localeId}` - Updates an existing translation
    - **Delete:** `DELETE /hostedpages-srv/translations/{localeId}` - Removes a translation
    - **Learn more:** [Translation Guide](../../../guides/hosted-pages/hosted-pages-translation)

    **Hosted Page Layouts (cidaas 4.x):**

    Applications reference a layout via `hosted_pages_layout_id` on the [App Configuration API](/openapi/app-configuration/app-configuration-api). Each layout includes branding and a `layout.hosted_page_group` reference to a hosted page group.

    - **List:** `GET /hostedpages-srv/hosted-page-layouts` — paginated list (`from`, `size` query params)
    - **Create:** `POST /hostedpages-srv/hosted-page-layouts` — creates a layout (returns 201)
    - **Read:** `GET /hostedpages-srv/hosted-page-layouts/{id}` — get by ID (**matches `hosted_pages_layout_id`**)
    - **Update:** `PUT /hostedpages-srv/hosted-page-layouts/{id}` — full update
    - **Delete:** `DELETE /hostedpages-srv/hosted-page-layouts/{id}` — removes a layout
    - **Search:** `POST /hostedpages-srv/graph/hosted-page-layouts` — graph filter search

    **Learn more:** [Hosted Pages Management](/guides/hosted-pages/hosted-pages-management)
  termsOfService: 'https://www.cidaas.com/terms-of-use/'
  summary: cidaas hosted pages api
tags:
  - name: Hosted Page
  - name: Hosted Pages Group
  - name: Hosted Page Layouts
  - name: hostedpages-srv
  - name: Hosted Pages Themes
servers:
  - url: 'https://{host}/'
    description: Enter your host name
    variables:
      host:
        default: demo.cidaas.de
        description: Your cidaas host name
  - url: 'https://demo.cidaas.de'
    description: Demo environment
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://domain/authz-srv/authz'
          tokenUrl: 'https://domain/token-srv/token'
          scopes:
            'cidaas:hosted_pages_read': Provides read access for a hosted pages group.
            'cidaas:hosted_pages_write': Provides write access for a hosted pages group.
            'cidaas:hosted_pages_delete': Provides delete access for a hosted pages group.
            'cidaas:themes_read': Provides read access to themes
            'cidaas:themes_write': Provides write access to themes
            'cidaas:themes_delete': Provides delete access to themes
          refreshUrl: ''
        clientCredentials:
          tokenUrl: 'https://domain/token-srv/token'
          scopes:
            'cidaas:hosted_pages_read': Provides read access for a hosted pages group.
            'cidaas:hosted_pages_write': Provides write access for a hosted pages group.
            'cidaas:hosted_pages_delete': Provides delete access for a hosted pages group.
            'cidaas:admin_write': Used for the seeding of the default hosted pages group.
            'cidaas:themes_read': Provides read access to themes
            'cidaas:themes_write': Provides write access to themes
            'cidaas:themes_delete': Provides delete access to themes
        implicit:
          authorizationUrl: 'https://domain/authz-srv/authz'
          scopes:
            'cidaas:hosted_pages_read': read access for hosted pages group
            'cidaas:hosted_pages_write': write access for hosted pages group
            'cidaas:hosted_pages_delete': delete access for hosted pages group
            'cidaas:themes_read': Provides read access to themes
            'cidaas:themes_write': Provides write access to themes
            'cidaas:themes_delete': Provides delete access to themes
  parameters:
    id:
      name: id
      in: path
      required: true
      description: The unique id of a hosted pages group.
      schema:
        type: string
      x-cid-variables:
        - type: load
          name: groupId
    hpid:
      name: hpid
      in: path
      required: true
      description: The unique id of a hosted page (e.g., "login", "register", "mfa_required").
      schema:
        type: string
      x-cid-variables:
        - type: load
          name: pageId
    locale:
      name: locale
      in: query
      required: false
      description: |
        The locale to identify a hosted page. Follows ISO locale format (e.g., "en-US", "de-DE", "fr-FR").
        If not provided, the system will use the Accept-Language header or default locale.
      schema:
        type: string
        pattern: '^[a-z]{2}([_-])?([A-Za-z]{2})?$'
      example: en-US
    filename:
      name: filename
      in: path
      required: true
      description: The filename of the theme (e.g., "custom.css", "brand-theme.css").
      schema:
        type: string
paths:
  /hostedpages-srv/hpgroup:
    get:
      x-cid-order-id: 2
      tags:
        - Hosted Pages Group
      description: |
        This API call finds all hosted page groups or those with specific hosted pages for the given ID and/or owner type.

        Use this endpoint to:
        - List all hosted page groups in your tenant
        - Filter by specific hosted page ID (e.g., "login", "register")
        - Filter by owner type (admin, client, or system)
        - Combine filters to find specific groups

        **Related Documentation:**
        - [Hosted Pages Overview](/guides/hosted-pages/hosted-pages-management)
        - [Creating Hosted Pages Groups](/guides/hosted-pages/hosted-pages-management#how-to-create-a-hosted-pages-group)
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_read'
      parameters:
        - name: pageId
          in: query
          required: false
          description: The hosted page id or identifier for looking up a page in the hosted pages group.
          schema:
            type: string
          x-cid-variables:
            - type: load
              name: pageId
        - name: ownerType
          in: query
          required: false
          description: The hosted page owner type used for looking up a page in the hosted pages group.
          schema:
            type: string
            enum:
              - admin
              - client
              - system
            example: admin
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./hostedpages/models/hostedPageGroupsResponse.yaml
        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: UNAUTHORIZED
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '404':
          description: NOT_FOUND
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
      summary: Get Hosted Pages Groups
      operationId: GetHostedPagesGroups
    post:
      x-cid-order-id: 1
      tags:
        - Hosted Pages Group
      description: |
        This API call creates or updates a hosted pages group.

        **Creating a New Group:**
        - Omit the `_id` field to create a new hosted pages group
        - Provide `groupOwner` (admin, client, or system)
        - Set `default_locale` (e.g., "en-US", "de-DE")
        - Include an array of `hosted_pages` with their URLs and locales

        **Updating an Existing Group:**
        - Include the `_id` field of the existing group
        - Provide updated fields (all fields will be updated)
        - Returns 200 if updated, 201 if created

        **Hosted Page Types:**
        Supported types include: login, register, login_success, register_success, password_forgot_init, 
        password_set, password_set_success, verification_init, verification_complete, mfa_required, 
        consent_preview, consent_scopes, logout_success, account_deduplication, and more.

        **Related Documentation:**
        - [Hosted Pages Overview](/guides/hosted-pages/hosted-pages-management)
        - [Mapping Hosted Pages to Apps](/guides/hosted-pages/hosted-pages-management#how-to-map-hosted-pages-to-an-app)
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_write'
      operationId: storeHostedPageGroup
      requestBody:
        required: true
        description: The Hosted Pages Group to be added or updated.
        content:
          application/json:
            schema:
              $ref: ./hostedpages/models/hostedPageGroup.yaml
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./hostedpages/models/hostedPageGroupResponse.yaml
          x-cid-variables:
            - type: save
              path: data._id
              name: groupId
            - type: save
              path: data.hosted_pages.0.hosted_page_id
              name: pageId
        '201':
          description: CREATED
          content:
            application/json:
              schema:
                $ref: ./hostedpages/models/hostedPageGroupResponse.yaml
          x-cid-variables:
            - type: save
              path: data._id
              name: groupId
            - type: save
              path: data.hosted_pages.0.hosted_page_id
              name: pageId
        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: UNAUTHORIZED
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
      summary: Store the Hosted Pages Group
    parameters: []
  '/hostedpages-srv/hpgroup/{id}':
    get:
      summary: Get Hosted Pages by Group
      operationId: GetHostedPageGroup
      parameters:
        - $ref: '#/components/parameters/id'
      tags:
        - Hosted Pages Group
      description: |
        This API call retrieves the hosted page group for the specified ID.

        Returns the complete hosted pages group including:
        - Group metadata (ID, creation/update times, owner type)
        - Default locale setting
        - All hosted pages in the group with their URLs and locales

        **Related Documentation:**
        - [Hosted Pages Overview](/guides/hosted-pages/hosted-pages-management)
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_read'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./hostedpages/models/hostedPageGroupResponse.yaml
        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: UNAUTHORIZED
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '404':
          description: RESOURCE NOT FOUND - Hosted Pages Group.
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
    post:
      x-cid-order-id: 3
      parameters:
        - $ref: '#/components/parameters/id'
      tags:
        - Hosted Page
      description: |
        This API call adds or updates a hosted page to the specified hosted page group.

        **Adding a New Hosted Page:**
        - Provide a `hosted_page_id` (e.g., "login", "register")
        - Specify the `locale` (e.g., "en-US", "de-DE")
        - Provide the `url` where the hosted page is served

        **Updating an Existing Hosted Page:**
        - Use the same `hosted_page_id` and `locale` combination
        - Provide updated `url` or other fields
        - The existing page will be replaced with the new data

        **Note:** Each hosted page is uniquely identified by the combination of `hosted_page_id` and `locale` within a group.

        **Related Documentation:**
        - [Hosted Pages Overview](/guides/hosted-pages/hosted-pages-management)
        - [Available Hosted Pages](/guides/hosted-pages/hosted-pages-management#available-hosted-pages)
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_write'
      requestBody:
        required: true
        description: Indicates the hosted page to be added or updated.
        content:
          application/json:
            schema:
              $ref: ./hostedpages/models/hostedPage.yaml
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./hostedpages/models/hostedPageResponse.yaml
        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: UNAUTHORIZED
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '404':
          description: RESOURCE NOT FOUND - Hosted Pages Group.
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
      summary: Stores a Hosted Page in the Hosted Pages Group.
      operationId: StoreHostedPageInHPGroup
    delete:
      x-cid-order-id: 6
      parameters:
        - $ref: '#/components/parameters/id'
      tags:
        - Hosted Pages Group
      description: |
        This API call deletes the hosted page group for the specified ID.

        **Warning:** This operation permanently removes the entire hosted pages group and all hosted pages within it.
        Make sure no applications are currently using this group before deletion.

        **Related Documentation:**
        - [Hosted Pages Overview](/guides/hosted-pages/hosted-pages-management)
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_delete'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./hostedpages/models/hostedPageGroupResponse.yaml
        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: UNAUTHORIZED
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '404':
          description: RESOURCE NOT FOUND - Hosted Pages Group
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
      summary: Deletes the Hosted Pages Group.
      operationId: DeleteHostedPageGroup
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: The unique id of a hosted pages group.
  '/hostedpages-srv/hpgroup/{id}/{hpid}':
    delete:
      x-cid-order-id: 5
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/hpid'
        - $ref: '#/components/parameters/locale'
      description: |
        This API call deletes the hosted page with the specified `hpid` and `locale` from the hosted pages group.

        **Parameters:**
        - `id`: The hosted pages group ID
        - `hpid`: The hosted page ID (e.g., "login", "register")
        - `locale` (query, optional): The locale of the hosted page to delete. If not provided, all locales for the given `hpid` will be deleted.

        **Note:** This removes only the specific hosted page(s) from the group, not the entire group.

        **Related Documentation:**
        - [Hosted Pages Overview](/guides/hosted-pages/hosted-pages-management)
      operationId: deleteHostedPage
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_delete'
      tags:
        - Hosted Page
      responses:
        '200':
          description: OK
        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: UNAUTHORIZED
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '404':
          description: RESOURCE NOT FOUND - Hosted Page or hosted page not found.
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
      summary: Remove a Hosted Page from the Hosted Pages Group.
    get:
      x-cid-order-id: 4
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/hpid'
        - $ref: '#/components/parameters/locale'
      description: |
        This API call determines the hosted page for the given ID with locales from the Accept-Language header or query parameter.

        **Locale Resolution:**
        - If `locale` query parameter is provided, it takes precedence
        - Otherwise, uses the `Accept-Language` HTTP header
        - Falls back to the group's `default_locale` if no match is found

        **Use Cases:**
        - Retrieve the correct hosted page URL for a specific page type and locale
        - Support multi-language applications by dynamically selecting the appropriate page
        - Get page configuration for rendering in your application

        **Related Documentation:**
        - [Hosted Pages Overview](/guides/hosted-pages/hosted-pages-management)
        - [Translation Guide](../../../guides/hosted-pages/hosted-pages-translation)
      operationId: getHostedPage
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_read'
      tags:
        - Hosted Page
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./hostedpages/models/hostedPageResponse.yaml
        '400':
          description: BAD_REQUEST
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: UNAUTHORIZED
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '404':
          description: RESOURCE NOT FOUND - Hosted Page or hosted page not found.
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
      summary: Fetch a Hosted Page from the Hosted Pages Group.
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: The unique id of a hosted pages group.
      - schema:
          type: string
        name: hpid
        in: path
        required: true
        description: The unique id of a hosted page
      - schema:
          type: string
        name: locale
        in: query
        required: false
  /hostedpages-srv/themes:
    get:
      summary: Get Themes
      tags:
         - Theming
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    x-stoplight:
                      id: 6eejiufc4t52l
                    default: true
                    description: 'True, if operation is successful'
                  status:
                    type: integer
                    x-stoplight:
                      id: yvqgoyn2ibm5g
                    description: Https status code
                    example: 200
                  data:
                    type: array
                    x-stoplight:
                      id: xaetv36qaedlz
                    description: List of available themes
                    items:
                      x-stoplight:
                        id: f22a2xezahsl8
                      type: string
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                $ref: ./common/models/errorResponse.yaml
      operationId: get-hostedpages-srv-themes
      x-stoplight:
        id: qtm8nagd40aig
      description: |
        This API call retrieves a list of available themes.

        Returns all theme filenames that can be used to customize the visual appearance of hosted pages.
        Themes are CSS files that define styling variables for colors, typography, spacing, borders, and more.

        **Use Cases:**
        - Display available themes in admin UI for selection
        - Check which themes are available before mapping to an app
        - List all custom themes uploaded by administrators

        **Related Documentation:**
        - [Theming Guide](/guides/hosted-pages/hosted-pages-theming) - Complete guide on customizing hosted pages appearance
        - [Apply Themes to Apps](/guides/hosted-pages/hosted-pages-theming#apply-your-theme-in-apps)
      security:
        - OAuth2:
            - 'cidaas:themes_read'
      requestBody:
        content:
          application/json:
            schema:
              type: object
    post:
      summary: Upload New Theme
      tags:
         - Theming
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    x-stoplight:
                      id: z72acxznantrv
                    description: 'True, if operation is successful.'
                  status:
                    type: integer
                    x-stoplight:
                      id: pwhqotlxh8avp
                    example: 200
                    description: Https status code
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      operationId: post-hostedpages-srv-themesui
      x-stoplight:
        id: ugky310d8q7f8
      description: |
        This API call uploads a new theme file (e.g., custom.css) via form data to add custom themes to the available themes list.

        **Theme File Format:**
        - Upload CSS files containing CSS custom properties (variables) prefixed with `--cid-`
        - Define variables for typography, colors, spacing, borders, shadows, and more
        - See the theming guide for complete list of available variables

        **Request Format:**
        - Use `multipart/form-data` content type
        - Include a `theme` field with the CSS file path or file content
        - Example: `theme: @"path/to/custom.css"`

        **Updating Themes:**
        - Upload a new file with the same filename to replace an existing theme
        - All apps using that theme will automatically use the updated version

        **Related Documentation:**
        - [Theming Guide](../../../guides/hosted-pages/hosted-pages-theming) - Complete reference for all theme variables
        - [Create New Themes](../../../guides/hosted-pages/hosted-pages-theming#create-new-hosted-pages-themes)
        - [Theming Examples](../../../guides/hosted-pages/hosted-pages-theming#how-it-would-look)
      security:
        - OAuth2:
            - 'cidaas:themes_write'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                theme:
                  type: string
                  x-stoplight:
                    id: bmpt71qcyl8z4
                  description: The theme parameter should contain the path to the CSS file you wish to upload.
                  example: '@"yourDirectory/custom.css"'
    parameters: []
  '/hostedpages-srv/themes/{filename}':
    parameters:
      - schema:
          type: string
        name: filename
        in: path
        required: true
        description: desired theme’s filename
    get:
      summary: Get Theme by Filename
      tags:
         - Theming
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    x-stoplight:
                      id: kq8j4kgk5a8li
                    default: true
                    description: 'True, if operation is successful.'
                  status:
                    type: integer
                    x-stoplight:
                      id: ny59jeuvx3313
                    description: Https status code
                  data:
                    type: array
                    x-stoplight:
                      id: x9cafhfa8krbj
                    description: list of spec of the themes
                    items:
                      x-stoplight:
                        id: xhwm3lh19jvya
                      type: string
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                $ref: ./common/models/errorResponse.yaml
      operationId: get-hostedpages-srv-themes-filename
      x-stoplight:
        id: ejuuflhk664sb
      description: |
        This API call fetches a specific theme by filename. Replace `{filename}` in the URL with the desired theme filename.

        Returns the CSS content of the specified theme file, which can be used to:
        - Preview theme styling
        - Edit existing themes
        - Understand theme structure
        - Validate theme syntax

        **Related Documentation:**
        - [Theming Guide](../../../guides/hosted-pages/hosted-pages-theming) - Complete reference for theme variables
        - [Theme Variables Reference](../../../guides/hosted-pages/hosted-pages-theming#theming-options-flexibility-to-customize-the-default-hosted-pages)
      security:
        - OAuth2:
            - 'cidaas:themes_read'
    delete:
      summary: Delete Theme by Filename
      tags:
         - Theming
      parameters:
        - schema:
            type: string
          name: filename
          in: path
          required: true
          description: The filename of the theme to delete (e.g., "custom.css", "brand-theme.css")
      description: |
        This API call deletes a specific theme by filename.

        **Warning:** This permanently removes the theme file. Make sure no applications are currently using this theme before deletion.

        **Related Documentation:**
        - [Theming Guide](../../../guides/hosted-pages/hosted-pages-theming)
      operationId: delete-hostedpages-srv-themes-filename
      security:
        - OAuth2:
            - 'cidaas:themes_delete'
      responses:
        '200':
          description: OK - Theme successfully deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: 'True, if operation is successful.'
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '404':
          description: Theme not found
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
  /hostedpages-srv/hosted-page-layouts:
    get:
      summary: List hosted page layouts
      operationId: ListHostedPageLayouts
      x-cid-order-id: 1
      tags:
        - Hosted Page Layouts
      description: |
        Returns hosted page layouts with pagination.

        Requires `cidaas:hosted_pages_read` or `cidaas:themes_read`.
      parameters:
        - name: from
          in: query
          schema:
            type: integer
            default: 0
          description: Result offset.
        - name: size
          in: query
          schema:
            type: integer
            default: 50
          description: Page size (max 100).
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_read'
            - 'cidaas:themes_read'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: ./hosted-page-layouts/HostedPageLayoutListResponse.yaml
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
    post:
      summary: Create hosted page layout
      operationId: CreateHostedPageLayout
      x-cid-order-id: 2
      tags:
        - Hosted Page Layouts
      description: |
        Creates a hosted page layout. Server assigns `id`, `fingerprint`, and timestamps. `groupId` is set from token claims.

        `description` and `layout` are required. Set `layout.hosted_page_group` to link a [Hosted Page Group](./hosted-pages-api).

        Requires `cidaas:hosted_pages_write` or `cidaas:themes_write`.
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_write'
            - 'cidaas:themes_write'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./hosted-page-layouts/HostedPageLayoutEntity.yaml
            examples:
              default-layout:
                summary: Layout with branding and hosted page group
                value:
                  description: Default login branding
                  layout:
                    hosted_page_group: default
                    primary_color: '#0066CC'
                    accent_color: '#FF6600'
                    logo_align: CENTER
                    content_align: CENTER
      responses:
        '201':
          description: Created successfully
          content:
            application/json:
              schema:
                $ref: ./hosted-page-layouts/HostedPageLayoutResponse.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '409':
          description: Conflict — layout with the same fingerprint already exists
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
  '/hostedpages-srv/hosted-page-layouts/{id}':
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Hosted page layout identifier. This is the value stored in `hosted_pages_layout_id` on an application.
    get:
      summary: Get hosted page layout by ID
      operationId: GetHostedPageLayout
      x-cid-order-id: 3
      tags:
        - Hosted Page Layouts
      description: |
        Retrieves a hosted page layout by ID. This is the record referenced by `hosted_pages_layout_id` on app configurations.

        Requires `cidaas:hosted_pages_read` or `cidaas:themes_read`.
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_read'
            - 'cidaas:themes_read'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: ./hosted-page-layouts/HostedPageLayoutResponse.yaml
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
    put:
      summary: Update hosted page layout
      operationId: UpdateHostedPageLayout
      x-cid-order-id: 4
      tags:
        - Hosted Page Layouts
      description: |
        Full update of a hosted page layout. Layouts with owner `core` or `system` cannot be updated.

        Requires `cidaas:hosted_pages_write` or `cidaas:themes_write`.
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_write'
            - 'cidaas:themes_write'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./hosted-page-layouts/HostedPageLayoutEntity.yaml
      responses:
        '200':
          description: Updated successfully
          content:
            application/json:
              schema:
                $ref: ./hosted-page-layouts/HostedPageLayoutResponse.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '403':
          description: Forbidden — protected layout (owner core/system)
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '409':
          description: Conflict — duplicate fingerprint
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
    delete:
      summary: Delete hosted page layout
      operationId: DeleteHostedPageLayout
      x-cid-order-id: 5
      tags:
        - Hosted Page Layouts
      description: |
        Deletes a hosted page layout. Layouts with owner `core` or `system` cannot be deleted. Returns an error if the layout is still referenced by applications.

        Requires `cidaas:hosted_pages_delete` or `cidaas:themes_delete`.
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_delete'
            - 'cidaas:themes_delete'
      responses:
        '200':
          description: Deleted successfully
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '403':
          description: Forbidden — protected or referenced layout
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
  /hostedpages-srv/graph/hosted-page-layouts:
    post:
      summary: Graph search hosted page layouts
      operationId: GraphSearchHostedPageLayouts
      x-cid-order-id: 6
      tags:
        - Hosted Page Layouts
      description: |
        Search hosted page layouts using the generic graph filter.

        Requires `cidaas:hosted_pages_read` or `cidaas:themes_read`.
      security:
        - OAuth2:
            - 'cidaas:hosted_pages_read'
            - 'cidaas:themes_read'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./hosted-page-layouts/GraphHostedPageLayoutRequest.yaml
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: ./hosted-page-layouts/HostedPageLayoutListResponse.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ./common/models/errorResponse.yaml