Cisco Umbrella Destinations API

openapi: 3.2.0
info:
  title: Cisco Umbrella Destination Lists Destinations 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: Destinations
  description: Destinations
paths:
  /destinationlists/{destinationListId}/destinations:
    get:
      tags:
      - Destinations
      description: Get destinations in a destination list.
      summary: Get Destinations in Destination List
      operationId: getDestinations
      security:
      - oauthFlow:
        - policies.destinations:read
      parameters:
      - $ref: '#/components/parameters/destinationListId'
      - $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:
                $ref: '#/components/schemas/PaginatedDestinationObjectResponse'
              example:
                status:
                  code: 200
                  text: OK
                meta:
                  page: 1
                  limit: 100
                  total: 24
                data:
                - id: '1234590'
                  destination: cisco.com
                  type: domain
                  comment: A comment about test destination
                  createdAt: '2021-07-23 19:36:45'
        '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:
      - Destinations
      summary: Add Destinations to Destination List
      description: Add destinations to a destination list.
      operationId: createDestinations
      security:
      - oauthFlow:
        - policies.destinations:write
      parameters:
      - $ref: '#/components/parameters/destinationListId'
      requestBody:
        description: 'Add destinations to a destination list.

          Accepts no more than 500 destination objects in the body of the request.


          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.'
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/DestinationCreateObject'
            example:
            - destination: cisco.com
            - destination: 10.10.10.10
            - destination: mydestination/telemetry.com
      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: 5
        '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}/destinations/remove:
    delete:
      tags:
      - Destinations
      summary: Delete Destinations from Destination List
      description: 'Remove destinations from the destination list.


        **Note:** Accepts a list that contains no more than 500 destination IDs.


        You can retrieve a list of the destinations in the destination list through the GET `/destinationlists/{destinationListId}/destinations` operation.

        Then, to remove destinations in a destination list, provide a list of destination IDs in the request body of the

        DELETE `/destinationlists/{destinationListId}/destinations/remove` operation.'
      operationId: deleteDestinations
      security:
      - oauthFlow:
        - policies.destinations:write
      parameters:
      - $ref: '#/components/parameters/destinationListId'
      requestBody:
        description: Add a list of destination ID.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DestinationIdsList'
            example:
            - 12345
            - 987435
      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: 5
        '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
    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
    DestinationIdsList:
      type: array
      items:
        type: integer
        example: 1234
      maxItems: 500
      description: The list of destination ID.
      example:
      - 1234
      - 187575
    DestinationObjectWithStringId:
      type: object
      required:
      - id
      - type
      - destination
      - createdAt
      properties:
        id:
          $ref: '#/components/schemas/idDestinationString'
        destination:
          $ref: '#/components/schemas/destination'
        type:
          $ref: '#/components/schemas/type'
        comment:
          $ref: '#/components/schemas/comment'
        createdAt:
          type: string
          description: The date and time when the destination list was created.
          example: '2018-07-23 19:36:45'
      example:
        id: '1234590'
        destination: destination-two.com
        type: domain
        comment: A comment about test destination
        createdAt: '2021-07-23 19:36:45'
    DestinationCreateObject:
      type: object
      required:
      - destination
      description: The properties of the destination.
      properties:
        destination:
          $ref: '#/components/schemas/destination'
        comment:
          type: string
          example: A comment about the destination
          description: A comment about the destination.
      example:
        destination: mydestination.com
        comment: A comment about the destination
    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.
    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'
    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
    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`.'
    idDestinationString:
      type: string
      example: '1234567'
      description: The unique ID of the destination.
    PaginatedDestinationObjectResponse:
      type: object
      description: The status, metadata, and list of destinations for the destination list.
      required:
      - status
      - meta
      - data
      properties:
        status:
          $ref: '#/components/schemas/status'
        meta:
          $ref: '#/components/schemas/meta'
        data:
          type: array
          description: The list of destinations in the destination list.
          items:
            $ref: '#/components/schemas/DestinationObjectWithStringId'
    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/