Cisco Umbrella Secure Web Gateway Device Settings API

openapi: 3.0.1
info:
  version: 2.0.0
  title: Cisco Umbrella Secure Web Gateway Device Settings API
  description: Manage the Secure Web Gateway (SWG) settings for the devices in an organization.
  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: deployments/v2
tags:
- name: SWG Device Settings
  description: Secure Web Gateway (SWG) device settings
- name: Umbrella
security:
- oauthFlow: []
paths:
  /deviceSettings/SWGEnabled/set:
    post:
      tags:
      - SWG Device Settings
      - Umbrella
      description: 'Add a list of origin ID and the Secure Web Gateway setting for devices in the organization.

        The SWG device setting overrides the organization-level SWG setting.


        **Note:** Before you can add an SWG override setting to a device, you must register the device as a roaming computer
        with Umbrella.

        Umbrella applies the SWG override setting to a device using the device''s origin ID.

        You can list the roaming computers in your organization by sending a request to the Umbrella Roaming Computers API.'
      summary: Set SWG Override Device Settings
      operationId: createSecureWebGatewayDeviceSettings
      security:
      - oauthFlow:
        - deployments.devices.swg:write
      requestBody:
        description: '* Provide a list of origin ID for the devices in the organization. The list can contain 1–100 origin
          IDs.

          * Provide the Secure Web gateway (SWG) device setting to apply to the devices.'
        content:
          application/json:
            schema:
              type: object
              description: The properties of the `originIds` and `value` of the SWG device setting.
              required:
              - value
              - originIds
              properties:
                originIds:
                  type: array
                  description: The list of origin IDs. The list can contain 1–100 origin IDs.
                  items:
                    $ref: '#/components/schemas/originId'
                value:
                  $ref: '#/components/schemas/value'
            example:
              value: '1'
              originIds:
              - 12321231
              - 123134314
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisteredSWGDeviceSettings'
              example:
                totalCount: 2
                successCount: 1
                failCount: 1
                items:
                - originId: 12321231
                  code: 200
                  message: success
                - originId: 12313431
                  code: 404
                  message: The origin ID of the device does not exist.
                value: '1'
        '400':
          $ref: '#/components/responses/400ErrorSingle'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404ErrorSingle'
        '413':
          $ref: '#/components/responses/413ErrorSingle'
        '429':
          $ref: '#/components/responses/429Error'
        '500':
          $ref: '#/components/responses/500ErrorSingle'
  /deviceSettings/SWGEnabled/list:
    post:
      tags:
      - SWG Device Settings
      - Umbrella
      description: List the Secure Web Gateway (SWG) override setting for devices in the organization.
      summary: List SWG Override Device Settings
      operationId: listSecureWebGatewayDeviceSettings
      security:
      - oauthFlow:
        - deployments.devices.swg:read
      requestBody:
        description: Provide a list of origin ID for the devices in the organization. The list can contain 1–100 origin IDs.
        content:
          application/json:
            schema:
              type: object
              description: The `originIds` property.
              required:
              - originIds
              properties:
                originIds:
                  type: array
                  description: The list of origin IDs. The list can contain 1–100 origin IDs.
                  items:
                    $ref: '#/components/schemas/originId'
            example:
              originIds:
              - 12321231
              - 123134314
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSWGDeviceSettings'
              example:
              - originId: 124131441
                name: SWG-enabled
                value: '1'
                modifiedAt: '2021-04-26 13:12:11'
              - originId: 124131442
                name: SWG-not-enabled
                value: '0'
                modifiedAt: '2023-04-26 13:12:11'
        '400':
          $ref: '#/components/responses/400ErrorSingle'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404ErrorSingle'
        '413':
          $ref: '#/components/responses/413ErrorSingle'
        '429':
          $ref: '#/components/responses/429Error'
        '500':
          $ref: '#/components/responses/500ErrorSingle'
  /deviceSettings/SWGEnabled/remove:
    post:
      tags:
      - SWG Device Settings
      - Umbrella
      security:
      - oauthFlow:
        - deployments.devices.swg:write
      description: 'Remove the Secure Web Gateway (SWG) override setting for the devices in the organization.

        Once you remove the override setting on a device, Umbrella applies your organization''s SWG setting to the device.'
      summary: Delete SWG Override Device Settings
      operationId: deleteSecureWebGatewayDeviceSettings
      requestBody:
        description: Provide a list of origin ID for the devices in the organization. The list can contain 1–100 origin IDs.
        content:
          application/json:
            schema:
              type: object
              description: The `originIds` property.
              required:
              - originIds
              properties:
                originIds:
                  type: array
                  description: The list of origin IDs. The list can contain 1–100 origin IDs.
                  items:
                    $ref: '#/components/schemas/originId'
            example:
              originIds:
              - 12321231
              - 123134314
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Deleted SWG override setting on the devices.
                    example: No content
              example:
                status: No content
        '400':
          $ref: '#/components/responses/400ErrorSingle'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404ErrorSingle'
        '413':
          $ref: '#/components/responses/413ErrorSingle'
        '429':
          $ref: '#/components/responses/429Error'
        '500':
          $ref: '#/components/responses/500ErrorSingle'
