openapi: 3.0.1 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 tags: - name: Destination Lists description: Destination Lists - name: Destinations description: Destinations - name: Umbrella security: - oauthFlow: [] paths: /destinationlists: get: tags: - Destination Lists - Umbrella 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 - Umbrella 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 - Umbrella 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 - Umbrella 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 - Umbrella 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' /destinationlists/{destinationListId}/destinations: get: tags: - Destinations - Umbrella 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 - Umbrella 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 - Umbrella 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: 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 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' 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: 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 destinationListId: name: destinationListId in: path schema: type: integer description: The unique ID of the destination list. required: true example: 245 schemas: 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 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 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.' access: type: string enum: - allow - block example: allow description: The type of access for the destination list. id: type: integer example: 1234567 description: The unique ID of the destination list. idDestinationString: type: string example: '1234567' description: The unique ID of the destination. organizationId: type: integer example: 2345678 description: The organization ID. 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' 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 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. DestinationListPatch: type: object description: Update the name of the destination list. required: - name properties: name: $ref: '#/components/schemas/name' DestinationIdsList: type: array items: type: integer example: 1234 maxItems: 500 description: The list of destination ID. example: - 1234 - 187575 destination: type: string example: cisco.com description: A domain, URL, or IP. name: type: string example: Global Allow list description: The name of the destination list. comment: type: string description: The comment about the destination. example: Add new destination list type: type: string enum: - domain - url - ipv4 example: domain description: The type of the destination. 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 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' 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' 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: [] 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 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 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 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 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 responses: InvalidRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestError' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' 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' 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/