Group API

Groups are collections of users. Site admins use the Group API to manage Groups.

See Instabase API authorization and response conventions for authorization, success response, and error response convention details.

For the Group API, api_root defines where to route API requests for your Instabase instance:

import json, requests

api_root = "https://www.instabase.com/api/v1/groups"

Create a Group

Use this API to create a group.

This API can be invoked only by:

Request

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'full_name': 'Engineering',
  'description': 'All Instabase Engineers',
  'profile_photo_url': 'https://photo.jpg'
}
data = json.dumps(args)
resp = requests.post(api_root + '/group/<group_name>', headers=headers, data=data).json()

The body of the request must be a JSON object with the following fields:

  • full_name: a user-friendly display name

  • description: a description for the Group.

The group_name must be a unique group identifier. Duplicate group names are not supported.

The group_name is a part of the API route, and it must meet these string requirements:

  • composed only of alphanumeric characters and underscores

  • be 3 to 100 characters in length

Get Group information

Use this API to retrieve Group information, including the admins and members of the Group. This API can be invoked by all.

Request

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
resp = requests.get(api_root + '/group/<group_name>', headers=headers).json()

Response

If successful:

{
  "status": "OK",
  "group": {
    "name": "eng_group",
    "full_name": "Engineering",
    "description": "All Instabase Engineers",
    "profile_photo_url": "https://photo.jpg",
    "admins": [
        {
            "type": "user",
            "name": "admin"
        }
    ],
    "members": [
        {
            "type": "user",
            "name": "alice"
        },
        {
            "type": "user",
            "name": "bob"
        }
    ]
  }
}

The body of the response is a JSON dictionary with the following fields:

  • full_name: a user-friendly display name

  • description: a description for the Group.

  • admins: the users who are admins of the Group

  • members: the users who are members of the Group

Update Group

Use this API to update Group information such as the display name and description.

This API can be invoked only by:

  • A site admin

  • A user with the manage_groups site ACL

  • An admin of the group

Request

A request must provide a new group name, a new display name, a new description or a new profile photo URL to be successfully processed.

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'new_name': 'new_group_name',
  'full_name': 'A New Group',
  'description': 'A new description for Instabase Eng'
}
data = json.dumps(args)
resp = requests.patch(api_root + '/group/<group_name>', headers=headers, data=data).json()

Delete Group

Use this API to delete a Group. This API can be invoked only by:

  • A site admin

  • Any user with the manage_groups site ACL

  • Any admin of the group

Request

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
resp = requests.delete(api_root + '/group/<group_name>', headers=headers).json()

Add/Remove users to/from a Group

Use this API to add users to a Group. This API can be invoked only by:

  • A site admin

  • Any user with the manage_groups site ACL

  • Any admin of the group

Request

Users of a Group can have admin or member roles.

  • Admins have read and write access to edit the group metadata.

  • Members have only read access.

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
    'admin': {
        'gru': True,
        'stuart': False
    },
    'member': {
        'fred': False,
        'bob': True
    }
}
data = json.dumps(args)
resp = requests.post(api_root + '/group/<group_name>/members', headers=headers, data=data).json()

Response

If one or more users was not successfully added, more details are provided in error_details with a JSON dictionary that denotes which users failed to be added and why.

{
  "status": "ERROR",
  "msg": "Failed to add all members.",
  "error_details": {
    "stuart": "User (gru) not found",
    "fred": "User (fred) not found"
  }
}

List all groups

Use this API to retrieve a list of all Groups. Members can optionally be returned. This API can be invoked by all.

Request

Supported query parameters are:

  • username: (Optional) If specified, returns only the list of groups the user is in

  • get_members: (Optional) If true, returns the list of all members for each group.

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
resp = requests.get(api_root + '/list?get_members=true&username=gru>', headers=headers).json()

Response

If successful:

{
    "status": "OK",
    "groups": [
        {
            "name": "eng_group",
            "full_name": "Engineering",
            "description": "Instabase Engineers",
            "profile_photo_url": "https://photo.jpg",
            "admins": [
                {
                    "type": "user",
                    "name": "dru"
                }
            ],
            "members": [
                {
                    "type": "user",
                    "name": "fred"
                },
                {
                    "type": "user",
                    "name": "bob"
                }
            ]
        },
        {
            "name": "sales_group",
            "full_name": "Sales",
            "description": "Instabase Sales",
            "profile_photo_url": "https://photo.jpg",
            "admins": [
                {
                    "type": "user",
                    "name": "gru"
                }
            ],
            "members": [
                {
                    "type": "user",
                    "name": "stuart"
                },
                {
                    "type": "user",
                    "name": "bob"
                }
            ]
        }
    ]
}

The body of the response is a JSON dictionary with the following fields:

  • groups: The list of Groups and their metadata

Each Group in the groups list contains:

  • full_name: The user-friendly display name.

  • description: The description for the Group.

  • profile_photo_url: The URL to the profile photo if set.

  • admins: The users who are admins of the Group. This list is returned only if the request specified get_members=true.

  • members: The users who are members of the Group. This list is returned only if the request specified get_members=true.