Groups

List groups: GET /groups

A list of groups will be returned where the current user is a member of.

URLhttps://api.sense-os.nl/groups
MethodGET
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType
publicWith this parameter set to 1, only public groups are returned and when it is set to 0 only private groups are returned. xsd:integer
totalReturns a count of the total amount of items xsd:integer
pageThis parameter specifies which page of the results must be retrieved. The page offset starts at 0. xsd:integer
per_pageThis parameter specifies the amount of items that must be received at once. The maximum amount is 1000 items and the default amount is 100 items. xsd:integer
sortSpecifies the sort direction, either ASC or DESC. xsd:string
sort_fieldThe field to sort on. This can be: id, username, email, public, description, name. xsd:string

List all groups: GET /groups/all

This method will return all the groups on CommonSense that are not hidden.

URLhttps://api.sense-os.nl/groups/all
MethodGET
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType
publicWith this parameter set to 1, only public groups are returned and when it is set to 0 only private groups are returned. xsd:integer
totalReturns a count of the total amount of items xsd:integer
pageThis parameter specifies which page of the results must be retrieved. The page offset starts at 0. xsd:integer
per_pageThis parameter specifies the amount of items that must be received at once. The maximum amount is 1000 items and the default amount is 100 items. xsd:integer
sortSpecifies the sort direction, either ASC or DESC. xsd:string
sort_fieldThe field to sort on. This can be: id, username, email, public, description, name. xsd:string

Delete group: DELETE /groups/{group_id}

This methods deletes a user from the group. Only members with the right to delete users can perform this action. If a user leaves a group then all his shared sensors will be removed from this group automatically.

URLhttps://api.sense-os.nl/groups/{group_id}
MethodDELETE
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType

Create group: POST /groups

This method will create a group to which the current user will be added. A group can optionally have a username and password which can be used for login. The password must be in md5 format. A group can also have an access_password which can be used for users to add themselves to the group. If a user joins a private group without access_password then the user first needs to be accepted by a member with the add user rights. The only field that is required is the group name, the rest of the values will be set to the default. The default values are:
"name":"", // name of the group
"email":"", // email of the group
"username":"", // username for login
"mobile":"" // mobile number of the group
"description":"", // description of the group
"public":false, // allows every user to join the group
"hidden":false, // hides the group from the main list
"anonymous":false, // anonymous membership, overrides user info display requirements
"access_password":"", // optional md5 hashed access password for entering a private group
"required_sensors":"", // an array with the names of the sensors that a user needs to have in
// order to join the group, the sensors will be shared automatically
"optional_sensors":"", // sensors that will be shared automatically when a user is in a group
// default group rights for new users:
"default_list_users":true, // a user may list group users
"default_add_users":false, // a user may add other users
"default_remove_users":false, // a user may remove other users
"default_list_sensors":true, // a user may list the sensors
"default_add_sensors":true, // a user may add sensors
"default_remove_sensors":false, // a user may remove sensors
// user info display requirements
"required_show_first_name":true, // users need to show their first name
"required_show_surname":true, // users need to show their surname
"required_show_email":false, // users need to show email
"required_show_phone_number":false, // users need to show phone number
"required_show_username":false, // users need to show their username
"required_show_id":true, // users need to show their id
"required_show_zipcode":true, // users need to show their zipcode
"required_show_address":true, // users need to show their address
"required_show_country":true, // users need to show their country

URLhttps://api.sense-os.nl/groups
MethodPOST
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType

Request Body

The group object

{
    "group": {
        "name": "New private group",
        "anonymous": 1,
        "public": 0,
        "hidden": 0,
        "access_password": "098f6bcd4621d373cade4e832627b4f6",
        "description": "password protected group",
        "required_sensors": [
            "noise_sensor",
            "position"
        ],
        "default_list_users": 1,
        "default_add_users": 0,
        "default_remove_users": 0,
        "default_list_sensors": 1,
        "default_add_sensors": 1,
        "default_remove_sensors": 0,
        "required_show_id": 1,
        "required_show_email": 0,
        "required_show_first_name": 1,
        "required_show_surname": 0,
        "required_show_phone_number": 0,
        "required_show_username": 0
    }
}

Update group: PUT /groups/{group_id}

This method will update the details of a group. Only the values specified as input will be updates. Every member of the group can update the group details

URLhttps://api.sense-os.nl/groups/{group_id}
MethodPUT
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType

Request Body

The group object

