Esper Device Group API

openapi: 3.2.0
info:
  description: "# Introduction\nEsper 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. With these APIs, you can orchestrate and manage devices that have been provisioned against your Esper Manage environment. Furthermore, these APIs allows you to manage the Android applications installed on your Dedicated Device fleet. To read more about the various capabilities of Esper APIs and Esper managed devices, please visit [esper.io](https://esper.io). This guide describes all the available APIs in detail, along with code samples for you to quickly ramp up to using them.\\\nTo use these APIs you will need to create a developer account with Esper and get access to the Esper Dev Console and the Esper ManageDashboard. You can find out more about Esper and sign up for free at [esper.io/signup](https://esper.io/signup)\\\nWe've done our best to keep this document up to date, but if you find any issues, please reach out to us at developer@esper.io.\n\n# SDK\n\n  You are welcome to use your favorite HTTP/REST library for your programming language in order to call these APIs, or you can use our SDK (currently supporting [python](https://github.com/esper-io/esper-client-py)) to do so.\n\n\n# Authentication\nThe client needs to send authentication details to access the Esper APIs by generating and applying an API key. Be sure to sign up for your free trial account with Esper Dev to generate your key:\n\n# Errors\nThe APIs use standard HTTP status codes to indicate success or failure. All error responses will have a JSON body in the following format:\n\n```\n{\n  \"errors\": [],\n  \"message\": \"error message\",\n  \"status\": 400\n}\n```\n* `errors` -  List of error details\n* `message` - Error description\n* `status` - HTTP status code\n"
  version: 1.0.0
  title: ESPER API REFERENCE Application 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
    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
    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
  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