openapi: 3.0.1
info:
  title: Cisco Umbrella Internal Domains API
  version: 2.0.0
  description: Manage the internal domains in your organization.
  contact:
    name: Cloud Security Developer Community

servers:
  - url: https://api.umbrella.com/{basePath}
    variables:
      basePath:
        default: deployments/v2

security:
  - oauthFlow: []

tags:
  - name: Internal Domains

paths:

  '/internaldomains':
    post:
      tags:
        - Internal Domains
      description: |-
        Create an internal domain. If you do not assign a list of sites to the internal domain, the internal domain
        is associated with all sites in the organization.
      summary: Create Internal Domain
      operationId: createInternalDomain
      security:
        - oauthFlow:
          - deployments.internaldomains:write
      requestBody:
        $ref: '#/components/requestBodies/internalDomain'

      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalDomainObject'
              example:
                id: 1234
                domain: Internal domain name
                description: internal domain description
                includeAllVAs: false
                includeAllMobileDevices: false
                createdAt: '2020-03-09T22:18:26.625Z'
                modifiedAt: '2020-03-09T22:18:26.625Z'
                siteIds:
                  - 928250
                  - 6244410
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

    get:
      tags:
        - Internal Domains
      description: List the internal domains.
      summary: List Internal Domains
      operationId: listInternalDomains
      security:
        - oauthFlow:
          - deployments.internaldomains:read
      parameters:
        - $ref: '#/components/parameters/paginationPageParam'
        - $ref: '#/components/parameters/paginationLimitParam'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InternalDomainObject'
              example:
                - id: 1234
                  domain: Internal domain name
                  description: Internal domain description
                  includeAllVAs: false
                  includeAllMobileDevices: false
                  createdAt: '2020-03-09T22:18:26.625Z'
                  modifiedAt: '2020-03-09T22:18:26.625Z'
                  siteIds: []
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  '/internaldomains/{internalDomainId}':
    get:
      tags:
        - Internal Domains
      description: Get an internal domain.
      summary: Get Internal Domain
      operationId: getInternalDomain
      security:
        - oauthFlow:
          - deployments.internaldomains:read
      parameters:
        - $ref: '#/components/parameters/internalDomainId'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalDomainObject'
              example:
                id: 1234
                domain: Internal domain name
                description: Internal domain description
                includeAllVAs: false
                includeAllMobileDevices: false
                createdAt: '2020-03-09T22:18:26.625Z'
                modifiedAt: '2020-03-09T22:18:26.625Z'
                siteIds: []
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

    put:
      tags:
        - Internal Domains
      description: Update an internal domain.
      summary: Update Internal Domain
      operationId: updateInternalDomain
      security:
        - oauthFlow:
          - deployments.internaldomains:write
      parameters:
        - $ref: '#/components/parameters/internalDomainId'
      requestBody:
        $ref: '#/components/requestBodies/internalDomain'

      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalDomainObject'
              example:
                id: 1234
                domain: Internal domain name
                description: Internal domain description
                includeAllVAs: false
                includeAllMobileDevices: false
                createdAt: '2020-03-09T22:18:26.625Z'
                modifiedAt: '2020-03-09T22:18:26.625Z'
                siteIds:
                  - 928250
                  - 6244410
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

    delete:
      tags:
        - Internal Domains
      description: Delete an internal domain.
      summary: Delete Internal Domain
      operationId: deleteInternalDomain
      security:
        - oauthFlow:
          - deployments.internaldomains:write
      parameters:
        - $ref: '#/components/parameters/internalDomainId'
      responses:
        '204':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                type: string
                nullable: true
              example: null
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

