Concepts

The Labii API is a REST API that provides programmatic access to the Labii platform. It supports all different calling methods, including GET, POST, PUT, and DELETE.

The Labii API is designed to be accessible and flexible, allowing developers to use the programming language and tools of their choice to interact with the Labii platform. The API is fully documented and provides detailed information about each of its endpoints, including the HTTP method, endpoint URL, required parameters, and expected response.

Some of the key features of the Labii API include:

Resource-based architecture: The Labii API uses a resource-based architecture, which means that each endpoint represents a specific resource in the Labii platform, such as a project, experiment, or row.
Authentication and authorization: The Labii API uses OAuth 2.0 for authentication and authorization, ensuring that only authorized users can access sensitive data.
Pagination and filtering: The API provides support for pagination and filtering, allowing developers to retrieve specific subsets of data based on various criteria.

URL

The Labii API uses two types of URLs to represent two different views of an object:

List of objects: {{base_url}}/{app}/{model}/list/{level}/{sid}/{serializer}/
Detail of an object: {{base_url}}/{app}/{model}/detail/{sid}/

The base_url is set to https://www.labii.dev/ by default. If your organization has a dedicated server, you can use https://[your subdomain].labii.dev/ as the base_url.

The app parameter represents the name of the application, while the model parameter represents the name of the model. You can refer to the Labii documentation for more details on these parameters.

The level parameter represents the scope of records to retrieve. You can refer to the Levels section of the Labii documentation for more details on this parameter.

The sid parameter is a static and encrypted Labii object ID. It must match with the level parameter. For example, if level=organization, the sid parameter must be the SID of the organization.

Finally, the serializer parameter represents the scope of fields of the return data. There are three options available:

name: Returns only the SID and name of the object, which is very fast.
list: Returns selected fields of the objects, which is fast.
detail: Returns all fields of the objects, which is slow.

Objects

The Labii API provides various objects that represent different types of entities in the Labii platform, each with a set of methods for interacting with that entity. Below is a list of objects available in the Labii API along with their descriptions, the app they belong to, and their corresponding model:

Name	Description	App	Model
Organization	Represents the organization object	organizations	organization
Personnel	Represents a member of the organization	organizations	personnel
Team	Represents a team of the organization	organizations	team
Organization Widget	Represents the installed widgets in the organization	organizations	organizationwidget
Statement	Represents the monthly statement	organizations	statement
Backup	Represents the backup data	organizations	backup
Project	Represents the project object	projects	project
Project Member	Represents a project member or team	projects	member
Table	Represents the table object	tables	table
Column	Represents the columns of a table	tables	column
Row	Represents the rows of a table	tables	row
Cell	Represents the cells of a row	tables	cell
Section	Represents the sections of a row	tables	section
Version	Represents the versions of a row	tables	version
Filter	Represents the filters of a table	tables	filter
Workflow	Represents the workflow of a table	tables	workflow
Step	Represents the steps of a workflow	tables	step
Activity	Represents user activities	activities	activity
Widget	Represents the widget object	widgets	widget

Levels

Levels define the scope of records to retrieve. The level parameter is a required parameter for the list API. Labii uses the following levels:

organization: returns the results within the organization level.
user: returns the results for a particular user (deprecated).
project: returns the results for a project (deprecated).

Not all levels are available for all list APIs. If a wrong level is used, an HTTP_406_NOT_ACCEPTABLE error will be returned. The table below lists all the allowed levels for each API.

List API	level=organization	level=user	level=project
Organization List	Yes	Yes	-
Organization Member List	Yes	-	-
Team List	Yes	Yes	-
Organization Widget	Yes	-	-
Statement List	Yes	-	-
Backup List	Yes	-	-
Project List	Yes	Yes	-
Project Member List	Yes	-	Yes
Table List	Yes	-	-
Column List	Yes	-	-
Filter List	Yes	Yes	-
Row List	Yes	Yes	Yes
Cell List	Yes	-	-
Section List	Yes	-	-
Version List	Yes	-	-
Activity	Yes	Yes	-
Widget	*	-	-

Methods

The following documentation describes the methods used in the Labii API:

GET: This method is used to fetch one or more objects.
POST: This method is used to create an object.
PUT: This method is used to update an object.
PATCH: This method is used to partially update an object.
DELETE: This method is used to remove an object.

Different roles have different permissions in using the methods. There are five roles at the organization level:

Admin: The administrators
Member: The members of the organization
Alumni: The members who have left the organization
User: Other Labii users who do not belong to the organization
Anonymous: Unauthorized user

And 3 roles at the project level:

Project Admin: The administrator of a project
Project Edit: The members have edit permission at the project
Project View: The members have view permission at the project

