openapi: 3.1.0
info:
  title: Sitecore Edge Platform Admin API
  description: >-
    Use the Edge Platform Admin API to create, retrieve, update, and delete
    custom hostnames in your organization.

     This REST API lets you interact with:

     - The custom hostname object. Use a [custom hostname](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/custom-hostnames.html) to serve content or direct traffic to specific web services or applications under your organization's domain.

    After creating a custom hostname, you must:

     - [Register the hostname](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/set-up-a-custom-hostname.html#add-the-cname-and-txt-records-to-your-domains-dns-record). Add the CNAME and TXT records to verify domain ownership. 

     - [Check the status](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/set-up-a-custom-hostname.html#check-the-status-of-your-custom-hostname). Ensure that it is active before using the hostname. 

    Note the following:

     - You must have an [*Organization Admin* or *Organization Owner* role](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/roles.html#organization-roles) in Sitecore Cloud Portal.

     - To use this REST API, you must authenticate your API requests.

     - All API requests are made in your production environment.

    For more information, see the [official Sitecore Portal developer
    documentation](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/introduction-to-the-sitecore-cloud-portal.html).


    ## Authentication


    The Edge Platform Admin API uses bearer authentication.


    Bearer authentication involves security tokens called bearer tokens, which
    are generated in response to a login request.


    To get the [bearer
    token](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/manage-api-tokens.html):

     1. Log in to [Sitecore Cloud Portal](https://portal.sitecorecloud.io/).

     2. In the top-right corner of the menu bar, click your profile ![profile](https://resources.doc.sitecore.com/assets/image/uuid-b9b63de7-4dd2-ed95-8901-29afe1d1bf30.PNG) > **API tokens**.

     3. Click **Copy to clipboard**.

    You can now start making REST API requests. You must include this token in
    the authorization header of every request you make.
  version: '1.0'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-metadata:
    product: Sitecore Cloud Portal
tags:
  - name: Organizations
    description: >-
      The Organizations API lets you create and manage [custom
      hostnames](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/custom-hostnames.html)
      in your organization.
security:
  - BearerAuth: []
servers:
  - url: https://edge-platform-admin-api.sitecorecloud.io
    description: Production server
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas: {}
  parameters: {}
paths:
  /api/admin/v1/hostnames:
    post:
      tags:
        - Organizations
      summary: Create a custom hostname
      description: >-
        Creates a custom hostname in your organization by specifying a
        `hostname`, a `defaultSiteId`, and a `defaultContextId`. Wildcards and
        apex domains are not currently supported for naming hostnames.


        The number of custom hostnames you can create is limited by your
        organization's XM Cloud account entitlement. If this limit is exceeded,
        an error message is returned, and the custom hostname won't be created.


        After it is created, the custom hostname details are stored and used to
        [resolve and route
        traffic](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html)
        for incoming requests.
      operationId: post_em
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                hostname:
                  type: string
                  description: The unique name assigned to a custom hostname.
                  example: sitecore-api-preview.example.com
                defaultSiteId:
                  type: string
                  description: >-
                    The default [site
                    ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/get-the-environment-variables-for-a-site.html)
                    associated with the custom hostname.


                    If you don't specify a value for `defaultSiteId`, you'll
                    need to manually include it in the query parameter or body
                    with each request to the custom hostname to ensure it is
                    [resolved
                    correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                  example: playsummit
                defaultContextId:
                  type: string
                  description: >-
                    The default [context
                    ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/the-context-id-environment-variable.html)
                    associated with the custom hostname.


                    If you don't specify a value for `defaultContextId`, you'll
                    need to manually include it in the query parameter or header
                    with each request to the custom hostname to ensure it is
                    [resolved
                    correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                  example: 3BTl4aU7w12A5M76m9p8IA
              required:
                - hostname
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: >-
                      The custom hostname's unique identifier generated during
                      creation.
                    example: 08de73f4-6f01-49b2-9ca6-d7fab7de966d
                  hostname:
                    type: string
                    description: The unique name assigned to a custom hostname.
                    example: sitecore-api-preview.example.com
                  defaultSiteId:
                    type: string
                    description: >-
                      The default [site
                      ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/get-the-environment-variables-for-a-site.html)
                      associated with the custom hostname.


                      If you don't specify a value for `defaultSiteId`, you'll
                      need to manually include it in the query parameter or body
                      with each request to the custom hostname to ensure it is
                      [resolved
                      correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                    example: playsummit
                  defaultContextId:
                    type: string
                    description: >-
                      The default [context
                      ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/the-context-id-environment-variable.html)
                      associated with the custom hostname.


                      If you don't specify a value for `defaultContextId`,
                      you'll need to manually include it in the query parameter
                      or header with each request to the custom hostname to
                      ensure it is [resolved
                      correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                    example: 3BTl4aU7w12A5M76m9p8IA
                  ssl:
                    type: object
                    properties:
                      expires_on:
                        type: string
                        description: The SSL certificate's expiration date and time.
                        example: '2021-02-06T18:11:23.531995Z'
                      method:
                        type: string
                        description: >-
                          The validation method used to verify the SSL
                          certificate. 


                          Example values: "txt", "html"
                        example: txt
                      status:
                        type: string
                        description: |-
                          The current status of the SSL certificate.

                          Example values: "pending_validation", "active".
                        example: active
                      validation_records:
                        type: array
                        items:
                          type: object
                          properties:
                            txt_name:
                              type: string
                              description: >-
                                The name of the TXT record used for DCV.


                                When adding this name to your DNS provider for
                                DCV, you must exclude the domain name. For
                                example, the TXT record name must be
                                *_acme_challenge*.
                              example: _acme_challenge.sitecore-api-preview.example.com
                            txt_value:
                              type: string
                              description: The value of the TXT record used for DCV.
                              example: 9kGetV9XSlo0VXSrU1sYHeEwc36xmkFY-a0J-4CGq8c
                        description: >-
                          The TXT records used for domain control validation
                          (DCV).
                      validation_errors:
                        type: array
                        items:
                          type: object
                          properties:
                            message:
                              type: string
                              description: The error description.
                              example: SERVFAIL looking up CAA for app.example.com
                        description: Errors encountered during domain control validation.
                    required:
                      - expires_on
                      - method
                      - status
                      - validation_records
                      - validation_errors
                    description: >-
                      The custom hostname's SSL properties, such as the domain
                      control validation method, validation status, and related
                      DNS records.
                  ownership_verification:
                    type: object
                    properties:
                      name:
                        type: string
                        description: >-
                          The DNS name required to verify ownership of the
                          custom hostname.


                          When adding this name to your DNS provider to verify
                          ownership of the custom hostname, you must exclude the
                          domain name. For example, the DNS name must be
                          *_cf_custom-hostname*.
                        example: _cf_custom-hostname.sitecore-api-preview.example.com
                      type:
                        type: string
                        description: >-
                          The DNS record type required to verify ownership of
                          the custom hostname.
                        example: txt
                      value:
                        type: string
                        description: >-
                          The DNS record value required to verify ownership of
                          the custom hostname.
                        example: e5e19fb0-0666-449d-a5ae-414f485dc63b
                    required:
                      - name
                      - type
                      - value
                    description: >-
                      The DNS records required to verify ownership of the custom
                      hostname.
                  created_at:
                    type: string
                    description: The date and time the custom hostname was created.
                    example: '2021-02-06T18:11:23.531995Z'
                  status:
                    type: string
                    description: |-
                      The current status of the custom hostname.

                      Example values: "pending", "active".
                    example: active
                  verification_errors:
                    type: array
                    items:
                      type: string
                      description: The error description.
                      example: SERVFAIL looking up CAA for app.example.com
                    description: >-
                      A list of errors that occurred while verifying the
                      ownership of the custom hostname.
                required:
                  - id
                  - hostname
                  - ssl
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 400
                  title:
                    type: string
                    description: The error description.
                    example: BAD REQUEST
                  detail:
                    type: string
                    description: The error details.
                    example: URL format is invalid
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 401
                  title:
                    type: string
                    description: The error description.
                    example: UNAUTHORIZED
                  detail:
                    type: string
                    description: The error details.
                    example: >-
                      Authentication credentials are required to access the
                      resource. All requests must be authenticated.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: https://datatracker.ietf.org/doc/html/rfc7235#section-3.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '403':
          description: Forbidden request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 403
                  title:
                    type: string
                    description: The error description.
                    example: FORBIDDEN
                  detail:
                    type: string
                    description: The error details.
                    example: No access to the requested resource
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.3
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 409
                  title:
                    type: string
                    description: The error description.
                    example: CONFLICT
                  detail:
                    type: string
                    description: The error details.
                    example: The custom hostname already exists.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.8
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 422
                  title:
                    type: string
                    description: The error description.
                    example: UNPROCESSABLE ENTITY
                  detail:
                    type: string
                    description: The error details.
                    example: The maximum number of custom hostnames has been reached.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 500
                  title:
                    type: string
                    description: The error description.
                    example: INTERNAL SERVER ERROR
                  detail:
                    type: string
                    description: The error details.
                    example: >-
                      The server was unable to complete your request. Please try
                      again later.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
    get:
      tags:
        - Organizations
      summary: List custom hostnames
      description: >-
        Retrieves the list of all custom hostnames in your organization. This
        lets you check if a certain hostname already exists.


        If the hostname exists and you need to retrieve, update, or delete it,
        you can use the appropriate endpoint to perform the desired action.
      operationId: get_sm
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: >-
                      The custom hostname's unique identifier generated during
                      creation.
                    example: 08de73f4-6f01-49b2-9ca6-d7fab7de966d
                  hostname:
                    type: string
                    description: The unique name assigned to a custom hostname.
                    example: sitecore-api-preview.example.com
                  defaultSiteId:
                    type: string
                    description: >-
                      The default [site
                      ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/get-the-environment-variables-for-a-site.html)
                      associated with the custom hostname.


                      If you don't specify a value for `defaultSiteId`, you'll
                      need to manually include it in the query parameter or body
                      with each request to the custom hostname to ensure it is
                      [resolved
                      correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                    example: playsummit
                  defaultContextId:
                    type: string
                    description: >-
                      The default [context
                      ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/the-context-id-environment-variable.html)
                      associated with the custom hostname.


                      If you don't specify a value for `defaultContextId`,
                      you'll need to manually include it in the query parameter
                      or header with each request to the custom hostname to
                      ensure it is [resolved
                      correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                    example: 3BTl4aU7w12A5M76m9p8IA
                  ssl:
                    type: object
                    properties:
                      expires_on:
                        type: string
                        description: The SSL certificate's expiration date and time.
                        example: '2021-02-06T18:11:23.531995Z'
                      method:
                        type: string
                        description: >-
                          The validation method used to verify the SSL
                          certificate. 


                          Example values: "txt", "html"
                        example: txt
                      status:
                        type: string
                        description: |-
                          The current status of the SSL certificate.

                          Example values: "pending_validation", "active".
                        example: active
                      validation_records:
                        type: array
                        items:
                          type: object
                          properties:
                            txt_name:
                              type: string
                              description: >-
                                The name of the TXT record used for DCV.


                                When adding this name to your DNS provider for
                                DCV, you must exclude the domain name. For
                                example, the TXT record name must be
                                *_acme_challenge*.
                              example: _acme_challenge.sitecore-api-preview.example.com
                            txt_value:
                              type: string
                              description: The value of the TXT record used for DCV.
                              example: 9kGetV9XSlo0VXSrU1sYHeEwc36xmkFY-a0J-4CGq8c
                        description: >-
                          The TXT records used for domain control validation
                          (DCV).
                      validation_errors:
                        type: array
                        items:
                          type: object
                          properties:
                            message:
                              type: string
                              description: The error description.
                              example: SERVFAIL looking up CAA for app.example.com
                        description: Errors encountered during domain control validation.
                    required:
                      - expires_on
                      - method
                      - status
                      - validation_records
                      - validation_errors
                    description: >-
                      The custom hostname's SSL properties, such as the domain
                      control validation method, validation status, and related
                      DNS records.
                  ownership_verification:
                    type: object
                    properties:
                      name:
                        type: string
                        description: >-
                          The DNS name required to verify ownership of the
                          custom hostname.


                          When adding this name to your DNS provider to verify
                          ownership of the custom hostname, you must exclude the
                          domain name. For example, the DNS name must be
                          *_cf_custom-hostname*.
                        example: _cf_custom-hostname.sitecore-api-preview.example.com
                      type:
                        type: string
                        description: >-
                          The DNS record type required to verify ownership of
                          the custom hostname.
                        example: txt
                      value:
                        type: string
                        description: >-
                          The DNS record value required to verify ownership of
                          the custom hostname.
                        example: e5e19fb0-0666-449d-a5ae-414f485dc63b
                    required:
                      - name
                      - type
                      - value
                    description: >-
                      The DNS records required to verify ownership of the custom
                      hostname.
                  created_at:
                    type: string
                    description: The date and time the custom hostname was created.
                    example: '2021-02-06T18:11:23.531995Z'
                  status:
                    type: string
                    description: |-
                      The current status of the custom hostname.

                      Example values: "pending", "active".
                    example: active
                  verification_errors:
                    type: array
                    items:
                      type: string
                      description: The error description.
                      example: SERVFAIL looking up CAA for app.example.com
                    description: >-
                      A list of errors that occurred while verifying the
                      ownership of the custom hostname.
                required:
                  - id
                  - hostname
                  - ssl
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 401
                  title:
                    type: string
                    description: The error description.
                    example: UNAUTHORIZED
                  detail:
                    type: string
                    description: The error details.
                    example: >-
                      Authentication credentials are required to access the
                      resource. All requests must be authenticated.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: https://datatracker.ietf.org/doc/html/rfc7235#section-3.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '403':
          description: Forbidden request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 403
                  title:
                    type: string
                    description: The error description.
                    example: FORBIDDEN
                  detail:
                    type: string
                    description: The error details.
                    example: No access to the requested resource
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.3
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 404
                  title:
                    type: string
                    description: The error description.
                    example: RESOURCE NOT FOUND
                  detail:
                    type: string
                    description: The error details.
                    example: The specified resource does not exist.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.4
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 500
                  title:
                    type: string
                    description: The error description.
                    example: INTERNAL SERVER ERROR
                  detail:
                    type: string
                    description: The error details.
                    example: >-
                      The server was unable to complete your request. Please try
                      again later.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
  /api/admin/v1/hostnames/{hostname}:
    get:
      tags:
        - Organizations
      summary: Retrieve a custom hostname
      description: >-
        Retrieves a specific custom hostname in your organization, including
        details such as `defaultSiteId`, `defaultContextId`, and SSL certificate
        information.


        If you don't know the exact `hostname`, first retrieve all custom
        hostnames within your organization using the [List custom
        hostnames](https://api-docs.sitecore.com/edge-platform-admin-rest-api/organizations/get_sm)
        endpoint.
      operationId: get_im
      parameters:
        - schema:
            type: string
            description: The specific custom hostname you want to interact with.
            example: sitecore-api-preview.example.com
          required: true
          description: The specific custom hostname you want to interact with.
          name: hostname
          in: path
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: >-
                      The custom hostname's unique identifier generated during
                      creation.
                    example: 08de73f4-6f01-49b2-9ca6-d7fab7de966d
                  hostname:
                    type: string
                    description: The unique name assigned to a custom hostname.
                    example: sitecore-api-preview.example.com
                  defaultSiteId:
                    type: string
                    description: >-
                      The default [site
                      ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/get-the-environment-variables-for-a-site.html)
                      associated with the custom hostname.


                      If you don't specify a value for `defaultSiteId`, you'll
                      need to manually include it in the query parameter or body
                      with each request to the custom hostname to ensure it is
                      [resolved
                      correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                    example: playsummit
                  defaultContextId:
                    type: string
                    description: >-
                      The default [context
                      ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/the-context-id-environment-variable.html)
                      associated with the custom hostname.


                      If you don't specify a value for `defaultContextId`,
                      you'll need to manually include it in the query parameter
                      or header with each request to the custom hostname to
                      ensure it is [resolved
                      correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                    example: 3BTl4aU7w12A5M76m9p8IA
                  ssl:
                    type: object
                    properties:
                      expires_on:
                        type: string
                        description: The SSL certificate's expiration date and time.
                        example: '2021-02-06T18:11:23.531995Z'
                      method:
                        type: string
                        description: >-
                          The validation method used to verify the SSL
                          certificate. 


                          Example values: "txt", "html"
                        example: txt
                      status:
                        type: string
                        description: |-
                          The current status of the SSL certificate.

                          Example values: "pending_validation", "active".
                        example: active
                      validation_records:
                        type: array
                        items:
                          type: object
                          properties:
                            txt_name:
                              type: string
                              description: >-
                                The name of the TXT record used for DCV.


                                When adding this name to your DNS provider for
                                DCV, you must exclude the domain name. For
                                example, the TXT record name must be
                                *_acme_challenge*.
                              example: _acme_challenge.sitecore-api-preview.example.com
                            txt_value:
                              type: string
                              description: The value of the TXT record used for DCV.
                              example: 9kGetV9XSlo0VXSrU1sYHeEwc36xmkFY-a0J-4CGq8c
                        description: >-
                          The TXT records used for domain control validation
                          (DCV).
                      validation_errors:
                        type: array
                        items:
                          type: object
                          properties:
                            message:
                              type: string
                              description: The error description.
                              example: SERVFAIL looking up CAA for app.example.com
                        description: Errors encountered during domain control validation.
                    required:
                      - expires_on
                      - method
                      - status
                      - validation_records
                      - validation_errors
                    description: >-
                      The custom hostname's SSL properties, such as the domain
                      control validation method, validation status, and related
                      DNS records.
                  ownership_verification:
                    type: object
                    properties:
                      name:
                        type: string
                        description: >-
                          The DNS name required to verify ownership of the
                          custom hostname.


                          When adding this name to your DNS provider to verify
                          ownership of the custom hostname, you must exclude the
                          domain name. For example, the DNS name must be
                          *_cf_custom-hostname*.
                        example: _cf_custom-hostname.sitecore-api-preview.example.com
                      type:
                        type: string
                        description: >-
                          The DNS record type required to verify ownership of
                          the custom hostname.
                        example: txt
                      value:
                        type: string
                        description: >-
                          The DNS record value required to verify ownership of
                          the custom hostname.
                        example: e5e19fb0-0666-449d-a5ae-414f485dc63b
                    required:
                      - name
                      - type
                      - value
                    description: >-
                      The DNS records required to verify ownership of the custom
                      hostname.
                  created_at:
                    type: string
                    description: The date and time the custom hostname was created.
                    example: '2021-02-06T18:11:23.531995Z'
                  status:
                    type: string
                    description: |-
                      The current status of the custom hostname.

                      Example values: "pending", "active".
                    example: active
                  verification_errors:
                    type: array
                    items:
                      type: string
                      description: The error description.
                      example: SERVFAIL looking up CAA for app.example.com
                    description: >-
                      A list of errors that occurred while verifying the
                      ownership of the custom hostname.
                required:
                  - id
                  - hostname
                  - ssl
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 400
                  title:
                    type: string
                    description: The error description.
                    example: BAD REQUEST
                  detail:
                    type: string
                    description: The error details.
                    example: URL format is invalid
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 401
                  title:
                    type: string
                    description: The error description.
                    example: UNAUTHORIZED
                  detail:
                    type: string
                    description: The error details.
                    example: >-
                      Authentication credentials are required to access the
                      resource. All requests must be authenticated.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: https://datatracker.ietf.org/doc/html/rfc7235#section-3.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '403':
          description: Forbidden request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 403
                  title:
                    type: string
                    description: The error description.
                    example: FORBIDDEN
                  detail:
                    type: string
                    description: The error details.
                    example: No access to the requested resource
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.3
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 404
                  title:
                    type: string
                    description: The error description.
                    example: RESOURCE NOT FOUND
                  detail:
                    type: string
                    description: The error details.
                    example: The specified resource does not exist.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.4
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 500
                  title:
                    type: string
                    description: The error description.
                    example: INTERNAL SERVER ERROR
                  detail:
                    type: string
                    description: The error details.
                    example: >-
                      The server was unable to complete your request. Please try
                      again later.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
    patch:
      tags:
        - Organizations
      summary: Update a custom hostname
      description: >-
        Partially updates a custom hostname by replacing the `defaultSiteId`,
        `defaultContextId`, or both, as needed.


        The `hostname` itself cannot be updated after the custom hostname has
        been created and registered. As a workaround, you must delete the
        existing custom hostname and create a new one to change the `hostname`.
      operationId: patch_am
      parameters:
        - schema:
            type: string
            description: The specific custom hostname you want to interact with.
            example: sitecore-api-preview.example.com
          required: true
          description: The specific custom hostname you want to interact with.
          name: hostname
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                defaultSiteId:
                  type: string
                  description: >-
                    The default [site
                    ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/get-the-environment-variables-for-a-site.html)
                    associated with the custom hostname.


                    If you don't specify a value for `defaultSiteId`, you'll
                    need to manually include it in the query parameter or body
                    with each request to the custom hostname to ensure it is
                    [resolved
                    correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                  example: playsummit
                defaultContextId:
                  type: string
                  description: >-
                    The default [context
                    ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/the-context-id-environment-variable.html)
                    associated with the custom hostname.


                    If you don't specify a value for `defaultContextId`, you'll
                    need to manually include it in the query parameter or header
                    with each request to the custom hostname to ensure it is
                    [resolved
                    correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                  example: 3BTl4aU7w12A5M76m9p8IA
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  defaultSiteId:
                    type: string
                    description: >-
                      The default [site
                      ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/get-the-environment-variables-for-a-site.html)
                      associated with the custom hostname.


                      If you don't specify a value for `defaultSiteId`, you'll
                      need to manually include it in the query parameter or body
                      with each request to the custom hostname to ensure it is
                      [resolved
                      correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                    example: playsummit
                  defaultContextId:
                    type: string
                    description: >-
                      The default [context
                      ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/the-context-id-environment-variable.html)
                      associated with the custom hostname.


                      If you don't specify a value for `defaultContextId`,
                      you'll need to manually include it in the query parameter
                      or header with each request to the custom hostname to
                      ensure it is [resolved
                      correctly](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/resolving-a-custom-hostname-during-a-request.html).
                    example: 3BTl4aU7w12A5M76m9p8IA
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 400
                  title:
                    type: string
                    description: The error description.
                    example: BAD REQUEST
                  detail:
                    type: string
                    description: The error details.
                    example: URL format is invalid
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 401
                  title:
                    type: string
                    description: The error description.
                    example: UNAUTHORIZED
                  detail:
                    type: string
                    description: The error details.
                    example: >-
                      Authentication credentials are required to access the
                      resource. All requests must be authenticated.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: https://datatracker.ietf.org/doc/html/rfc7235#section-3.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '403':
          description: Forbidden request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 403
                  title:
                    type: string
                    description: The error description.
                    example: FORBIDDEN
                  detail:
                    type: string
                    description: The error details.
                    example: No access to the requested resource
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.3
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 404
                  title:
                    type: string
                    description: The error description.
                    example: RESOURCE NOT FOUND
                  detail:
                    type: string
                    description: The error details.
                    example: The specified resource does not exist.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.4
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 500
                  title:
                    type: string
                    description: The error description.
                    example: INTERNAL SERVER ERROR
                  detail:
                    type: string
                    description: The error details.
                    example: >-
                      The server was unable to complete your request. Please try
                      again later.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
    delete:
      tags:
        - Organizations
      summary: Delete a custom hostname
      description: >-
        Deletes a custom hostname and all its associated details. This is an
        irreversible operation.
      operationId: delete_rm
      parameters:
        - schema:
            type: string
            description: The specific custom hostname you want to interact with.
            example: sitecore-api-preview.example.com
          required: true
          description: The specific custom hostname you want to interact with.
          name: hostname
          in: path
      responses:
        '204':
          description: No Content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 400
                  title:
                    type: string
                    description: The error description.
                    example: BAD REQUEST
                  detail:
                    type: string
                    description: The error details.
                    example: URL format is invalid
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 401
                  title:
                    type: string
                    description: The error description.
                    example: UNAUTHORIZED
                  detail:
                    type: string
                    description: The error details.
                    example: >-
                      Authentication credentials are required to access the
                      resource. All requests must be authenticated.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: https://datatracker.ietf.org/doc/html/rfc7235#section-3.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '403':
          description: Forbidden request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 403
                  title:
                    type: string
                    description: The error description.
                    example: FORBIDDEN
                  detail:
                    type: string
                    description: The error details.
                    example: No access to the requested resource
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.3
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 404
                  title:
                    type: string
                    description: The error description.
                    example: RESOURCE NOT FOUND
                  detail:
                    type: string
                    description: The error details.
                    example: The specified resource does not exist.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.4
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 422
                  title:
                    type: string
                    description: The error description.
                    example: UNPROCESSABLE ENTITY
                  detail:
                    type: string
                    description: The error details.
                    example: The maximum number of custom hostnames has been reached.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: The HTTP response status code.
                    example: 500
                  title:
                    type: string
                    description: The error description.
                    example: INTERNAL SERVER ERROR
                  detail:
                    type: string
                    description: The error details.
                    example: >-
                      The server was unable to complete your request. Please try
                      again later.
                  type:
                    type: string
                    description: URL to get more information about the error.
                    example: >-
                      https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.1
                  instance:
                    type: string
                    description: The instance where the error was encountered.
                    example: >-
                      https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com
                required:
                  - status
                  - title
                  - detail
                  - type
                  - instance
webhooks: {}