components:
  securitySchemes:
    oauthFlow:
      type: oauth2
      description: The client credential flow.
      flows:
        clientCredentials:
          tokenUrl: https://api.umbrella.com/auth/v2/token
          scopes:
            deployments.internaldomains:write: 'Write deployments internal domains'
            deployments.internaldomains:read: 'Read deployments internal domains'

  requestBodies:

    internalDomain:
      description: Create the internal domain.
      required: true
      content:
        application/json:
          schema:
            properties:
              domain:
                type: string
                description: The internal domain.
                example: cisco-internal.com
              description:
                type: string
                description: |-
                  The description of the internal domain. The description is a sequence of characters with a length from 1 through 50.
                minLength: 1
                maxLength: 50
                example: A description of a domain.
              includeAllVAs:
                type: boolean
                description: Specifies whether to apply the internal domain to all virtual appliances.
                example: false
              includeAllMobileDevices:
                type: boolean
                description: Specifies whether to apply the internal domain to all mobile devices.
                example: false
              siteIds:
                type: array
                items:
                  type: integer
                  description: A site ID.
                  example: 923250
                description: The list of site IDs associated with the domain.
                example:
                  - 928250
                  - 6244410
            type: object
            required:
              - domain
          example:
            domain: The internal domain
            description: Description of the internal domain
            includeAllVAs: false
            includeAllMobileDevices: false
            siteIds:
              - 928250
              - 6244410

  headers:
    Content-Type:
      schema:
        type: string
      description: The MIME content type of the response body.
      example: application/json
    Date:
      schema:
        type: string
        pattern: '^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$'
      description: The timestamp of the response.
      example: '2023-03-14T18:34:25Z'
      #'2023-03-14T18:34:25.412525046Z'

  parameters:

    paginationPageParam:
      name: page
      in: query
      description: The number of a page in the collection.
      required: false
      schema:
        default: 1
        type: integer
        format: int32
        minimum: 1
      example: 2

    paginationLimitParam:
      name: limit
      in: query
      description: The number of records in the collection to return on the page.
      required: false
      schema:
        default: 100
        type: integer
        format: int32
        minimum: 1
        maximum: 100
      example: 50

    internalDomainId:
      name: internalDomainId
      in: path
      schema:
        type: integer
      description: The ID of the internal domain.
      required: true
      example: 12456


  schemas:

    InternalDomainObject:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the internal domain.
          example: 1234556
        domain:
          type: string
          description: The domain name of the internal domain.
          example: cisco-internal.com
        description:
          type: string
          description: The description of the internal domain.
          minLength: 1
          maxLength: 50
          example: An internal domain.
        includeAllVAs:
          type: boolean
          description: Specifies whether to apply the internal domain to all virtual appliances.
          example: false
        includeAllMobileDevices:
          type: boolean
          description: Specifies whether to apply the internal domain to all mobile devices.
          example: false
        createdAt:
          type: string
          format: date-time
          description: |-
            The date and time (ISO 8601 timestamp) when the internal domain was created.
          example: '2018-06-13T16:07:07.222Z'
        modifiedAt:
          type: string
          format: date-time
          description: |-
            The date and time (ISO 8601 timestamp) when the internal domain was modified.
          example: '2018-06-13T16:07:07.222Z'
        siteIds:
          type: array
          items:
            type: integer
            description: A site ID.
            example: 923250
          description: The list of site IDs associated with the domain.
          example:
            - 928250
            - 6244410
      required:
        - id
        - domain
        - description
        - includeAllVAs
        - includeAllMobileDevices
        - createdAt
        - modifiedAt
        - siteIds
      example:
        id: 1234
        domain: Internal domain name
        description: internal domain description
        includeAllVAs: false
        includeAllMobileDevices: false
        createdAt: '2020-03-09T22:18:26.625Z'
        modifiedAt: '2020-03-09T22:18:26.625Z'
        siteIds: []

  responses:
    400Error:
      description: Bad Request
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 400
                description: HTTP status code
              error:
                type: string
                example: Validation Error
                description: A brief description of the error
              message:
                type: string
                description: Detailed error message
    401Error:
      description: Unauthorized
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 401
                description: HTTP status code
              error:
                type: string
                example: Validation error
                description: A brief description of the error
              message:
                type: string
                description: Detailed error message
    403Error:
      description: Forbidden
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 403
                description: HTTP status code
              error:
                type: string
                example: Forbidden
                description: A brief description of the error
              message:
                type: string
                description: Detailed error message
    404Error:
      description: Not Found
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 404
                description: HTTP status code
              error:
                type: string
                example: Not Found
                description: A brief description of the error
              message:
                type: string
                description: Detailed error message
    500Error:
      description: Internal Server Error
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 500
                description: HTTP status code
              error:
                type: string
                example: Internal Server Error
                description: A brief description of the error
              message:
                type: string
                description: Detailed error message
