Acoustic Authoring sites API

openapi: 3.2.0
info:
  title: Acoustic Authoring sites API
  version: 1.0.142
  x-ibm-name: ibm-watson-content-hub-api
  description: 'Operations tagged Authoring sites 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 sites
  description: 'Use the Content authoring sites service Rest APIs to work with sites. Sites are comprised of a site metadata and a hierarchy of pages. You can retrieve or update site metadata and create, read, update, and delete site pages belonging to a site. The out-of-the-box site has an ID of ''default''.

    '
paths:
  /authoring/v1/sites:
    get:
      x-ibm-dx-security-user-roles:
      - admin
      - manager
      - editor
      - viewer
      summary: Get list of all sites
      description: 'Returns a list of all sites. A default site with id ''default'' exists out of the box.

        <br />User roles: admin, manager, editor, viewer'
      parameters:
      - name: fields
        in: query
        description: 'Reduce the returned site metadata down to just the specified fields. Fields specified by a comma seperated list of field names and should only be used once in query string.

          To only retrieve `rev` and `lastModified` this parameter should look like `fields=rev,lastModified`.

          '
        required: false
        style: form
        explode: false
        schema:
          type: string
          items:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                title: List of available sites
                description: List of available sites
                properties:
                  items:
                    type: array
                    items:
                      title: Site Metadata
                      description: Site Metadata
                      type: object
                      properties:
                        id:
                          type: string
                          description: The ID of the site.
                        rev:
                          type: string
                          description: The current revision of the document.
                        name:
                          type: string
                          description: The name of the site.
                        classification:
                          type: string
                          description: This is always `site`
                        lastModified:
                          type: string
                          description: The last modified date of this site metadata in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only.
                        lastModifierId:
                          type: string
                          description: This is the user id of the user that modified the site metadata. This field is read only
                        created:
                          type: string
                          description: The creation date of this site metadata in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only
                        creatorId:
                          type: string
                          description: This is the user id of the user that created the site metadata. This field is read only.
                        routingMode:
                          type: string
                          description: The is the routing mode for the site, values are either 'anchor' or 'path'. The property controls the URL structure that is used to address individual pages within the site. With a routing mode of 'anchor' pages are addressed by URL anchors that are relative to the site root document, for example 'https://your.host/#/products'.  With a routing mode of 'path' pages are addressed by URL path fragments instead of '#' anchors, for example 'https://your.host/products'. The 'path' mode is recommended for allowing external search crawlers to index the pages as separate documents.
              examples:
                response:
                  value:
                    items:
                    - name: default
                      classification: site
                      routingMode: anchor
                      lastModified: '2017-09-11T14:03:04.348Z'
                      lastModifierId: 00000000-0000-0000-0000-000000000009
                      created: '2017-09-11T14:03:04.348Z'
                      creatorId: 00000000-0000-0000-0000-000000000009
                      id: default
                      rev: 1-76a0d8566675d83395d8878fab7d4e5e
        '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'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                title: ErrorMessage
                description: ErrorMessage
                type: object
                properties:
                  service:
                    type: string
                    description: Service name.
                  requestId:
                    type: string
                    description: Request ID.
                  errors:
                    type: array
                    items:
                      title: Error
                      description: Error
                      type: object
                      properties:
                        code:
                          type: integer
                        message:
                          type: string
                        level:
                          type: string
                        description:
                          type: string
                        cause:
                          type: object
                          properties:
                            code:
                              type: integer
                            message:
                              type: string
                        locale:
                          type: string
              examples:
                response:
                  value:
                    service: prod-authoring-sites
                    requestId: '455478465455511'
                    errors:
                    - code: 5004
                      message: Unexpected error occurred.
                      level: ERROR
                      description: Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists.
                      locale: en
      tags:
      - Authoring sites
    post:
      x-ibm-dx-security-user-roles:
      - admin
      - manager
      - editor
      summary: Create a new site
      description: 'Use this endpoint to create a new site.


        The new site can either be an initial draft site which has no associated ready version or

        it can be a draft of an existing ready site.


        The body of the request should contain the metadata for the new site.

        This metadata should include the site ''name'', ''linkedDocId'' is optional, ''id'' is optional.

        If ''linkedDocId'' is provided, then the site created will be a draft of the ready site specified in ''linkedDocId''.

        If ''linkedDocId'' is not provided, then the site created will be an initial draft site i.e no ready version exists yet.

        If ID is provided, and a draft of the default site is being created it must start with default.

        ''linkedDocId'' must be set to ''default''.

        <br />User roles: admin, manager, editor'
      parameters:
      - name: copySourceSiteId
        in: query
        description: 'If ‘copySourceSiteId’ is specified when creating a site then a new site is created and all the pages from the source site are copied into the new site.

          '
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: Creating Site Metadata
              description: Create Site Metadata
              type: object
              properties:
                id:
                  type: string
                  description: The ID of the site. If creating a draft of the default site the id must start with default.
                linkedDocId:
                  type: string
                  description: The linkedDocId for draft sites. This is an optional field, if provided specify the ID of the ready site to create a draft of.
                name:
                  type: string
                  description: The name of the site. This is a required field.
                status:
                  type: string
                  description: The status of the site metadata (i.e. draft)
                routingMode:
                  type: string
                  description: The is routingMode the routing mode for the site, values are either 'anchor' or 'path'. The property controls the URL structure that is used to address individual pages within the site. With a routing mode of 'anchor' pages are addressed by URL anchors that are relative to the site root document, for example 'https://your.host/#/products'.  With a routing mode of 'path' pages are addressed by URL path fragments instead of '#' anchors, for example 'https://your.host/products'. The 'path' mode is recommended for allowing external search crawlers to index the pages as separate documents.
        description: The metadata for the new site
        required: true
      responses:
        '201':
          description: succcess.
          content:
            application/json:
              schema:
                title: Site Metadata
                description: Site Metadata
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the site.
                  rev:
                    type: string
                    description: The current revision of the document.
                  name:
                    type: string
                    description: The name of the site.
                  classification:
                    type: string
                    description: This is always `site`
                  lastModified:
                    type: string
                    description: The last modified date of this site metadata in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only.
                  lastModifierId:
                    type: string
                    description: This is the user id of the user that modified the site metadata. This field is read only
                  created:
                    type: string
                    description: The creation date of this site metadata in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only
                  creatorId:
                    type: string
                    description: This is the user id of the user that created the site metadata. This field is read only.
                  routingMode:
                    type: string
                    description: The is the routing mode for the site, values are either 'anchor' or 'path'. The property controls the URL structure that is used to address individual pages within the site. With a routing mode of 'anchor' pages are addressed by URL anchors that are relative to the site root document, for example 'https://your.host/#/products'.  With a routing mode of 'path' pages are addressed by URL path fragments instead of '#' anchors, for example 'https://your.host/products'. The 'path' mode is recommended for allowing external search crawlers to index the pages as separate documents.
              examples:
                response:
                  value:
                    name: default
                    routingMode: anchor
                    storeId: ''
                    storeIdentifier: ''
                    linkedDocId: default
                    classification: site
                    lastModified: '2018-07-17T15:17:02.203Z'
                    lastModifierId: d30a541e-ff2e-45a8-a0eb-52952a3cd6eb
                    creatorId: 00000000-0000-0000-0000-000000000009
                    created: '2018-07-16T15:56:20.009Z'
                    status: ready
                    id: default:fc81b9d3-76a7-4bd1-8ddc-a23cc9e4b101
                    rev: 68-8f553a9520a1f3be3b21fd6cc8684dd5
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                title: ErrorMessage
                description: ErrorMessage
                type: object
                properties:
                  service:
                    type: string
                    description: Service name.
                  requestId:
                    type: string
                    description: Request ID.
                  errors:
                    type: array
                    items:
                      title: Error
                      description: Error
                      type: object
                      properties:
                        code:
                          type: integer
                        message:
                          type: string
                        level:
                          type: string
                        description:
                          type: string
                        cause:
                          type: object
                          properties:
                            code:
                              type: integer
                            message:
                              type: string
                        locale:
                          type: string
              examples:
                response:
                  value:
                    service: prod-authoring-sites
                    requestId: '455478465455511'
                    errors:
                    - errorKey: SITE_ITEM_INVALID_ERROR
                      code: 2003
                      statusCode: '400'
                      message: Site metadata supplied is invalid, the 'linkedDocId' may be missing or empty.
                      messageParameters:
                        field: linkedDocId
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                title: ErrorMessage
                description: ErrorMessage
                type: object
                properties:
                  service:
                    type: string
                    description: Service name.
                  requestId:
                    type: string
                    description: Request ID.
                  errors:
                    type: array
                    items:
                      title: Error
                      description: Error
                      type: object
                      properties:
                        code:
                          type: integer
                        message:
                          type: string
                        level:
                          type: string
                        description:
                          type: string
                        cause:
                          type: object
                          properties:
                            code:
                              type: integer
                            message:
                              type: string
                        locale:
                          type: string
              examples:
                response:
                  value:
                    service: prod-authoring-sites
                    requestId: '69982173950058'
                    errors:
                    - code: 2096
                      message: 'Unable to create site with ID: default:fc81b9d3-76a7-4bd1-8ddc-a23cc9e4b101 due to a conflict.'
                      level: ERROR
                      description: Unable to create the specified site due to a conflict with an existing item. You may have attempted to create the site but the site already exists.
                      locale: en
        '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'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                title: ErrorMessage
                description: ErrorMessage
                type: object
                properties:
                  service:
                    type: string
                    description: Service name.
                  requestId:
                    type: string
                    description: Request ID.
                  errors:
                    type: array
                    items:
                      title: Error
                      description: Error
                      type: object
                      properties:
                        code:
                          type: integer
                        message:
                          type: string
                        level:
                          type: string
                        description:
                          type: string
                        cause:
                          type: object
                          properties:
                            code:
                              type: integer
                            message:
                              type: string
                        locale:
                          type: string
              examples:
                response:
                  value:
                    service: prod-authoring-sites
                    requestId: '455478465455511'
                    errors:
                    - code: 5004
                      message: Unexpected error occurred.
                      level: ERROR
                      description: Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists.
                      locale: en
      tags:
      - Authoring sites
  /authoring/v1/sites/{site-id}:
    get:
      x-ibm-dx-security-user-roles:
      - admin
      - manager
      - editor
      - viewer
      summary: Retrieve metadata for a site.
      description: 'Retrieve the site metadata for an existing site. A default site with ID ''default'' exists out-of-the-box.

        <br />User roles: admin, manager, editor, viewer'
      parameters:
      - name: site-id
        in: path
        description: The ID of the site.
        required: true
        schema:
          type: string
          format: uuid
      - name: fields
        in: query
        description: 'Optional. Only the site metadata fields that are specified here are returned for each result. Any site metadata field is a valid value and can be specified as a comma-separated list. Field names should only be specified once in the list.


          For example, to only retrieve `name` and `rev` this parameter should look like `fields=name,rev`.

          '
        required: false
        style: form
        explode: false
        schema:
          type: string
          items:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: Site Metadata
                description: Site Metadata
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the site.
                  rev:
                    type: string
                    description: The current revision of the document.
                  name:
                    type: string
                    description: The name of the site.
                  classification:
                    type: string
                    description: This is always `site`
                  lastModified:
                    type: string
                    description: The last modified date of this site metadata in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only.
                  lastModifierId:
                    type: string
                    description: This is the user id of the user that modified the site metadata. This field is read only
                  created:
                    type: string
                    description: The creation date of this site metadata in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only
                  creatorId:
                    type: string
                    description: This is the user id of the user that created the site metadata. This field is read only.
                  routingMode:
                    type: string
                    description: The is the routing mode for the site, values are either 'anchor' or 'path'. The property controls the URL structure that is used to address individual pages within the site. With a routing mode of 'anchor' pages are addressed by URL anchors that are relative to the site root document, for example 'https://your.host/#/products'.  With a routing mode of 'path' pages are addressed by URL path fragments instead of '#' anchors, for example 'https://your.host/products'. The 'path' mode is recommended for allowing external search crawlers to index the pages as separate documents.
              examples:
                response:
                  value:
                    name: default
                    classification: site
                    routingMode: anchor
                    lastModified: '2017-09-11T14:03:04.348Z'
                    lastModifierId: 00000000-0000-0000-0000-000000000009
                    created: '2017-09-11T14:03:04.348Z'
                    creatorId: 00000000-0000-0000-0000-000000000009
                    id: default
                    rev: 1-76a0d8566675d83395d8878fab7d4e5e
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                title: ErrorMessage
                description: ErrorMessage
                type: object
                properties:
                  service:
                    type: string
                    description: Service name.
                  requestId:
                    type: string
                    description: Request ID.
                  errors:
                    type: array
                    items:
                      title: Error
                      description: Error
                      type: object
                      properties:
                        code:
                          type: integer
                        message:
                          type: string
                        level:
                          type: string
                        description:
                          type: string
                        cause:
                          type: object
                          properties:
                            code:
                              type: integer
                            message:
                              type: string
                        locale:
                          type: string
              examples:
                response:
                  value:
                    service: prod-authoring-sites
                    requestId: '455478465455511'
                    errors:
                    - code: 2005
                      message: Invalid site ID parameter provided.
                      level: ERROR
                      description: The site ID provided is invalid. The site ID value cannot be empty or contain spaces. Provide a valid site ID and try again.
                      locale: en
        '404':
          description: Not found
          content:
            application/json:
              schema:
                title: ErrorMessage
                description: ErrorMessage
                type: object
                properties:
                  service:
                    type: string
                    description: Service name.
                  requestId:
                    type: string
                    description: Request ID.
                  errors:
                    type: array
                    items:
                      title: Error
                      description: Error
                      type: object
                      properties:
                        code:
                          type: integer
                        message:
                          type: string
                        level:
                          type: string
                        description:
                          type: string
                        cause:
                          type: object
                          properties:
                            code:
                              type: integer
                            message:
                              type: string
                        locale:
                          type: string
              examples:
                response:
                  value:
                    service: prod-authoring-sites
                    requestId: '455478465455511'
                    errors:
                    - code: 2002
                      message: 'Site not found for ID: dummyId'
                      level: ERROR
                      description: A site with the specified ID was not found in the system. Provide a valid ID and try again.
                      locale: en
        '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'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                title: ErrorMessage
                description: ErrorMessage
                type: object
                properties:
                  service:
                    type: string
                    description: Service name.
                  requestId:
                    type: string
                    description: Request ID.
                  errors:
                    type: array
                    items:
                      title: Error
                      description: Error
                      type: object
                      properties:
                        code:
                          type: integer
                        message:
                          type: string
                        level:
                          type: string
                        description:
                          type: string
                        cause:
                          type: object
                          properties:
                            code:
                              type: integer
                            message:
                              type: string
                        locale:
                          type: string
              examples:
                response:
                  value:
                    service: prod-authoring-sites
                    requestId: '455478465455511'
                    errors:
                    - code: 5004
                      message: Unexpected error occurred.
                      level: ERROR
                      description: Unable to complete the request due to an unexpected error. Try again or contact Acoustic support if problem persists.
                      locale: en
      tags:
      - Authoring sites
    put:
      x-ibm-dx-security-user-roles:
      - admin
      - manager
      - editor
      summary: Update metadata for a site.
      description: 'Update the metadata for an existing site. A default site with ID ''default'' exists out-of-the-box.


        The update data must include the `rev` and `name` metadata fields.

        <br />User roles: admin, manager, editor'
      parameters:
      - name: site-id
        in: path
        description: The ID of the site.
        required: true
        schema:
          type: string
          format: uuid
      - name: Content-Type
        in: header
        description: Content type of the request body, should be 'application/json'
        required: true
        schema:
          type: string
      - name: forceOverride
        in: query
        description: 'Force update of the existing site metadata without requiring the current `rev` value.

          When set to `true` this request will overwrite the stored site metadata regardless of a difference in revisions.

          '
        required: false
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              title: Updating Site Metadata
              description: Updating Site Metadata
              type: object
              properties:
                id:
                  type: string
                  description: The ID of the site.
                rev:
                  type: string
                  description: The current revision of the document. This is a required field.
                name:
                  type: string
                  description: The name of the site. This is a required field.
                routingMode:
                  type: string
                  description: The is the routing mode for the site, values are either 'anchor' or 'path'. The property controls the URL structure that is used to address individual pages within the site. With a routing mode of 'anchor' pages are addressed by URL anchors that are relative to the site root document, for example 'https://your.host/#/products'.  With a routing mode of 'path' pages are addressed by URL path fragments instead of '#' anchors, for example 'https://your.host/products'. The 'path' mode is recommended for allowing external search crawlers to index the pages as separate documents.
        description: Provide the updated site metadata in the body of the request. The current revision (`rev`) and the site name (`name`) fields must be provided in order to update the site metadata.
        required: true
      responses:
        '200':
          description: Success, returns updated site
          content:
            application/json:
              schema:
                title: Site Metadata update response
                description: Site Metadata update response
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the site.
                  rev:
                    type: string
                    description: The current revision of the document.
                  name:
                    type: string
                    description: The name of the site.
                  classification:
                    type: string
                    description: this is always `site`
                  routingMode:
                    type: string
                    description: The is the routing mode for the site, values are either 'anchor' or 'path'. The property controls the URL structure that is used to address individual pages within the site. With a routing mode of 'anchor' pages are addressed by URL anchors that are relative to the site root document, for example 'https://your.host/#/products'.  With a routing mode of 'path' pages are addressed by URL path fragments instead of '#' anchors, for example 'https://your.host/products'. The 'path' mode is recommended for allowing external search crawlers to index the pages as separate documents.
              examples:
                response:
                  value:
                    name: default
                    id: default
                    rev: 2

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