API	GET	POST	PUT	PATCH	DELETE
Organization List	Admin, Member	Admin	-	-	-
Organization Detail	Admin, Member	-	-	Admin	-
Organization Member List	Admin, Member	Admin	-	-	-
Organization Member Detail	Admin, Member	-	-	Admin	-
Team List	Admin, Member	Admin	-	-	-
Team Detail	Admin, Member	-	-	Admin	Admin
Organization Widget List	Admin, Member	Admin	-	-	Admin
Organization Widget Detail	Admin, Member	-	-	-	Admin
Statement List	Admin	-	-	-	-
Statement Detail	Admin	-	-	-	-
Backup List	Admin	Admin	-	-	-
Backup Detail	Admin	-	-	-	-
Project List	Admin, Project Admin, Project Edit, Project View	Admin	-	-	-
Project Detail	Admin, Project Admin, Project Edit, Project View	-	-	Admin, Project Admin	-
Project Member List	Admin, Project Admin, Project Edit, Project View	Admin, Project Admin	-	-	-
Project Member Detail	Admin, Project Admin, Project Edit, Project View	-	-	Admin, Project Admin	Admin, Project Admin
Table List	Admin, Member	Admin	-	-	-
Table Detail	Admin, Member	-	-	Admin	-
Column List	Admin, Member	Admin	-	-	-
Column Detail	Admin, Member	-	-	Admin	-
Filter List	Admin, Member	Admin, Member	-	-	-
Filter Detail	Admin, Member	-	-	Admin, Member	Admin, Member
Row List	Admin, Project Admin, Project Edit, Project View	Project Admin, Project Edit	-	Project Admin, Project Edit	-
Row Detail	Admin, Project Admin, Project Edit, Project View	-	-	Project Admin, Project Edit	-
Cell List	Admin, Project Admin, Project Edit, Project View	Project Admin, Project Edit	-	-	-
Cell Detail	-	-	-	Project Admin, Project Edit	-
Section List	Admin, Project Admin, Project Edit, Project View	Project Admin, Project Edit	-	-	-
Section Detail	Admin, Project Admin, Project Edit, Project View	-	-	Project Admin, Project Edit	-
Version List	Admin, Project Admin, Project Edit, Project View	-	-	-	-
Version Detail	Admin, Project Admin, Project Edit, Project View	-	-	-	-
Activity List	Admin, Member	-	-	-	-
Activity Detail	-	-	-	-	-
Widget List	Admin, Member	-	-	-	-
Widget Detail	Admin, Member	-	-	-	-

Serializer

The Serializer in Labii API is used to convert the data from the database into a different format. Each Serializer in Labii represents a different field set to be returned. Labii API supports the following serializers:

name: This serializer returns the field of sid and name of a record.
list: This serializer returns some basic fields. The set of fields varies for different tables.
detail: This serializer returns a full set of fields.

Status Codes

Here is a list of status code used by Labii API:

HTTP_200_OK: return when API call successful
HTTP_201_CREATED: return when an object is created
HTTP_204_NO_CONTENT: return when an object is successfully deleted
HTTP_401_UNAUTHORIZED: return when the user is not authenticated
HTTP_403_FORBIDDEN: return when a user does not have permission
HTTP_406_NOT_ACCEPTABLE: return when parameter is not correct
HTTP_500_INTERNAL_SERVER_ERROR: return on internal errors

Errors

These are common errors for the list view and detail view.

List view

HTTP_401_UNAUTHORIZED - token is not valid
HTTP_403_FORBIDDEN - the user does not have permission to perform the action
HTTP_406_NOT_ACCEPTABLE - some parameter provided is not acceptable
- Wrong level - the level provided is not valid or is not allowed
- Wrong sid - the sid provided can be not decrypted, or does not match any records
- Wrong field - Error: the field (xxx) is not allowed!
- Wrong datatype - list, acceptable data is DICT. Please POST multiple times if you have more than one dataset.

Detail view

HTTP_401_UNAUTHORIZED - token is not valid
HTTP_403_FORBIDDEN - the user does not have permission to perform the action
HTTP_406_NOT_ACCEPTABLE - some parameter provided is not acceptable
- Wrong sid - the sid provided can be not decrypted, or does not match any records
- Wrong field - Error: the field (xxx) can not be updated!

Example

Get a list of records with curl:

curl -X get https://www.labii.dev/tables/rows/list/organization/xxx/list/ -H "Authorization: Token xxxx"

In Python:

import requests
headers = {
    "X-Forwarded-For": "batch",
    "Content-Type": "application/json",
    "Authorization": "Token %s" % token
}
requests.get(url="https://www.labii.dev/tables/rows/list/organization/xxx/list", headers=headers)

URL​

Objects​

Levels​

Methods​

Serializer​

Status Codes​

Errors​

List view​

Detail view​

Example​

URL