API documentation

Returns a list of all groups belonging to an account as per the specified criteria. This API is paginated and returns 20 groups by default. A group is uniquely identified by a 'group_key'. This key should be used in all the other API referencing a particular group.

Params

Param name	Description
page optional	Page number of results to be fetched, Default 1 Value: Must be Integer.
per optional	Number of group records to be returned in one page, Default 20 Value: Must be Integer.
order_by optional	Field on which resultant group records should be sorted Value: Must be a String
order optional	Order, “asc” or “desc”, in which results should be sorted Value: Must be a String
timestamp_format optional	Format, “str” or “int”, in which timestamps of the group records should be returned, Default “int” Value: Must be a String
search optional	Keywords based on which groups should be searched. Currently you can search groups on - group_key, name or tag Value: Must be a String
scope optional	Matching condition if multiple keywords are specified for search. Valid values are “all” or “any”. Default is “all” Value: Must be a String
pretty optional	Return a pretty formatted response if true, Default is false Value: Must be a Boolean
field_list optional	List of fields required in the result. Value: Must be an array of any type
is_oem optional	Returns groups of child accounts along with groups of oem account if is_oem flag is true. Value: Must be one of: <code>true</code>, <code>false</code>, <code>true</code>, <code>false</code>.

Examples

Request - listing all groups without any criteria
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:49b7q_nYN4YZ2k-MsYx5Ng" https://api.datonis.io/api/v3/groups

