Cisco Umbrella Destination Lists API

openapi: 3.2.0
info:
  title: Cisco Umbrella Destination Lists API
  version: 2.0.0
  description: Create and manage destination lists and destinations.
  contact:
    name: Cloud Security Developer Community
  x-provenance:
    method: harvested
    authored_by: Cisco Umbrella
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: pubhub.devnetcloud.com
    note: 26 first-party OpenAPI 3.0 documents (256 operations) listed by Cisco's own docs-nav config and fetched anonymously. Byte-identity reconfirmed 2026-08-19 by SHA-256 against the live source.
  x-evidence:
  - type: source
    url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/umbrella-config.json
  - type: source
    url: https://developer.cisco.com/docs/cloud-security/
servers:
- url: https://api.umbrella.com/{basePath}
  variables:
    basePath:
      default: policies/v2
security:
- oauthFlow: []
tags:
- name: Destination Lists
  description: Destination Lists
paths:
  /destinationlists:
    get:
      tags:
      - Destination Lists
      description: Get the destination lists in your organization.
      summary: Get Destination Lists
      operationId: getDestinationLists
      parameters:
      - $ref: '#/components/parameters/paginationPageParam'
      - $ref: '#/components/parameters/paginationLimitParam'
      security:
      - oauthFlow:
        - policies.destinationLists:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDestinationListsResponse'
              example:
                status:
                  code: 200
                  text: OK
                meta:
                  page: 1
                  limit: 100
                  total: 100
                data:
                - id: 1234567
                  organizationId: 2345678
                  access: allow
                  isGlobal: true
                  name: Global Allow List
                  thirdpartyCategoryId: 0
                  createdAt: 1490206249
                  modifiedAt: 1520476127
                  isMspDefault: false
                  markedForDeletion: false
                  bundleTypeId: 2
                  meta:
                    destinationCount: 5
                    domainCount: 5
                    urlCount: 0
                    ipv4Count: 0
                    applicationCount: 0
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerErr'
    post:
      tags:
      - Destination Lists
      description: Create a destination list in your organization.
      summary: Create Destination List
      operationId: createDestinationList
      security:
      - oauthFlow:
        - policies.destinationLists:write
      requestBody:
        description: 'Provide destination information and an optional array of destination objects.

          Accepts no more than 500 destination objects.


          If you make an API request on the POST operation that adds a URL on a high-volume domain to a destination list,

          the operation may succeed (`HTTP/200 OK`).

          However, the server returns an error message (`HTTP/400 Bad Request`) that indicates that the destination is on a high-volume domain.

          **Note:** Umbrella does not add URLs that are on high-volume domains to destination lists. Instead, we recommend that you add the domain only.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DestinationListCreate'
            example:
              access: allow
              isGlobal: false
              name: New Destination List
        required: true
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DestinationListResponse'
              example:
                status:
                  code: 200
                  text: OK
                data:
                  id: 2477857
                  organizationId: 22429759
                  access: allow
                  isGlobal: false
                  name: New Destination List
                  thirdpartyCategoryId: 0
                  createdAt: 1532628019
                  modifiedAt: 1532628019
                  isMspDefault: false
                  markedForDeletion: false
                  bundleTypeId: 2
                  meta:
                    destinationCount: 1
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerErr'
  /destinationlists/{destinationListId}:
    patch:
      tags:
      - Destination Lists
      description: Update a destination list in your organization.
      summary: Update Destination List
      operationId: updateDestinationLists
      security:
      - oauthFlow:
        - policies.destinationLists:write
      parameters:
      - $ref: '#/components/parameters/destinationListId'
      requestBody:
        description: Update a destination list.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DestinationListPatch'
            example:
              name: Updated name of destination list
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DestinationListResponse'
              example:
                status:
                  code: 200
                  text: OK
                data:
                  id: 2477857
                  organizationId: 22429759
                  access: allow
                  isGlobal: false
                  name: New name of destination list
                  thirdpartyCategoryId: 0
                  createdAt: 1532628019
                  modifiedAt: 1532628019
                  isMspDefault: false
                  markedForDeletion: false
                  bundleTypeId: 2
                  meta:
                    destinationCount: 1
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerErr'
    delete:
      tags:
      - Destination Lists
      summary: Delete Destination List
      description: Delete a destination list from your organization.
      operationId: deleteDestinationList
      security:
      - oauthFlow:
        - policies.destinationLists:write
      parameters:
      - $ref: '#/components/parameters/destinationListId'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DestinationListDelete'
              example:
                status:
                  code: 200
                  text: OK
                data: []
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerErr'
    get:
      tags:
      - Destination Lists
      summary: Get Destination List
      description: Get a destination list.
      operationId: getDestinationList
      security:
      - oauthFlow:
        - policies.destinationLists:read
      parameters:
      - $ref: '#/components/parameters/destinationListId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DestinationListResponse'
              example:
                status:
                  code: 200
                  text: OK
                data:
                  id: 2477857
                  organizationId: 22429759
                  access: allow
                  isGlobal: false
                  name: New name of destination list
                  thirdpartyCategoryId: 0
                  createdAt: 1532628019
                  modifiedAt: 1532628019
                  isMspDefault: false
                  markedForDeletion: false
                  bundleTypeId: 2
                  meta:
                    destinationCount: 1
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerErr'
components:
  schemas:
    meta:
      type: object
      description: The pagination information for the response.
      properties:
        page:
          type: integer
          description: The number of the page in the collection.
          example: 50
        limit:
          type: integer
          description: The maximum number of items that are returned on the page.
          example: 10
        total:
          type: integer
          description: The total number of items in the collection.
          example: 20
    status:
      type: object
      required:
      - code
      - text
      description: The status information for the response.
      properties:
        code:
          type: integer
          description: The HTTP status code of the response.
          example: 200
        text:
          type: string
          description: The HTTP message that describes the response.
          example: OK
      example:
        code: 200
        text: OK
    DestinationListPatch:
      type: object
      description: Update the name of the destination list.
      required:
      - name
      properties:
        name:
          $ref: '#/components/schemas/name'
    BadRequestError:
      type: object
      description: Bad Request
      properties:
        statusCode:
          type: integer
          example: 400
          description: HTTP status code
        error:
          type: string
          example: Bad Request
          description: A brief description of the error
        message:
          type: string
          example: Validation Error
        txId:
          type: string
          example: d479k9i2b723
    comment:
      type: string
      description: The comment about the destination.
      example: Add new destination list
    organizationId:
      type: integer
      example: 2345678
      description: The organization ID.
    ServerError:
      type: object
      description: Internal Server Error
      properties:
        statusCode:
          type: integer
          example: 500
          description: HTTP status code
        error:
          type: string
          example: Internal Server Error
          description: The server can not process the request.
        message:
          type: string
          example: An internal server error occurred
        txId:
          type: string
          example: l477k9i2b893
    NotFoundError:
      type: object
      description: Not Found
      properties:
        statusCode:
          type: integer
          example: 404
          description: HTTP status code
        error:
          type: string
          example: Not Found
          description: A resource specified in the URL was not found.
        txId:
          type: string
          example: a478k9i2b723
    destination:
      type: string
      example: cisco.com
      description: A domain, URL, or IP.
    DestinationListDelete:
      type: object
      description: Delete the destination list. The data field is empty in the response.
      required:
      - status
      - data
      properties:
        status:
          $ref: '#/components/schemas/status'
        data:
          type: array
          items: {}
      example:
        status:
          code: 200
          text: OK
        data: []
    DestinationListResponse:
      type: object
      description: The status and properties of the destination lists.
      required:
      - status
      - data
      properties:
        status:
          $ref: '#/components/schemas/status'
        data:
          $ref: '#/components/schemas/DestinationListObject'
    DestinationListCreate:
      type: object
      required:
      - access
      - isGlobal
      - name
      description: The properties of the destination list.
      properties:
        access:
          $ref: '#/components/schemas/access'
        isGlobal:
          $ref: '#/components/schemas/isGlobal'
        name:
          $ref: '#/components/schemas/name'
        bundleTypeId:
          $ref: '#/components/schemas/bundleTypeId'
        destinations:
          type: array
          description: The list of destinations.
          maxItems: 500
          items:
            type: object
            description: The properties of the destination.
            properties:
              destination:
                $ref: '#/components/schemas/destination'
              type:
                $ref: '#/components/schemas/type'
              comment:
                $ref: '#/components/schemas/comment'
      example:
        access: allow
        isGlobal: false
        name: The name of the destination list.
    DestinationListObject:
      type: object
      required:
      - id
      - organizationId
      - access
      - isGlobal
      - name
      - thirdpartyCategoryId
      - createdAt
      - modifiedAt
      - isMspDefault
      - markedForDeletion
      properties:
        id:
          $ref: '#/components/schemas/id'
        organizationId:
          $ref: '#/components/schemas/organizationId'
        access:
          $ref: '#/components/schemas/access'
        isGlobal:
          $ref: '#/components/schemas/isGlobal'
        name:
          $ref: '#/components/schemas/name'
        thirdpartyCategoryId:
          type: integer
          example: 1
          description: The third-party category ID of the destination list.
        createdAt:
          type: integer
          example: 1490206249
          description: The date and time when the destination list was created.
        modifiedAt:
          type: integer
          example: 1520476127
          description: The date and time when the destination list was modified.
        isMspDefault:
          type: boolean
          description: Specifies whether MSP is the default.
          example: false
        markedForDeletion:
          type: boolean
          example: false
          description: Specifies whether the destination list is marked for deletion.
        bundleTypeId:
          $ref: '#/components/schemas/bundleTypeId'
        meta:
          type: object
          description: The total number of each type of destination in the destination list. The fields in the `meta` object are optional.
          properties:
            destinationCount:
              type: integer
              example: 5
              description: The total number of destinations in a destination list.
            domainCount:
              type: integer
              example: 5
              description: 'The total number of domains in a destination list.

                Domains are part of the total number of destinations in a destination list.'
            urlCount:
              type: integer
              example: 0
              description: 'The total number of URLs in a destination list.

                Urls are part of the total number of destinations in a destination list.'
            ipv4Count:
              type: integer
              example: 0
              description: 'The total number of IP addresses in a destination list.

                IP addresses are part of the total number of destinations in a destination list.'
            applicationCount:
              type: integer
              example: 0
              description: 'The total number of applications in a destination list.

                Applications are part of the total number of destinations in a destination list.'
          example:
            domainCount: 1
            urlCount: 0
            ipv4Count: 1
            destinationCount: 2
            applicationCount: 0
      example:
        id: 1234567
        organizationId: 2345678
        access: allow
        isGlobal: true
        name: Global Allow List
        thirdpartyCategoryId: 0
        createdAt: 1490206249
        modifiedAt: 1520476127
        isMspDefault: false
        markedForDeletion: false
        bundleTypeId: 2
        meta:
          destinationCount: 5
          domainCount: 5
          urlCount: 0
          ipv4Count: 0
          applicationCount: 0
    PaginatedDestinationListsResponse:
      type: object
      description: The status, metadata, and properties of the destination lists.
      required:
      - status
      - meta
      - data
      properties:
        status:
          $ref: '#/components/schemas/status'
        meta:
          $ref: '#/components/schemas/meta'
        data:
          type: array
          description: The list of destination lists.
          items:
            $ref: '#/components/schemas/DestinationListObject'
    UnauthorizedError:
      type: object
      description: Unauthorized
      properties:
        statusCode:
          type: integer
          example: 401
          description: HTTP status code
        error:
          type: string
          example: Unauthorized
          description: The authorization header is missing or the token is unauthorized.
        txId:
          type: string
          example: a478k9i2b723
    bundleTypeId:
      type: integer
      default: 1
      enum:
      - 1
      - 2
      - 4
      example: 4
      description: 'The type of the destination list in the policy.

        Set `1` for DNS, `2` for web, and `4` for SAML Bypass.

        If the field is not specified, the default value is `1`.'
    isGlobal:
      type: boolean
      example: false
      description: 'Specifies whether the destination list is a global destination list.

        There is only one default `allow` destination list and one default `block` destination list for an organization.'
    id:
      type: integer
      example: 1234567
      description: The unique ID of the destination list.
    ForbiddenError:
      type: object
      description: Forbidden
      properties:
        statusCode:
          type: integer
          example: 403
          description: HTTP status code
        error:
          type: string
          example: Forbidden
          description: The token is invalid.
        txId:
          type: string
          example: a478k9i2b723
    name:
      type: string
      example: Global Allow list
      description: The name of the destination list.
    access:
      type: string
      enum:
      - allow
      - block
      example: allow
      description: The type of access for the destination list.
    type:
      type: string
      enum:
      - domain
      - url
      - ipv4
      example: domain
      description: The type of the destination.
  headers:
    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'
    Content-Type:
      schema:
        type: string
      description: The MIME content type of the response body.
      example: application/json
  responses:
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    ServerErr:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerError'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    InvalidRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
  parameters:
    destinationListId:
      name: destinationListId
      in: path
      schema:
        type: integer
      description: The unique ID of the destination list.
      required: true
      example: 245
    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: 4
    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
  securitySchemes:
    oauthFlow:
      type: oauth2
      description: client credential flow
      flows:
        clientCredentials:
          tokenUrl: https://api.umbrella.com/auth/v2/token
          scopes:
            policies.destinationLists:write: Write policies destination lists
            policies.destinationLists:read: Read policies destination lists
            policies.destinations:write: Write policies destinations
            policies.destinations:read: Read policies destinations
x-provenance:
  method: harvested
  first_party: true
  harvested: '2026-08-19'
  source: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/policies/destination-lists.yaml
  publisher: Cisco Systems, Inc. (Cisco DevNet Cloud Security docs)
x-evidence:
  fetched: '2026-08-19'
  url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/policies/destination-lists.yaml
  http_status: 200
  docs: https://developer.cisco.com/docs/cloud-security/