Device42 Cloud API

openapi: 3.2.0
info:
  title: Device42 Cloud API
  version: '2.0'
  description: 'API Overview


    RESTful APIs are supported in Device42 as one of the primary methods of entering, editing and retrieving data.'
  contact:
    name: Device42
    email: support@device42.com
servers:
- url: https://<host>
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Cloud
paths:
  /api/1.0/auto_discovery/cloudaccount/:
    get:
      operationId: getAuto_discoveryCloudaccount
      summary: Get all cloud jobs
      description: Retrieves all cloud autodiscovery jobs
      tags:
      - Cloud
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  jobs:
                    type: array
                    items:
                      properties:
                        job_id:
                          example: 54
                        name:
                          example: Oraclejob54
                        cloud_type:
                          example: oracle cloud
                        vendor:
                          example: oracle
                        remote_collector:
                          example: rc-223-la
                        user_id:
                          example: sjapo4duy17re45
                        key_file:
                          example: b48b-9acd57b4a3a0
                        tenant_id:
                          example: a41cde6e-8f12-44b8
                        oracle_regions:
                          example: us-ashburn-1,us-phoenix-1
                        instance_not_found:
                          example: Change status
                        collect_db_info:
                          example: 'no'
                        db_usernames:
                          example: []
                        db_password_ids:
                          example: []
                        add_tags_to_device:
                          example: 2
                        add_tags_as_custom_fields:
                          example: 3
                        vendor_metadata_source:
                          example: 2
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: postAuto_discoveryCloudaccount
      description: 'Create/update a cloud autodiscovery job.


        Required parameters by cloud vendor or job type.

        (API parameter = UI equivalent)

        ALL DISCOVERY JOBS

        - name = Name

        - cloud_type = Cloud Type

        AMAZON AWS

        - accountid = Access Key ID

        - secret_key OR secret_key_id = Secret Key

        - regions = Regions


        MICROSOFT AZURE

        - auth_type = Authentication Type

        - accountid = Client ID (Service Principal) or Username (User Credentials)

        - secret_key OR secret_key_id = Client Secret (Service Principal) or Password (User Credentials)

        - subscriptionid = Subscription ID

        - tenant = Tenant ID

        LINODE

        - api_key OR api_key_id = API Key

        DIGITALOCEAN

        - token_key = Token Key

        OPENSTACK

        - ip = URL

        - username = User

        - secret_key OR secret_key_id = Password

        - tenant = Project Name

        GOOGLE CLOUD

        - tenant = Project ID

        - secret_key OR secret_key_id = Credentials JSON

        - google_regions = Zones

        ALIBABA CLOUD

        - accountid = Access Key ID

        - secret_key OR secret_key_id = Access Key Secret

        ORACLE CLOUD

        - accountid = User ID

        - api_key OR api_key_id = Fingerprint

        - secret_key OR secret_key_id = Key File

        - tenant = Tenant ID

        - oracle_regions = Zones

        STANDALONE KUBERNETES

        - ip = URL

        - auth_type = Authentication Type

        - accountid = Bearer Token or Basic Credentials (depending on Authentication Type)

        ARISTA CLOUDVISION

        - server = node(s)

        - auth_type = Authentication Type

        - username (Basic Credentials Only)

        - secret_key (password if auth_type = Basic Authentication, API Token if auth_type = Bearer Token)

        - tenant (CVSaaS only)

        JAMF

        - ip = URL

        - accountid = User ID

        WORKSPACE ONE

        - ip = URL

        - tenant = Tenant

        - accountid = Basic Credentials'
      summary: Create/update cloud job
      tags:
      - Cloud
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  description: Name of the discovery job; required for all jobs.
                  type: string
                cloud_type:
                  description: Required for all jobs.
                  type: string
                  enum:
                  - Amazon AWS
                  - Microsoft Azure
                  - Linode
                  - DigitalOcean
                  - OpenStack
                  - Google Cloud
                  - Alibaba Cloud
                  - Oracle Cloud
                  - Standalone Kubernetes
                  - Arista CloudVision
                  - Jamf
                  - Workspace ONE
                secret_key_id:
                  description: Amazon AWS, MS Azure, OpenStack, Google Cloud, Alibaba Cloud, Oracle Cloud
                  type: string
                vendor:
                  description: The cloud vendor
                  type: string
                kubernetes_discovery:
                  description: Available for Amazon AWS, Microsoft Azure, and standalone Kubernetes. <br>Yes / No
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                remote_collector_id:
                  description: ID number of the remote collector (RC) to use for the job.
                  type: string
                customer_id:
                  description: Customer ID number for discovered devices.
                  type: string
                clear_customer:
                  description: Clear all previously set customers on discovered objects.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                  default: 'no'
                device_name_format:
                  description: Name format for discovered cloud instances (only for Alibaba Cloud, Amazon AWS, Google Cloud, MS Azure, Oracle Cloud).
                  type: string
                  enum:
                  - Instance ID + name (if defined)
                  - Instance ID
                  - Name (only use if unique)
                container_not_found:
                  description: For Kubernetes discovery.<br>1 = changes status, 2 = delete container
                  type: string
                  enum:
                  - '1'
                  - '2'
                auth_type:
                  description: Type of authentication credentials for MS Azure and Standalone Kubernetes.
                  type: string
                  enum:
                  - User Credentials
                  - Service Principal
                  - Bearer Token
                  - Basic Credentials
                accountid:
                  description: Required for Alibaba Cloud, Amazon AWS, Kubernetes, MS Azure, Oracle Cloud, Jamf, Workspace ONE.
                  type: string
                vrfgroup:
                  description: name of vrf group for discovered subnets (added in v10.4.0)
                  type: string
                notes:
                  description: Any additional notes
                  type: string
                instance_not_found:
                  description: 1 = changes status, 2 = delete instance
                  type: string
                  enum:
                  - '1'
                  - '2'
                strip_domain_name:
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                add_suffix:
                  type: string
                match_name_only_for_virtuals:
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                match_name_only_for_hypervisor:
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                groups:
                  description: name of one or more groups separated by commas
                  type: string
                object_category:
                  description: category of discovered vservers and vms
                  type: string
                debug_level:
                  type: string
                  enum:
                  - No Debug
                  - Normal Debug
                  - Extended Debug
                clear_existing_schedule:
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                schedule_time:
                  description: 'Time in HH:MM format if you want to schedule the job. Note: Must be formatted as text NOT date. For multiple schedules, separate with a slash (/).'
                  type: string
                schedule_days:
                  description: Comma separated days of week, where Monday = 0. e.g. 0,1,2 will set the job for Mon, Tue and Wed. For multiple schedules, separate with a slash (/).
                  type: string
                secret_key:
                  description: Amazon AWS, MS Azure, OpenStack, Google Cloud, Alibaba Cloud, Oracle Cloud
                  type: string
                regions:
                  description: Comma separated region names for Amazon AWS
                  type: string
                aws_roles:
                  description: Comma separated names of Amazon AWS Roles
                  type: string
                aws_roles_remove:
                  description: Comma separated names of aws_roles to remove from a cloud discovery job. Use <b> * </b> to clear all aws_roles from a cloud discovery job.
                  type: string
                azure_cloud_definition:
                  description: Cloud Definition for MS Azure discovery jobs.
                  type: string
                  enum:
                  - Public
                  - China
                  - US Gov.
                  - German
                google_regions:
                  description: comma-separated list of Google region names
                  type: string
                oracle_regions:
                  description: comma-separated list of Oracle region names
                  type: string
                subscriptionid:
                  description: MS Azure Subscription ID
                  type: string
                ip:
                  description: OpenStack URL; Standalone Kubernetes URL; Jamf URL; Workspace ONE URL;
                  type: string
                server:
                  description: (Arista CloudVision; IP(s) or hostname(s) for CVP nodes)
                  type: string
                tenant:
                  description: OpenStack Project name; Google Project ID; Oracle Tenant ID; Arista CloudVision Tenant; Workspace ONE Tentant;
                  type: string
                username:
                  description: OpenStack username - required for OpenStack
                  type: string
                api_key:
                  description: Oracle Cloud Fingerprint; Linode API Key
                  type: string
                api_key_id:
                  description: Oracle Cloud Fingerprint; Linode API Key
                  type: string
                api_token:
                  description: Linode API token - Required for Linode
                  type: string
                token_key:
                  description: DigitalOcean Token Key - required for DigitalOcean.
                  type: string
                alibaba_regions:
                  description: Comma-separated list of Alibaba Cloud region names.
                  type: string
                features:
                  description: 'Comma-separated list of features.  Choices for AWS are: s3, ebs, route53, databases, elb, functions, redshift, dynamodb, efs.  Choices for GCP are: databases.  Choices for AZURE are: databases, functions.  Use ''D42_NULL'' to disable advanced features for Cloud discovery jobs.'
                  type: string
                collect_db_info:
                  description: Collect database server information. Use yes or no. ( Cosmos DB for PostgreSQL only )
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                db_username:
                  description: Username for DB discovery. Required if collect_db_info is 'yes'
                  type: string
                db_password:
                  description: Password for DB discovery. Required if collect_db_info is 'yes'
                  type: string
                extended_discovery:
                  description: Collect summary information on all AWS/Azure resources that are not supported by full discovery yet. Use yes or no.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                chromeos_discovery:
                  description: Collect summary information on all ChromeOS devices in Google Cloud Platform discovery. Use yes or no.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                use_env_credentials:
                  description: Use cloud credentials from environment not from job. Only supported for AWS.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                discover_all_subscriptions:
                  description: Discover all Subscriptions within Azure Tenant.
                  type: boolean
                service_level:
                  description: Must already exist
                  type: string
                tags:
                  description: add tags (comma separated)
                  type: string
                tags_remove:
                  description: remove tags (comma separated)
                  type: string
                add_tags_as_custom_fields:
                  description: 'The way how to add vendor metadata.<br> 1: Do nothing 2: Add as custom fields 3: Add as tags'
                  type: integer
                  enum:
                  - 1
                  - 2
                  - 3
                vendor_metadata_source:
                  description: 'Metadata source ( For Google Cloud Only ).<br> 1: Labels 2: Custom Metadata'
                  type: integer
                  enum:
                  - 1
                  - 2
                remove_password_ids:
                  description: Comma separated list of D42 IDs of existing secret records to be removed from the job.
                  type: string
                add_tags_to_device:
                  description: 'Add tags to device ( For Google Cloud Only ).<br> 1: Do nothing 2: Import Tags'
                  type: integer
                  enum:
                  - 1
                  - 2
              required:
              - name
              - cloud_type
        required: true
      responses:
        '200':
          description: 'The above command returns results like this:'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      operationId: putAuto_discoveryCloudaccount
      description: Execute cloud job
      summary: Run cloud job
      tags:
      - Cloud
      requestBody:
        $ref: '#/components/requestBodies/putAuto_discoveryNetworks'
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example: Task is scheduled for running
                  code:
                    example: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    Forbidden:
      description: Forbidden (The resource requested is hidden)
      content:
        application/json:
          example:
            errors:
            - code: 403
              reason: Forbidden
              title: Forbidden
              detail: The resource requested is hidden
    BadRequest:
      description: Bad Request (A validation exception has occurred.)
      content:
        application/json:
          example:
            errors:
            - code: 400
              reason: BAD_REQUEST
              title: The error response code title.
              detail: Details of the error response.
    Unauthorized:
      description: Unauthorized (Invalid credentials.)
      content:
        application/json:
          example:
            errors:
            - code: 401
              reason: Unauthorized
              title: Unauthorized
              detail: Invalid credentials.
    InternalServerError:
      description: Internal Server Error (A required parameter is missing or there is an issue with the server. Check the returned 'msg' field from the call.)
      content:
        application/json:
          example:
            errors:
            - code: 500
              reason: Internal Server Error
              title: Internal Server Error
              detail: A required parameter is missing or there is an issue with the server. Check the returned 'msg' field from the call.
    NotFound:
      description: Not Found (The specified resource could not be found)
      content:
        application/json:
          example:
            errors:
            - code: 404
              reason: Not Found
              title: Not Found
              detail: The specified resource could not be found.
    ServiceUnavailable:
      description: Service Unavailable (Please check if your Device42 instance is working normally.)
      content:
        application/json:
          example:
            errors:
            - code: 503
              reason: Service Unavailable
              title: Service Unavailable
              detail: Please check if your Device42 instance is working normally.
  requestBodies:
    putAuto_discoveryNetworks:
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            properties:
              name:
                description: name of the job - required if no job_id
                type: string
              job_id:
                description: D42 ID for the job - required if no name
                type: string
              run:
                description: yes to start
                type: string
            required:
            - run
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using a Device42 user's username and password.
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from POST /tauth/1.0/token/ using an API Client's key/secret as Basic auth credentials.