{
    "group": {
        "name": "New private group",
        "anonymous": 1,
        "public": 0,
        "hidden": 0,
        "access_password": "098f6bcd4621d373cade4e832627b4f6",
        "description": "password protected group",
        "required_sensors": [
            "noise_sensor",
            "position"
        ],
        "default_list_users": 1,
        "default_add_users": 0,
        "default_remove_users": 0,
        "default_list_sensors": 1,
        "default_add_sensors": 1,
        "default_remove_sensors": 0,
        "required_show_id": 1,
        "required_show_email": 0,
        "required_show_first_name": 1,
        "required_show_surname": 0,
        "required_show_phone_number": 0,
        "required_show_username": 0
    }
}

List group users: GET /groups/{group_id}/users

This methods returns the members of the group as a list of users. Only group members with the rights to access the user list can perform this action. Based on the user info display requirements set by the members certain details will be shown. Members who are allowed to add users to the group can also see an extra field called accepted. This field displays whether the user is already accepted to the group, if it is set to false then the member with the add user rights can accept this user by adding him to the group.

URLhttps://api.sense-os.nl/groups/{group_id}/users
MethodGET
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType
detailsThis parameter specifies whether more details such as permissions should be shown. xsd:string

Delete group user: DELETE /groups/{group_id}/users/{user_id}

This methods deletes a user from the group. Only members with the right to delete users can perform this action. If a user leaves a group then all his shared sensors will be removed from this group automatically.

URLhttps://api.sense-os.nl/groups/{groupid}/users/{userid}
MethodDELETE
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType

Add users to a group: POST /groups/{group_id}/users

This method will add a user to the group. To add a user at least a username or user_id must be specified. Users can only at themself to a group. When joining a public group or a private group with access password a user is automatically accepted in a group. To join a private group without access password members of the group with the add user right should accept a user in a group via this function.

URLhttps://api.sense-os.nl/groups/{group_id}/users
MethodPOST
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType

Request Body

The users array

{
    "users": [
        {
            "user": {
                "id": "3",
                "username": "testuser"
            },
            "group_permissions": {
                "list_users": 1,
                "add_users": 0,
                "remove_users": 0,
                "list_sensors": 1,
                "add_sensors": 1,
                "remove_sensors": 0,
                "edit_group": 0
            },
            "display_user_info": {
                "show_first_name": 1,
                "show_surname": 1,
                "show_email": 0,
                "show_phone_number": 0,
                "show_username": 0,
                "show_id": 1
            },
            "sensors": [
                109,
                201
            ],
            "access_password": "098f6bcd4621d373cade4e832627b4f6"
        }
    ]
}

Update group users: PUT /groups/{group_id}/users/{user_id}

This method will update the properties of a user in the group.

URLhttps://api.sense-os.nl/groups/{groupid}/users/{userid}
MethodPUT
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType

Request Body

The user object

{
    "group_permissions": {
        "list_users": 1,
        "add_users": 0,
        "remove_users": 0,
        "list_sensors": 1,
        "add_sensors": 1,
        "remove_sensors": 0,
        "edit_group": 0
    },
    "display_user_info": {
        "show_first_name": 1,
        "show_surname": 1,
        "show_email": 0,
        "show_phone_number": 0,
        "show_username": 0,
        "show_id": 1
    }
}

List group sensors: GET /groups/{group_id}/sensors

This method returns a list of sensors in the group. Only users with the list sensors right can list the sensors of a group.

URLhttps://api.sense-os.nl/groups/{group_id}/sensors
MethodGET
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType
pageThis parameter specifies which page of the results must be retrieved. The page offset starts at 0. xsd:integer
per_pageThis parameter specifies the amount of items that must be received at once. The maximum amount is 1000 items and the default amount is 100 items. xsd:integer
physicalWith this parameter set to 1, only physical sensors will be returned. Also information of the sensor's parent device will be given in the fields device_device_type and device_device_uuid unless the parameter owned is used. xsd:boolean
detailsTo get all the related data as device, environment and owner the parameter details=full can be used. If only a list of sensor id's is needed then details=no can be used. xsd:string

Add sensor to a group: POST /groups/{group_id}/sensors

This method will add sensors to the group. Only members of the group with add sensor rights can add a sensor to the group.

URLhttps://api.sense-os.nl/groups/{group_id}/sensors
MethodPOST
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType

Request Body

The sensors array

{
    "sensors": [
        {
            "id": 1
        },
        {
            "id": "2"
        }
    ]
}

Delete a sensor from a group: DELETE /groups/{group_id}/sensors/{sensor_id}

This methods deletes a sensor from the group. Only members with the right to delete sensors can perform this action. If a user leaves a group then all his shared sensors will be removed from this group automatically.

URLhttps://api.sense-os.nl/groups/{groupid}/sensors/{sensorid}
MethodDELETE
Need AuthTrue

Request Headers

NameDefaultTypeStyleRequired
Accept*xsd:stringheaderTrue

Request Parameters

NameDescriptionType