Response (returns first 20 records)
{
  "total_count": 3,
  "page": 1,
  "groups": [
    {
      "created_at": 1448436290,
      "description": "",
      "group_key": "ca5ec715f2",
      "group_type": 1,
      "name": "Energy Meters Single Phase 30Amps",
      "scope": "all",
      "thing_expression": null,
      "updated_at": 1448436290,
      "tags": "1-Phase,30-Amps"
    },
    {
      "created_at": 1448436624,
      "description": "",
      "group_key": "d1b3572168",
      "group_type": 2,
      "name": "Red Refrigerators and Machines",
      "scope": "all",
      "thing_expression": "this.user_defined_properties.Color ==...

Request - listing groups by specifying number of groups to be returned at a time (page size) and specific set to be returned (page)
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:49b7q_nYN4YZ2k-MsYx5Ng" -d '{"per":"2","page":"2"}' https://api.datonis.io/api/v3/groups

Response (returns page 2 with 2 groups per page)
{
  "total_count": 3,
  "page": "2",
  "groups": [
    {
      "created_at": 1448437406,
      "description": "",
      "group_key": "88a714c562",
      "group_type": 1,
      "name": "Automated Washing Machines",
      "scope": "all",
      "thing_expression": null,
      "updated_at": 1448437406,
      "tags": "automated"
    }
  ]
}

Request - listing groups ordered by a field with string formatted timestamps
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:49b7q_nYN4YZ2k-MsYx5Ng" -d '{"timestamp_format":"str","order_by":"created_at","order":"desc"}' https://api.datonis.io/api/v3/groups

Response (returns groups in the reverse order of time that they were created at with timestamps in string format)
{
  "total_count": 3,
  "page": 1,
  "groups": [
    {
      "created_at": "2015/11/25 07:43:26",
      "description": "",
      "group_key": "88a714c562",
      "group_type": 1,
      "name": "Automated Washing Machines",
      "scope": "all",
      "thing_expression": null,
      "updated_at": "2015/11/25 07:43:26",
      "tags": "automated"
    },
    {
      "created_at": "2015/11/25 07:30:24",
      "description": "",
      "group_key": "d1b3572168",
      "group_type": 2,
      "name": "Red Refrigerators and Machines",
      "scope": "all",
      "thing_expression":...

Request - listing groups based on some search criteria with all keywords matching
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:49b7q_nYN4YZ2k-MsYx5Ng" -d '{"search":"Washing Machines"}' https://api.datonis.io/api/v3/groups

Response (returns groups containing both keywords 'Washing' as well as 'Machines')
{
  "total_count": 1,
  "page": 1,
  "groups": [
    {
      "created_at": 1448437406,
      "description": "",
      "group_key": "88a714c562",
      "group_type": 1,
      "name": "Automated Washing Machines",
      "scope": "all",
      "thing_expression": null,
      "updated_at": 1448437406,
      "tags": "automated"
    }
  ]
}

Request - listing groups based on some search criteria with any of the keywords matching
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:49b7q_nYN4YZ2k-MsYx5Ng" -d '{"search":"Washing Machines", "scope":"any"}' https://api.datonis.io/api/v3/groups

Response (returns groups containing either of the keywords 'Washing' or 'Machines')
{
  "total_count": 2,
  "page": 1,
  "groups": [
    {
      "created_at": 1448437406,
      "description": "",
      "group_key": "88a714c562",
      "group_type": 1,
      "name": "Automated Washing Machines",
      "scope": "all",
      "thing_expression": null,
      "updated_at": 1448437406,
      "tags": "automated"
    },
    {
      "created_at": 1448436624,
      "description": "",
      "group_key": "d1b3572168",
      "group_type": 2,
      "name": "Red Refrigerators and Machines",
      "scope": "all",
      "thing_expression": "this.user_defined_properties.Color == 'Red'",
      "updated_at": 1448437019,
      "tags": ""
    }
  ]
}

Returns details of the group specified

Params

Param name	Description
pretty optional	Return a pretty formatted response if true, Default is false Value: Must be a Boolean
is_oem optional	Show group of child account if is_oem flag is true. Value: Must be one of: <code>true</code>, <code>false</code>, <code>true</code>, <code>false</code>.

Examples

Request - get details of the specified group (group_key specified as a part of the url)
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:49b7q_nYN4YZ2k-MsYx5Ng" https://api.datonis.io/api/v3/groups/88a714c562

Response (details of the group requested)
{
  "group": {
    "created_at": 1448437406,
    "description": "",
    "group_key": "88a714c562",
    "group_type": 1,
    "name": "Automated Washing Machines",
    "scope": "all",
    "thing_expression": null,
    "updated_at": 1448437406,
    "tags": "automated"
  }
}

Creates a group with given parameters

Params

Param name	Description
group required	Object containing information about the group to be created Value: Must be a Hash
pretty optional	Return a pretty formatted response if true, Default is false Value: Must be a Boolean
is_oem optional	Create group in child account by oem user if is_oem flag is true. Value: Must be a Boolean
child_organisation_key optional	Organisation key of child account where oem user wants to create group. Required field if is_oem is present. Value: Must be a String

Examples

Request
  curl -X POST -H "Content-Type:application/json" -H "X-Auth-Token:49b7q_nYN4YZ2k-MsYx5Ng" -d '{"group":{"name":"Energy Meters Three Phase 45Amps","description":"Energy Meters Three Phase 45Amps","scope":"all","tags":"3-Phase,45-Amps"}}' https://api.datonis.io/api/v3/groups

Response (details of the group created)
{
  "group": {
    "created_at": 1448438832,
    "description": "Energy Meters Three Phase 45Amps",
    "group_key": "ace98fcd44",
    "group_type": 1,
    "name": "Energy Meters Three Phase 45Amps",
    "scope": "all",
    "thing_expression": null,
    "updated_at": 1448438832,
    "tags": "3-Phase,45-Amps"
  }
}

Updates the group with given parameters

Params

Param name	Description
group required	Object containing information about the group to be updated Value: Must be a Hash
pretty optional	Return a pretty formatted response if true, Default is false Value: Must be a Boolean
is_oem optional	Update group in child account by oem user if is_oem flag is true. Value: Must be a Boolean

Examples

Request - containing parameters to be modified
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:49b7q_nYN4YZ2k-MsYx5Ng" -d '{"group":{"name":"Energy Meters Three Phase 50Amps","description":"Energy Meters Three Phase 50Amps","tags":"3-Phase,50-Amps"}}' https://api.datonis.io/api/v3/groups/ace98fcd44

Response (details of the group updated)
{
  "group": {
    "created_at": 1448438832,
    "description": "Energy Meters Three Phase 50Amps",
    "group_key": "ace98fcd44",
    "group_type": 1,
    "name": "Energy Meters Three Phase 50Amps",
    "scope": "all",
    "thing_expression": null,
    "updated_at": 1448438952,
    "tags": "3-Phase,50-Amps"
  }
}

Deletes the specified group from the system

Params

Param name	Description
pretty optional	Return a pretty formatted response if true, Default is false Value: Must be a Boolean
is_oem optional	Delete group in child account by oem user if is_oem flag is true. Value: Must be a Boolean

Examples

Request
  curl -X DELETE -H "Content-Type:application/json" -H "X-Auth-Token:49b7q_nYN4YZ2k-MsYx5Ng"  https://api.datonis.io/api/v3/groups/ace98fcd44

Response
{
}

Adds specified tags to the existing list of tags associated with the group

Params

Param name	Description
tags optional	Comma separated list of tags to be added to the group Value: Must be a String
pretty optional	Return a pretty formatted response if true, Default is false Value: Must be a Boolean
is_oem optional	Add tag in group of child account by oem user if is_oem flag is true. Value: Must be a Boolean

Examples

Request - add tags to the specified group (group_key specified as a part of the url)
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:49b7q_nYN4YZ2k-MsYx5Ng" -d '{"tags":"Balanced"}' https://api.datonis.io/api/v3/groups/ace98fcd44/tag

Response (group with updated tags)
{
  "group": {
    "created_at": 1448438832,
    "description": "Energy Meters Three Phase 50Amps",
    "group_key": "ace98fcd44",
    "group_type": 1,
    "name": "Energy Meters Three Phase 50Amps",
    "scope": "all",
    "thing_expression": null,
    "updated_at": 1448439061,
    "tags": "3-Phase,50-Amps,Balanced"
  }
}

Removes specified tags from the group

Params

Param name	Description
tags optional	Comma separated list of tags to be removed from the group Value: Must be a String
pretty optional	Return a pretty formatted response if true, Default is false Value: Must be a Boolean
is_oem optional	Remove tag from group of child account by oem user if is_oem flag is true. Value: Must be a Boolean

Examples

Request - remove tags from the specified group (group_key specified as a part of the url)
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:49b7q_nYN4YZ2k-MsYx5Ng" -d '{"tags":"Balanced"}' https://api.datonis.io/api/v3/groups/ace98fcd44/untag

Response (group with updated tags)
{
  "group": {
    "created_at": 1448438832,
    "description": "Energy Meters Three Phase 50Amps",
    "group_key": "ace98fcd44",
    "group_type": 1,
    "name": "Energy Meters Three Phase 50Amps",
    "scope": "all",
    "thing_expression": null,
    "updated_at": 1448439142,
    "tags": "3-Phase,50-Amps"
  }
}

Group

GET /api/v3/groups
List all groups

Params

Examples

GET /api/v3/groups/:group_key
Fetch details of a specific group

Params

Examples

POST /api/v3/groups
Create a group

Params

Examples

PUT /api/v3/groups/:group_key
Updates a group

Params

Examples

DELETE /api/v3/groups/:group_key
Delete the specified group

Params

Examples

PUT /api/v3/groups/:group_key/tag
Add specified tags to a group

Params

Examples

PUT /api/v3/groups/:group_key/untag
Remove specified tags from the group

Params

Examples

Group

GET /api/v3/groups List all groups

Params

Examples

GET /api/v3/groups/:group_key Fetch details of a specific group

Params

Examples

POST /api/v3/groups Create a group

Params

Examples

PUT /api/v3/groups/:group_key Updates a group

Params

Examples

DELETE /api/v3/groups/:group_key Delete the specified group

Params

Examples

PUT /api/v3/groups/:group_key/tag Add specified tags to a group

Params

Examples

PUT /api/v3/groups/:group_key/untag Remove specified tags from the group

Params

Examples

GET /api/v3/groups
List all groups

GET /api/v3/groups/:group_key
Fetch details of a specific group

POST /api/v3/groups
Create a group

PUT /api/v3/groups/:group_key
Updates a group

DELETE /api/v3/groups/:group_key
Delete the specified group

PUT /api/v3/groups/:group_key/tag
Add specified tags to a group

PUT /api/v3/groups/:group_key/untag
Remove specified tags from the group