components:
  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'
  securitySchemes:
    oauthFlow:
      type: oauth2
      description: client credential flow
      flows:
        clientCredentials:
          tokenUrl: https://api.umbrella.com/auth/v2/token
          scopes:
            deployments.devices.swg:write: Write SWG device settings
            deployments.devices.swg:read: Read SWG device settings
  responses:
    400ErrorSingle:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            description: The information about the error condition.
            required:
            - Error
            properties:
              Error:
                type: string
                description: The message associated with the error condition.
          example:
            Error: Invalid request
    401Error:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            message: Unauthorized request
    403Error:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            message: Forbidden
    404ErrorSingle:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            description: The information about the error condition.
            required:
            - Error
            properties:
              Error:
                type: string
                description: The message associated with the error condition.
          example:
            Error: Not Found
    413ErrorSingle:
      description: Content Too Large
      content:
        application/json:
          schema:
            type: object
            description: The list of `originIds` contains more than 100 origin IDs.
            required:
            - Error
            properties:
              Error:
                type: string
                description: 'Invalid Request: orginIds in the request exceeded max limit - 100.'
                example: 'Invalid Request: orginIds in the request exceeded max limit - 100.'
          example:
            Error: 'Invalid Request: orginIds in the request exceeded max limit - 100.'
    429Error:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            message: Too many requests. Retry request.
    500ErrorSingle:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            description: The information about the error condition.
            required:
            - Error
            properties:
              Error:
                type: string
                description: The message associated with the error condition.
          example:
            Error: Internal server error
  schemas:
    originId:
      description: The origin ID of the device.
      type: integer
      format: int64
      example: 12321231
    value:
      type: string
      enum:
      - '0'
      - '1'
      description: 'Specifies whether to enable the Secure Web Gateway (SWG) device settings.

        Valid values are: `0` or `1` where `1` indicates enable.'
      example: '1'
    error:
      type: object
      description: The information about the error condition.
      properties:
        message:
          type: string
          description: The message associated with the error condition.
        error:
          type: string
          description: The status code for the error condition.
    RegisteredSWGDeviceSettings:
      type: object
      description: The information about the Secure Web Gateway (SWG) setting for the devices in the organization.
      required:
      - totalCount
      - successCount
      - failCount
      - items
      - value
      properties:
        totalCount:
          type: integer
          description: The total number of devices that requested to update the device setting.
        successCount:
          type: integer
          description: The number of devices that successfully changed the device setting.
        failCount:
          type: integer
          description: The number of devices that failed to change the device setting.
        items:
          type: array
          description: The list of device setting status properties.
          items:
            type: object
            description: The status and description for the device setting.
            required:
            - originId
            - code
            - message
            properties:
              originId:
                $ref: '#/components/schemas/originId'
              code:
                type: integer
                description: The status code of the response.
              message:
                type: string
                description: The description of the response.
        value:
          $ref: '#/components/schemas/value'
      example:
        totalCount: 2
        successCount: 1
        failCount: 1
        items:
        - originId: 12321231
          code: 200
          message: success
        - originId: 12313431
          code: 404
          message: The origin ID does not exist.
        value: '1'
    ListSWGDeviceSettings:
      type: array
      description: The list of Secure Web Gateway (SWG) settings for the devices in the organization.
      items:
        type: object
        description: The properties of the secure web gateway settings for the device.
        required:
        - originId
        - name
        - value
        - modifiedAt
        properties:
          originId:
            $ref: '#/components/schemas/originId'
          name:
            type: string
            description: The name of the device setting.
            example: SWG enabled device
          value:
            $ref: '#/components/schemas/value'
          modifiedAt:
            type: string
            description: The date and time when the settings on the device were modified. The timestamp is in the ISO 8601
              date format.
            format: iso-date-time
            example: '2021-04-26 13:12:11'
      example:
      - originId: 124131441
        name: SWGEnabled
        value: '1'
        modifiedAt: '2021-04-26 13:12:11'
      - originId: 124131442
        name: SWG-not-enabled
        value: '0'
        modifiedAt: '2023-04-26 13:12:11'
x-provenance:
  method: harvested
  first_party: true
  harvested: '2026-08-19'
  source: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/swg-devices.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/deployments/swg-devices.yaml
  http_status: 200
  docs: https://developer.cisco.com/docs/cloud-security/