Space API

Use the Space API to get details about the spaces in your instance.

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

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

import json, requests

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

List Spaces

Use this API to query the list of Spaces a user has access to with various search filters. The list will include both User Spaces as well as Organization Spaces. This API can be invoked by all.

Request

headers = {"Authorization": "Bearer {0}".format(token)}
resp = requests.get(api_root + "/list?get_profiles=True&get_repos=True",
                    headers=headers).json()

Supported query parameters are:

  • get_profiles: If true, will return profile information about the Space, such as the full name, the description and profile photo URL.

  • get_repos: If true, will return the list of repos within each space the user has access to.

  • get_admins: If true, will return the list of Space admins for each Space.

  • get_admin_spaces_only: If true, returns the list of Spaces that the requesting User is an admin of, or that contains at least one Subspace that requesting user is an admin of.

Response

{
    "status": "OK",
    "spaces": [
        {
            "account_type": "USER",
            "repo_owner": "alice",
            "is_admin": true,
            "full_name": "Alice's Space",
            "description": "Alice's private user space",
            "profile_photo_url": "https://alice.jpg",
            "admins": [
                {
                    "type": "user",
                    "name": "alice"
                }
            ],
            "repos": [
                {
                    "repo_owner": "alice",
                    "repo_name": "repo1",
                    "is_admin": true,
                },
                {
                    "repo_owner": "alice",
                    "repo_name": "repo2",
                    "is_admin": true,
                },
            ]
        },
        {
            "account_type": "ORGANIZATION",
            "repo_owner": "ib_eng",
            "is_admin": true,
            "full_name": "Engineering Organization",
            "description": "The engineering organization",
            "profile_photo_url": "https://eng.jpg",
            "admins": [
                {
                    "type": "user",
                    "name": "eng-lead"
                }
            ],
             "repos": [
                {
                    "repo_owner": "ib_eng",
                    "repo_name": "repo1",
                    "is_admin": false,
                },
                {
                    "repo_owner": "ib_eng",
                    "repo_name": "repo2",
                    "is_admin": false,
                },
            ]
        }
    ]
}

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

  • spaces: The list of Spaces and their metadata

Each Space in the spaces list contains:

  • account_type: The Space type, valid values are: USER, ORGANIZATION.

  • repo_owner: The unique name of the Space.

  • is_admin: Indicates whether the requesting user is an admin of the Space, returned only if the request specified is_admin=true.

  • full_name: The user-friendly display name, returned only if the request specified get_profiles=true.

  • description: The description for the Space, returned only if the request specified get_profiles=true.

  • profile_photo_url: The URL to the profile photo if set, returned only if the request specified get_profiles=true.

  • admins: The list of admins on the Space. Each element includes a type field with value user or group to incidate whether the name field is referring to a username or a group name.

  • repos: The list of Subspaces (Repos) in the Space, returned only if the request specified get_repos=true. Each element includes the repo_name. If the request also specified get_admins=true, then also returns whether or not the user is an admin of the Subspace.