Acoustic Authoring layouts API

openapi: 3.2.0
info:
  title: Acoustic Authoring layouts API
  version: 1.0.142
  x-ibm-name: ibm-watson-content-hub-api
  description: 'Operations tagged Authoring layouts across 2 of this provider''s published API definitions: acoustic-content-openapi-original.json, acoustic-content-swagger2-original.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Authoring layouts
  description: 'Use the Content content authoring layout service Rest APIs to work with layouts and layout mappings.


    Layouts define the template for the type documents. They define the markup and how to add content properties and elements into the markup. For example, the layouts ''Article'', and ''Event'' would define what an article or event looks like on the web site, or email.


    Layout Mappings define an association between a content-type and one or more layouts. Specifically marking those layouts as valid for the given content-type.

    '
paths:
  /authoring/v1/layouts:
    post:
      tags:
      - Authoring layouts
      summary: Create new layouts.
      description: 'Use the /layouts end-point to create a new layout.<br />User roles: admin, manager'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: A new layout.
              properties:
                name:
                  type: string
                  description: The name of the layout.
                  pattern: ^[a-zA-Z0-9*. \-+_~$!',()]*$
                  minLength: 1
                  example: Sample layout
                description:
                  type: string
                  description: The description of the layout.
                  pattern: ^[a-zA-Z0-9*. \-+_~$!',()]*$
                  example: An example description of the sample layout
                classification:
                  type: string
                  description: Indicates the type of this document.
                  enum:
                  - layout
                created:
                  type: string
                  description: Optional creation date of this layout in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. Value is ignored if set in the future.
                  format: date-time
                path:
                  type: string
                  description: Optional path to associate with the layout. Must be unique. Will default to filesystem friendly version of /[NAME].
                  example: /myLayouts/SampleLayout.json
                prerender:
                  type: boolean
                  description: Indicates if the layout should be prerendered.
                  default: false
                  example: false
                tags:
                  type: array
                  items:
                    type: string
                  uniqueItems: true
                  example:
                  - news
                  - sample
                thumbnail:
                  type: object
                  description: 'The reference to the asset that should act as the thumbnail of this layout.

                    The thumbnail can be referred to by either id or path.

                    '
                  properties:
                    id:
                      type: string
                      description: The ID of the asset.
                      example: 6c622bbb-5f5b-45d4-89e1-fce1c054138f
                    path:
                      type: string
                      description: The path of the asset.
                      example: /sales/images/hub.png
                template:
                  type: string
                  minLength: 1
                  example: /mytemplates/template.hbs
                templateType:
                  type: string
                  description: Specifies the type of template associated with this layout. This field is required when prerender field is set to true.
                  enum:
                  - handlebars
                  - angular
                  default: handlebars
                  example: handlebars
                urlTemplate:
                  type: string
                  description: Specifies the pattern for url generation.
                isSystem:
                  type: boolean
                  description: Indicates whether this item is a 'system item' or not.
                  default: false
              required:
              - name
              - template
        description: Contains the layout to create.
        required: true
      responses:
        '201':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                description: An existing layout.
                properties:
                  id:
                    type: string
                    description: The ID of the layout.
                    pattern: ^[a-zA-Z0-9*.\-+_~$!',()]*$
                    minLength: 1
                    example: f26044ca-d92d-49e8-acd9-00563c1e0db9
                  rev:
                    type: string
                    description: The current revision of the layout.
                    minLength: 1
                    example: 139c63397272172e73f52d22f22f606f6c
                  name:
                    type: string
                    description: The name of the layout.
                    pattern: ^[a-zA-Z0-9*. \-+_~$!',()]*$
                    minLength: 1
                    example: Sample layout
                  description:
                    type: string
                    description: The description of the layout.
                    pattern: ^[a-zA-Z0-9*. \-+_~$!',()]*$
                    example: An example description of the sample layout
                  classification:
                    type: string
                    description: Indicates the type of this document.
                    enum:
                    - layout
                  creatorId:
                    type: string
                    description: The ID of the user that created the layout.
                    example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f
                  creator:
                    type: string
                    description: 'The display name of the user that created the layout. This field is only returned when the ''include'' query string option is set to ''ALL'' or ''metadata''.

                      This field is read only.

                      '
                    example: Thomas Watson
                  created:
                    type: string
                    description: The created date of this layout in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only.
                    format: date-time
                  lastModifierId:
                    type: string
                    description: The ID of the user that last modified the layout.
                    example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f
                  lastModifier:
                    type: string
                    description: 'The display name of the last user that modified the layout. This field is only returned when the ''include'' query string option is set to ''ALL'' or ''metadata''.

                      This field is read only.

                      '
                    example: Thomas Watson
                  lastModified:
                    type: string
                    description: The last modified date of this layout in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only.
                    format: date-time
                  path:
                    type: string
                    description: Optional path to associate with the layout. Must be unique. Will default to filesystem friendly version of /[NAME].
                    example: /myLayouts/SampleLayout.json
                  prerender:
                    type: boolean
                    description: Indicates if the layout should be prerendered.
                    default: false
                    example: false
                  tags:
                    type: array
                    items:
                      type: string
                    uniqueItems: true
                    example:
                    - news
                    - sample
                  thumbnail:
                    type: object
                    description: 'The reference to the asset that should act as the thumbnail of this layout.

                      The thumbnail can be referred to by either id or path.

                      '
                    properties:
                      id:
                        type: string
                        description: The ID of the asset.
                        example: 6c622bbb-5f5b-45d4-89e1-fce1c054138f
                      path:
                        type: string
                        description: 'The path of the asset. This field is only returned when the ''include'' query string option is set to ''ALL'' or ''metadata''.

                          This field is read only.

                          '
                        example: /sales/images/hub.png
                      url:
                        type: string
                        description: 'The URL of the asset. This field is only returned when the ''include'' query string option is set to ''ALL'' or ''metadata''.

                          This field is read only.

                          '
                        example: /authoring/v1/resources/d45c83a8-2738-48a2-89e1-35256ee16283.jpg
                  template:
                    type: string
                    minLength: 1
                    example: /mytemplates/template.hbs
                  templateType:
                    type: string
                    description: Specifies the type of template associated with this layout. This field is required when prerender field is set to true.
                    enum:
                    - handlebars
                    - angular
                    default: handlebars
                    example: handlebars
                  urlTemplate:
                    type: string
                    description: Specifies the pattern for url generation.
                  isSystem:
                    type: boolean
                    description: Indicates whether this item is a 'system item' or not.
                    default: false
                required:
                - rev
                - name
                - template
        '400':
          description: Empty body or Invalid input.
          content:
            application/json:
              schema:
                type: object
                description: an error response.
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      description: an individual error, info or warning message.
                      properties:
                        code:
                          type: integer
                          description: The message code.
                        key:
                          type: string
                          description: The message key.
                        message:
                          type: string
                          description: The error message.
                        description:
                          type: string
                          description: Optional detailed error message.
                        more_info:
                          type: string
                          description: Optional additional information for the message.
                        category:
                          type: string
                          description: The message category whereby only user messages are designed to be shown to an end user.
                          enum:
                          - API
                          - USER
                        level:
                          type: string
                          description: Indicates the message level.
                          enum:
                          - INFO
                          - WARNING
                          - ERROR
                        parameters:
                          type: object
                          description: The message parameters of this message.
                        field:
                          type: string
                          description: Only present on field validation errors, indicates the field in error.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                  requestId:
                    type: string
                    description: The current request ID.
                  service:
                    type: string
                    description: The name of the service that produced the error.
                  requestMethod:
                    type: string
                    description: The Http method type of the current request.
                  requestUri:
                    type: string
                    description: The current request uri.
        '403':
          description: The operation is not available based on the current tenant's tier.
          content:
            application/json:
              schema:
                type: object
                description: an error response.
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      description: an individual error, info or warning message.
                      properties:
                        code:
                          type: integer
                          description: The message code.
                        key:
                          type: string
                          description: The message key.
                        message:
                          type: string
                          description: The error message.
                        description:
                          type: string
                          description: Optional detailed error message.
                        more_info:
                          type: string
                          description: Optional additional information for the message.
                        category:
                          type: string
                          description: The message category whereby only user messages are designed to be shown to an end user.
                          enum:
                          - API
                          - USER
                        level:
                          type: string
                          description: Indicates the message level.
                          enum:
                          - INFO
                          - WARNING
                          - ERROR
                        parameters:
                          type: object
                          description: The message parameters of this message.
                        field:
                          type: string
                          description: Only present on field validation errors, indicates the field in error.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                  requestId:
                    type: string
                    description: The current request ID.
                  service:
                    type: string
                    description: The name of the service that produced the error.
                  requestMethod:
                    type: string
                    description: The Http method type of the current request.
                  requestUri:
                    type: string
                    description: The current request uri.
        '404':
          description: Current tenant's database is not provisioned.
          content:
            application/json:
              schema:
                type: object
                description: an error response.
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      description: an individual error, info or warning message.
                      properties:
                        code:
                          type: integer
                          description: The message code.
                        key:
                          type: string
                          description: The message key.
                        message:
                          type: string
                          description: The error message.
                        description:
                          type: string
                          description: Optional detailed error message.
                        more_info:
                          type: string
                          description: Optional additional information for the message.
                        category:
                          type: string
                          description: The message category whereby only user messages are designed to be shown to an end user.
                          enum:
                          - API
                          - USER
                        level:
                          type: string
                          description: Indicates the message level.
                          enum:
                          - INFO
                          - WARNING
                          - ERROR
                        parameters:
                          type: object
                          description: The message parameters of this message.
                        field:
                          type: string
                          description: Only present on field validation errors, indicates the field in error.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                  requestId:
                    type: string
                    description: The current request ID.
                  service:
                    type: string
                    description: The name of the service that produced the error.
                  requestMethod:
                    type: string
                    description: The Http method type of the current request.
                  requestUri:
                    type: string
                    description: The current request uri.
        '409':
          description: Layout with the same path exists.
        '429':
          description: Too Many Requests, the server has reached a limit, the request must be sent again at a later time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error.
          content:
            application/json:
              schema:
                type: object
                description: an error response.
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      description: an individual error, info or warning message.
                      properties:
                        code:
                          type: integer
                          description: The message code.
                        key:
                          type: string
                          description: The message key.
                        message:
                          type: string
                          description: The error message.
                        description:
                          type: string
                          description: Optional detailed error message.
                        more_info:
                          type: string
                          description: Optional additional information for the message.
                        category:
                          type: string
                          description: The message category whereby only user messages are designed to be shown to an end user.
                          enum:
                          - API
                          - USER
                        level:
                          type: string
                          description: Indicates the message level.
                          enum:
                          - INFO
                          - WARNING
                          - ERROR
                        parameters:
                          type: object
                          description: The message parameters of this message.
                        field:
                          type: string
                          description: Only present on field validation errors, indicates the field in error.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                  requestId:
                    type: string
                    description: The current request ID.
                  service:
                    type: string
                    description: The name of the service that produced the error.
                  requestMethod:
                    type: string
                    description: The Http method type of the current request.
                  requestUri:
                    type: string
                    description: The current request uri.
      x-ibm-dx-security-user-roles:
      - admin
      - manager
    get:
      tags:
      - Authoring layouts
      summary: Retrieve all layouts in the database.
      description: 'Use the /layouts endpoint to retrieve all layouts from the database.<br />User roles: admin, manager, editor, viewer'
      parameters:
      - name: offset
        in: query
        description: Use the offset parameter to specify the number of layouts to skip and return the rest.
        required: false
        schema:
          type: number
          format: integer
          default: 0
      - name: limit
        in: query
        description: Set the limit for the number of layouts that are returned.
        required: false
        schema:
          type: number
          format: integer
          default: 50
      - name: format
        in: query
        required: false
        description: "Specify the result format.\n * `feed` - (default) returns a wrapper with links\n * `array` - returns just the array of results\n * `sequence` - each result is a separate JSON document on a new line\n"
        schema:
          type: string
          enum:
          - feed
          - array
          - sequence
      - name: pageMode
        in: query
        required: false
        description: "Specify the next and previous page link mode.\n * `offset` - (default) allows paging forward or backwards, but only a small number of  times\n * `deep` - uses index keys to efficiently page through a large result set, but only in one direction\n"
        schema:
          type: string
          enum:
          - offset
          - deep
      - name: order
        in: query
        description: Specify whether you want the layouts to be returned in ascending/alphabetical (default) or descending/reverse-alphabetical order.
        required: false
        schema:
          type: string
          enum:
          - ascending
          - descending
          default: ascending
      - name: fields
        in: query
        description: Only the layout fields that are specified here are returned for each result. Any layout field is a valid value and can be specified as a comma-separated list.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                description: A query result that returns layouts.
                properties:
                  offset:
                    type: integer
                    description: number of results to skip.
                  limit:
                    type: integer
                    description: number of results to return.
                  href:
                    type: string
                    description: the url of the current query.
                  next:
                    type: string
                    description: the url for the next page of results. Only present if there are more results.
                  previous:
                    type: string
                    description: the url for the previous page of results. Not present when on the first page.
                  items:
                    type: array
                    items:
                      type: object
                      description: An existing layout.
                      properties:
                        id:
                          type: string
                          description: The ID of the layout.
                          pattern: ^[a-zA-Z0-9*.\-+_~$!',()]*$
                          minLength: 1
                          example: f26044ca-d92d-49e8-acd9-00563c1e0db9
                        rev:
                          type: string
                          description: The current revision of the layout.
                          minLength: 1
                          example: 139c63397272172e73f52d22f22f606f6c
                        name:
                          type: string
                          description: The name of the layout.
                          pattern: ^[a-zA-Z0-9*. \-+_~$!',()]*$
                          minLength: 1
                          example: Sample layout
                        description:
                          type: string
                          description: The description of the layout.
                          pattern: ^[a-zA-Z0-9*. \-+_~$!',()]*$
                          example: An example description of the sample layout
                        classification:
                          type: string
                          description: Indicates the type of this document.
                          enum:
                          - layout
                        creatorId:
                          type: string
                          description: The ID of the user that created the layout.
                          example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f
                        creator:
                          type: string
                          description: 'The display name of the user that created the layout. This field is only returned when the ''include'' query string option is set to ''ALL'' or ''metadata''.

                            This field is read only.

                            '
                          example: Thomas Watson
                        created:
                          type: string
                          description: The created date of this layout in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only.
                          format: date-time
                        lastModifierId:
                          type: string
                          description: The ID of the user that last modified the layout.
                          example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f
                        lastModifier:
                          type: string
                          description: 'The display name of the last user that modified the layout. This field is only returned when the ''include'' query string option is set to ''ALL'' or ''metadata''.

                            This field is read only.

                            '
                          example: Thomas Watson
                        lastModified:
                          type: string
                          description: The last modified date of this layout in ISO 8601 with the format YYYY-MM-DDThh:mm:ss.sssZ. This field is read only.
                          format: date-time
                        path:
                          type: string
                          description: Optional path to associate with the layout. Must be unique. Will default to filesystem friendly version of /[NAME].
                          example: /myLayouts/SampleLayout.json
                        prerender:
                          type: boolean
                          description: Indicates if the layout should be prerendered.
                          default: false
                          example: false
                        tags:
                          type: array
                          items:
                            type: string
                          uniqueItems: true
                          example:
                          - news
                          - sample
                        thumbnail:
                          type: object
                          description: 'The reference to the asset that should act as the thumbnail of this layout.

                            The thumbnail can be referred to by either id or path.

                            '
                          properties:
                            id:
                              type: string
                              description: The ID of the asset.
                              example: 6c622bbb-5f5b-45d4-89e1-fce1c054138f
                            path:
                              type: string
                              description: 'The path of the asset. This field is only returned when the ''include'' query string option is set to ''ALL'' or ''metadata''.

                                This field is read only.

                                '
                              example: /sales/images/hub.png
                            url:
                              type: string
                              description: 'The URL of the asset. This field is only returned when the ''include'' query string option is set to ''ALL'' or ''metadata''.

                                This field is read only.

                                '
                              example: /authoring/v1/resources/d45c83a8-2738-48a2-89e1-35256ee16283.jpg
                        template:
                          type: string
                          minLength: 1
                          example: /mytemplates/template.hbs
                        templateType:
                          type: string
                          description: Specifies the type of template associated with this layout. This field is required when prerender field is set to true.
                          enum:
                          - handlebars
                          - angular
                          default: handlebars
                          example: handlebars
                        urlTemplate:
                          type: string
                          description: Specifies the pattern for url generation.
                        isSystem:
                          type: boolean
                          description: Indicates whether this item is a 'system item' or not.
                          default: false
                      required:
                      - rev
                      - name
                      - template
        '429':
          description: Too Many Requests, the server has reached a limit, the request must be sent again at a later time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ibm-dx-security-user-roles:
      - admin
      - manager
      - editor
      - viewer
  /authoring/v1/layouts/by-content/{content-id}:
    get:
      tags:
      - Authoring layouts
      summary: Retrieves the layouts associated with the specified content.
      description: 'Use the /layouts/by-content/{contentId} endpoint to retrieve the layouts associated with the specified content. When the ''filter'' query string parameter is set to ''selected'', only the selected layout (which could be a co

# --- truncated at 32 KB (379 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/acoustic/refs/heads/main/openapi/acoustic-authoring-layouts-api-openapi.yml