Esper Device Group API

openapi: 3.2.0
info:
  description: '# Introduction

    Esper APIs are a set of REST-based APIs that help you programmatically control and monitor Android-based Dedicated Devices running the Esper agent using Esper Manage.'
  version: 1.0.0
  title: ESPER API REFERENCE Device Group API
  termsOfService: https://esper.io/terms-of-service
  contact:
    email: developer@esper.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://foo-api.esper.cloud/api
tags:
- name: Device Group
  description: APIs for device group management
  externalDocs:
    description: Find out more about device group management
    url: https://docs.esper.io/home/console.html#groups
paths:
  /enterprise/{enterprise_id}/devicegroup/:
    parameters:
    - name: enterprise_id
      description: A UUID string identifying enterprise.
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getAllGroups
      summary: List device groups
      description: Returns EnterpriseDeviceGroup list
      parameters:
      - name: name
        in: query
        description: Filter by group name
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
          default: 20
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                required:
                - count
                - results
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type:
                    - string
                    - 'null'
                    format: url
                  previous:
                    type:
                    - string
                    - 'null'
                    format: url
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeviceGroup'
      security:
      - apiKey: []
      tags:
      - Device Group
    post:
      operationId: createGroup
      summary: Create a device group
      description: Returns EnterpriseDeviceGroup instance
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceGroup'
      security:
      - apiKey: []
      tags:
      - Device Group
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceGroupUpdate'
        required: true
  /enterprise/{enterprise_id}/devicegroup/{group_id}/:
    parameters:
    - name: group_id
      in: path
      description: A UUID string identifying this enterprise device group.
      required: true
      schema:
        type: string
        format: uuid
    - name: enterprise_id
      description: A UUID string identifying enterprise.
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getGroupById
      summary: Get device group information
      description: Returns EnterpriseDeviceGroup instance
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceGroup'
      security:
      - apiKey: []
      tags:
      - Device Group
    put:
      operationId: updateGroup
      summary: Update device group
      description: Returns EnterpriseDeviceGroup instance
      parameters:
      - name: action
        in: query
        required: false
        description: add / remove / rename / move
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceGroup'
      security:
      - apiKey: []
      tags:
      - Device Group
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceGroupUpdate'
        required: true
    patch:
      operationId: partialUpdateGroup
      summary: Partial update group
      description: Returns EnterpriseDeviceGroup instance
      parameters:
      - name: action
        in: query
        required: false
        description: add / remove / rename / move
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceGroup'
      security:
      - apiKey: []
      tags:
      - Device Group
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceGroupPartialUpdate'
        required: true
    delete:
      operationId: deleteGroup
      summary: Delete a device group
      description: Emtpy response
      responses:
        '204':
          description: successful operation
      security:
      - apiKey: []
      tags:
      - Device Group
components:
  schemas:
    DeviceGroupUpdate:
      required:
      - name
      type: object
      properties:
        id:
          title: Id
          description: Group id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          description: Group name
          type: string
        created_on:
          title: Created on
          description: Date and time of when the group was created
          type: string
          format: date-time
          readOnly: true
        enterprise:
          title: Enterprise
          description: Enterprise url
          type: string
          format: url
          readOnly: true
        parent:
          title: Parent
          description: Parent group id
          type: string
          format: uuid
        device_ids:
          title: Device ids
          type: array
          description: Devices ids
          items:
            type: string
            format: uuid
          uniqueItems: true
        device_count:
          title: Device count
          type: integer
          readOnly: true
        path:
          title: Path
          type: string
          description: Path of the group
          readOnly: true
        children_count:
          title: Children Count
          description: Count of child groups
          type: integer
          readOnly: true
    DeviceGroup:
      required:
      - name
      type: object
      properties:
        id:
          title: Id
          description: Group id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          description: Group name
          type: string
        created_on:
          title: Created on
          description: Date and time of when the group was created
          type: string
          format: date-time
          readOnly: true
        enterprise:
          title: Enterprise
          description: Enterprise url
          type: string
          format: url
          readOnly: true
        parent:
          title: Parent
          description: Parent group url
          type: string
          format: url
        device_count:
          title: Device count
          description: Count of devices in the group
          type: integer
          readOnly: true
        path:
          title: Path
          description: Path of the group
          type: string
          readOnly: true
        children_count:
          title: Children count
          description: Count of child groups
          type: integer
          readOnly: true
    DeviceGroupPartialUpdate:
      type: object
      properties:
        id:
          title: Id
          description: Group id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          description: Group name
          type: string
        created_on:
          title: Created on
          description: Date and time of when the group was created
          type: string
          format: date-time
          readOnly: true
        enterprise:
          title: Enterprise
          description: Enterprise url
          type: string
          format: url
          readOnly: true
        parent:
          title: Parent
          description: Parent group id
          type: string
          format: uuid
        device_ids:
          title: Device ids
          type: array
          description: Device ids
          items:
            type: string
            format: uuid
          uniqueItems: true
        device_count:
          title: Device count
          description: Count of devices in the group
          type: integer
          readOnly: true
        path:
          title: Path
          description: Path of the group
          type: string
          readOnly: true
        children_count:
          title: Children Count
          description: Count of child groups
          type: integer
          readOnly: true
  securitySchemes:
    apiKey:
      description: "#### API KEY - Access Token\nAccess token for APIs passed as authorization header in calls. You need to generate this from your Esper Dev Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper Dev account. Please follow the instructions [here](https://docs.esper.io/home/module/genapikey.html) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication scheme [here](https://console-docs.esper.io/API/generate.html).\n"
      name: Authorization
      type: apiKey
      in: header
x-tagGroups:
- name: API Reference
  tags:
  - Enterprise
  - Application
  - Application V1
  - Device
  - Device Group
  - Commands
  - Group Commands
  - Token
  - Commands V2
  - Enterprise Policy
  - Geofence
  - Reports
  - Subscription
  - Content