Showpad Themes API

openapi: 3.2.0
info:
  title: Showpad Themes API
  description: 'This [OAS](https://swagger.io/specification/) document is intended for developers or engineers who will be

    integrating their platform with Showpad API.


    The base URL of this API is patterned as `https://{subdomain}.api.showpad.com/v4` where `{subdomain}` is the

    provided subdomain of the customer, i.e., `https://xyz-org.api.showpad.com/v4` will be the API base URL of a

    customer that has a `xyz-org` subdomain.

    '
  version: '4'
  termsOfService: https://www.showpad.com/terms-of-service
  contact:
    name: Showpad
    email: support@showpad.com
    url: https://help.showpad.com/hc/en-us/requests/new
  x-serviceName: Showpad API
  x-logo:
    url: ./Showpad-logo-vertical-blue.png
    altText: Showpad Developer API
  x-audience: external-partner
servers:
- url: https://{subdomain}.api.showpad.com/v4
  description: Production server
  x-environment: production
  variables:
    subdomain:
      default: customer
      description: Showpad customer subdomain
tags:
- name: themes
  x-displayName: Themes
  description: These are endpoints for managing Themes
paths:
  /themes:
    get:
      operationId: theme-list
      summary: List of Themes
      description: 'Retrieve a list of themes available in your Showpad instance. Themes include branding configurations, layout styles, and visual assets used to customize the platform interface.


        Use this endpoint when you need to:

        - Fetch a paginated collection of design configurations for your organization.

        - Look up specific theme details by filtering results using a title string.

        - Organize theme collections using predefined sorting fields like creation or modification dates.


        This endpoint supports pagination constraints via limit and offset parameters and allows filtering.'
      tags:
      - themes
      security:
      - BearerAuth: []
      parameters:
      - schema:
          type: string
        required: false
        name: divisionId
        in: query
        description: Filters the results to include only those that belong to a specific Division. This is useful for multi-division organizations to retrieve visual styles scoped to particular business units or regions.
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
        required: false
        name: includeGlobal
        in: query
        description: Controls whether the Global Theme is included in the response. Use `includeGlobal=true` to include the Global Theme in the results, regardless of `divisionId` filter. If not provided, defaults to false.
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
        required: false
        name: isDefault
        in: query
        description: Controls whether the response filters by the theme's default status attribute. Use `isDefault=true` to return only the default organization theme. If not provided, defaults to false.
      - schema:
          type: string
        required: false
        name: title
        in: query
        description: Filters results by the theme's title. Returns only the themes where the `title` contains the specified string value.
      - schema:
          type: string
          enum:
          - title
          - -title
          - createdAt
          - -createdAt
          - updatedAt
          - -updatedAt
          default: -createdAt
        required: false
        name: sort
        in: query
        description: Specifies the field and direction used to sort the results. Prefix the field name with a hyphen (`-`) for descending sort order.
      - schema:
          type: integer
          default: '50'
          description: Defines the maximum number of results to return in a single response. Use in combination with `offset` to implement pagination when retrieving large datasets in batches.
          minimum: 1
          maximum: 1000
        required: false
        description: Defines the maximum number of results to return in a single response. Use in combination with `offset` to implement pagination when retrieving large datasets in batches.
        name: limit
        in: query
      - schema:
          type: integer
          default: '0'
          description: Specifies the number of results to skip before starting to return data. Use in combination with `limit` to implement pagination when retrieving large datasets.
          minimum: 0
        required: false
        description: Specifies the number of results to skip before starting to return data. Use in combination with `limit` to implement pagination when retrieving large datasets.
        name: offset
        in: query
      responses:
        '200':
          description: The request was successful. Returns a paginated collection of available themes, including their configurations, color properties, and visual metadata.
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                - items
                properties:
                  count:
                    type: integer
                  items:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - title
                      - isGlobal
                      - isDefault
                      - displayData
                      - colorSettings
                      - createdAt
                      - updatedAt
                      - division
                      properties:
                        id:
                          type: string
                          description: The unique identifier of the theme.
                        title:
                          type: string
                          description: The display name of the theme.
                        isGlobal:
                          type: boolean
                          description: Indicates whether the theme is a Global Theme. A Global Theme is available to all users across all Divisions.
                        isDefault:
                          type: boolean
                          description: Controls whether the theme is set as the default option within its designated Division. The default theme is automatically assigned to all experiences in that Division. A Global Theme cannot be marked as default, meaning this value remains false for global entities. Only one theme can be configured as the default per Division.
                        displayData:
                          type: object
                          required:
                          - aboutDescription
                          - logo
                          - displayImage
                          properties:
                            aboutDescription:
                              type: string
                              maxLength: 800
                              description: The descriptive text displayed within the Shared Content Viewer. This property does not apply to Shared Spaces, which lack an about section.
                            logo:
                              type:
                              - object
                              - 'null'
                              required:
                              - url
                              properties:
                                url:
                                  type: string
                            displayImage:
                              type:
                              - object
                              - 'null'
                              required:
                              - url
                              properties:
                                url:
                                  type: string
                        colorSettings:
                          type: object
                          required:
                          - headerColor
                          - headerFontColor
                          - accentColor
                          - accentFontColor
                          description: A collection of hex color codes that define the theme's color palette across different user interface components.
                          properties:
                            headerColor:
                              type: string
                              maxLength: 6
                              example: F6F6F6
                              description: The hex code configuration for the interface header background color. Do not include a leading hashtag (#).
                            headerFontColor:
                              type: string
                              maxLength: 6
                              example: F6F6F6
                              description: The hex code configuration for text overlay elements inside the header background. Do not include a leading hashtag (#).
                            accentColor:
                              type: string
                              maxLength: 6
                              example: F6F6F6
                              description: The hex code configuration for primary buttons, highlights, and interactive accents. Do not include a leading hashtag (#).
                            accentFontColor:
                              type: string
                              maxLength: 6
                              example: F6F6F6
                              description: The hex code configuration for text overlay elements placed on top of accent-colored components. Do not include a leading hashtag (#).
                        createdAt:
                          type: string
                          format: date-time
                          description: The date and time when the theme was created.
                          example: '2019-08-24T14:15:22Z'
                        updatedAt:
                          type: string
                          format: date-time
                          description: The date and time when the theme was last modified.
                          example: '2019-08-24T14:15:22Z'
                        division:
                          type:
                          - object
                          - 'null'
                          required:
                          - id
                          description: The scope of the Division to which this theme is assigned. This object returns `NULL` exclusively for a Global Theme, as global configurations are available across all business units.
                          properties:
                            id:
                              type: string
                              description: The unique identifier of the scoping Division. This parent object returns `NULL` exclusively for a Global Theme.
        '401':
          description: Unauthorized. The request lacks valid authentication credentials, or the provided token has expired.
          content:
            application/problem+json:
              schema:
                type: object
                required:
                - title
                - detail
                - status
                - type
                properties:
                  id:
                    type: string
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  title:
                    type: string
                    description: "A short summary of the problem type. Written in English and readable\n        for engineers (usually not suited for non-technical stakeholders and\n        not localized)."
                    example: Invalid payload
                  detail:
                    type: string
                    description: A human readable explanation specific to this occurrence of the problem
                    example: Property value provided is not a valid.
                  status:
                    type: integer
                    format: int32
                    description: The HTTP status code generated by the origin server for this occurrence of the problem.
                    minimum: 400
                    maximum: 599
                    example: 400
                  meta:
                    type: array
                    description: Additional information to support the error
                    items:
                      type: object
                      required:
                      - name
                      - reason
                      - category
                      description: Additional payload to support the encountered error.
                      properties:
                        name:
                          type: string
                          description: The name of the affected resource attribute.
                          example: color
                        reason:
                          type: string
                          description: The explanation of the problem.
                          example: Value must be 'green', 'red' or 'blue'.
                        category:
                          type: string
                          description: The error category.
                          example: propertyRequired
                  type:
                    type: string
                    pattern: ^(\/[a-z]+(-[a-z]+)*)+$
                    description: URI reference of the error.
                    example: /errors/not-found
        '403':
          description: Forbidden. The server understood the request but refuses to authorize it. The authenticated user does not have the necessary permissions to perform this action.
          content:
            application/problem+json:
              schema:
                type: object
                required:
                - title
                - detail
                - status
                - type
                properties:
                  id:
                    type: string
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  title:
                    type: string
                    description: "A short summary of the problem type. Written in English and readable\n        for engineers (usually not suited for non-technical stakeholders and\n        not localized)."
                    example: Invalid payload
                  detail:
                    type: string
                    description: A human readable explanation specific to this occurrence of the problem
                    example: Property value provided is not a valid.
                  status:
                    type: integer
                    format: int32
                    description: The HTTP status code generated by the origin server for this occurrence of the problem.
                    minimum: 400
                    maximum: 599
                    example: 400
                  meta:
                    type: array
                    description: Additional information to support the error
                    items:
                      type: object
                      required:
                      - name
                      - reason
                      - category
                      description: Additional payload to support the encountered error.
                      properties:
                        name:
                          type: string
                          description: The name of the affected resource attribute.
                          example: color
                        reason:
                          type: string
                          description: The explanation of the problem.
                          example: Value must be 'green', 'red' or 'blue'.
                        category:
                          type: string
                          description: The error category.
                          example: propertyRequired
                  type:
                    type: string
                    pattern: ^(\/[a-z]+(-[a-z]+)*)+$
                    description: URI reference of the error.
                    example: /errors/not-found
        default:
          description: An error occurred. See the HTTP status code and problem object for more information.
          content:
            application/problem+json:
              schema:
                type: object
                required:
                - title
                - detail
                - status
                - type
                properties:
                  id:
                    type: string
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  title:
                    type: string
                    description: "A short summary of the problem type. Written in English and readable\n        for engineers (usually not suited for non-technical stakeholders and\n        not localized)."
                    example: Invalid payload
                  detail:
                    type: string
                    description: A human readable explanation specific to this occurrence of the problem
                    example: Property value provided is not a valid.
                  status:
                    type: integer
                    format: int32
                    description: The HTTP status code generated by the origin server for this occurrence of the problem.
                    minimum: 400
                    maximum: 599
                    example: 400
                  meta:
                    type: array
                    description: Additional information to support the error
                    items:
                      type: object
                      required:
                      - name
                      - reason
                      - category
                      description: Additional payload to support the encountered error.
                      properties:
                        name:
                          type: string
                          description: The name of the affected resource attribute.
                          example: color
                        reason:
                          type: string
                          description: The explanation of the problem.
                          example: Value must be 'green', 'red' or 'blue'.
                        category:
                          type: string
                          description: The error category.
                          example: propertyRequired
                  type:
                    type: string
                    pattern: ^(\/[a-z]+(-[a-z]+)*)+$
                    description: URI reference of the error.
                    example: /errors/not-found
  /themes/{themeId}:
    get:
      operationId: theme-get
      summary: Get a Theme
      description: 'Retrieves the full configuration, color settings, visual assets, and metadata for a specific theme.


        This endpoint allows you to:

        - Fetch localized branding components for a specific business unit.

        - Verify active color configurations before rendering custom UI elements.

        - Access asset URLs for logos and cover images.'
      tags:
      - themes
      security:
      - BearerAuth: []
      responses:
        '200':
          description: The request was successful. Returns the detailed configuration, color properties, and asset metadata for the specified theme.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - title
                - isGlobal
                - isDefault
                - displayData
                - colorSettings
                - createdAt
                - updatedAt
                - division
                properties:
                  id:
                    type: string
                    description: The unique identifier of the theme.
                  title:
                    type: string
                    description: The display name of the theme.
                  isGlobal:
                    type: boolean
                    description: Indicates whether the theme is a Global Theme. A Global Theme is available to all users across all Divisions.
                  isDefault:
                    type: boolean
                    description: Controls whether the theme is set as the default option within its designated Division. The default theme is automatically assigned to all experiences in that Division. A Global Theme cannot be marked as default, meaning this value remains false for global entities. Only one theme can be configured as the default per Division.
                  displayData:
                    type: object
                    required:
                    - aboutDescription
                    - logo
                    - displayImage
                    properties:
                      aboutDescription:
                        type: string
                        maxLength: 800
                        description: The descriptive text displayed within the Shared Content Viewer. This property does not apply to Shared Spaces, which lack an about section.
                      logo:
                        type:
                        - object
                        - 'null'
                        required:
                        - url
                        properties:
                          url:
                            type: string
                      displayImage:
                        type:
                        - object
                        - 'null'
                        required:
                        - url
                        properties:
                          url:
                            type: string
                  colorSettings:
                    type: object
                    required:
                    - headerColor
                    - headerFontColor
                    - accentColor
                    - accentFontColor
                    description: A collection of hex color codes that define the theme's color palette across different user interface components.
                    properties:
                      headerColor:
                        type: string
                        maxLength: 6
                        example: F6F6F6
                        description: The hex code configuration for the interface header background color. Do not include a leading hashtag (#).
                      headerFontColor:
                        type: string
                        maxLength: 6
                        example: F6F6F6
                        description: The hex code configuration for text overlay elements inside the header background. Do not include a leading hashtag (#).
                      accentColor:
                        type: string
                        maxLength: 6
                        example: F6F6F6
                        description: The hex code configuration for primary buttons, highlights, and interactive accents. Do not include a leading hashtag (#).
                      accentFontColor:
                        type: string
                        maxLength: 6
                        example: F6F6F6
                        description: The hex code configuration for text overlay elements placed on top of accent-colored components. Do not include a leading hashtag (#).
                  createdAt:
                    type: string
                    format: date-time
                    description: The date and time when the theme was created.
                    example: '2019-08-24T14:15:22Z'
                  updatedAt:
                    type: string
                    format: date-time
                    description: The date and time when the theme was last modified.
                    example: '2019-08-24T14:15:22Z'
                  division:
                    type:
                    - object
                    - 'null'
                    required:
                    - id
                    description: The scope of the Division to which this theme is assigned. This object returns `NULL` exclusively for a Global Theme, as global configurations are available across all business units.
                    properties:
                      id:
                        type: string
                        description: The unique identifier of the scoping Division. This parent object returns `NULL` exclusively for a Global Theme.
                  experiences:
                    type: array
                    description: List of Experience IDs the theme is assigned to. This field is omitted for a Global Theme. For non-global themes, an empty list restricts access to administrators.
                    items:
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: string
                          example: 9c5f3aa0784df25db1db821354e337e9
                          description: The unique identifier of the Experience.
        '401':
          description: Unauthorized. The request lacks valid authentication credentials, or the provided token has expired.
          content:
            application/problem+json:
              schema:
                type: object
                required:
                - title
                - detail
                - status
                - type
                properties:
                  id:
                    type: string
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  title:
                    type: string
                    description: "A short summary of the problem type. Written in English and readable\n        for engineers (usually not suited for non-technical stakeholders and\n        not localized)."
                    example: Invalid payload
                  detail:
                    type: string
                    description: A human readable explanation specific to this occurrence of the problem
                    example: Property value provided is not a valid.
                  status:
                    type: integer
                    format: int32
                    description: The HTTP status code generated by the origin server for this occurrence of the problem.
                    minimum: 400
                    maximum: 599
                    example: 400
                  meta:
                    type: array
                    description: Additional information to support the error
                    items:
                      type: object
                      required:
                      - name
                      - reason
                      - category
                      description: Additional payload to support the encountered error.
                      properties:
                        name:
                          type: string
                          description: The name of the affected resource attribute.
                          example: color
                        reason:
                          type: string
                          description: The explanation of the problem.
                          example: Value must be 'green', 'red' or 'blue'.
                        category:
                          type: string
                          description: The error category.
                          example: propertyRequired
                  type:
                    type: string
                    pattern: ^(\/[a-z]+(-[a-z]+)*)+$
                    description: URI reference of the error.
                    example: /errors/not-found
        '403':
          description: Forbidden. The server understood the request but refuses to authorize it. The authenticated user does not have the necessary permissions to perform this action.
          content:
            application/problem+json:
              schema:
                type: object
                required:
                - title
                - detail
                - status
                - type
                properties:
                  id:
                    type: string
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  title:
                    type: string
                    description: "A short summary of the problem type. Written in English and readable\n        for engineers (usually not suited for non-technical stakeholders and\n        not localized)."
                    example: Invalid payload
                  detail:
                    type: string
                    description: A human readable explanation specific to this occurrence of the problem
                    example: Property value provided is not a valid.
                  status:
                    type: integer
                    format: int32
                    description: The HTTP status code generated by the origin server for this occurrence of the problem.
                    minimum: 400
                    maximum: 599
                    example: 400
                  meta:
                    type: array
                    description: Additional information to support the error
                    items:
                      type: object
                      required:
                      - name
                      - reason
                      - category
                      description: Additional payload to support the encountered error.
                      properties:
                        name:
                          type: string
                          description: The name of the affected resource attribute.
                          example: color
                        reason:
                          type: string
                          description: The explanation of the problem.
                          example: Value must be 'green', 'red' or 'blue'.
                        category:
                          type: string
                          description: The error category.
                          example: propertyRequired
                  type:
                    type: string
                    pattern: ^(\/[a-z]+(-[a-z]+)*)+$
                    description: URI reference of the error.
                    example: /errors/not-found
        '404':
          description: Not Found. Returned when the requested resource does not exist or the user does not have permission to access it.
          content:
            application/problem+json:
              schema:
                type: object
                required:
                - title
                - detail
                - status
                - type
                properties:
                  id:
                    type: string
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  title:
                    type: string
                    description: "A short summary of the problem type. Written in English and readable\n        for engineers (usually not suited for non-technical stakeholders and\n        not localized)."
                    example: Invalid payload
                  detail:
                    type: string
                    description: A human readable explanation specific to this occurrence of the problem
                    example: Property value provided is not a valid.
                  status:
                    type: integer
                    format: int32
                    description: The HTTP status code generated by the origin server for this occurrence of the problem.
                    minimum: 400
                    maximum: 599
                    example: 400
                  meta:
                    type: array
                    description: Additional information to support the error
                    items:
                      type: object
                      required:
                      - name
                      - reason
                      - category
                      description: Additional payload to support the encountered 

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/showpad/refs/heads/main/openapi/showpad-themes-api-openapi.yml