Bulbthings logo
API docs by Redocly

API Reference (beta 🧪)

E-mail: hello@bulbthings.com Terms of Service

The Bulbthings API follows the JSON:API specification. The API is organized around clear resource-oriented endpoints, and uses HTTP response codes to indicate API errors. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application. JSON is returned by all API responses, including errors.

Learn more about Bulbthings

🔒 Authentication

API key (required)

Bulbthings uses API keys to authenticate requests. You can create and manage API keys from your dashboard. Keep your keys secure and do not share them in publicly accessible areas such as GitHub, client-side code, and so forth. Keys must be provided via HTTP request headers: Authorization: Bearer your-api-key.

Workspace scope (recommended)

If you are only making requests for a single Bulbthings workspace, it is recommended you provide a companyId query parameter to all of your requests, for example GET https://api.bulbthings.com/entities?companyId=your-workspace-id. This will automatically restrict the data you read/write to the specified workspace and avoid having to manually filter results. The companyId workspace identifier can be found in the developer settings page of your dashboard.

Accounts

Account objects represent the users of the platform. They can either be a human or an application bot.

List all accounts

Returns a list of accounts.

query Parameters
include
string
Enum: "companies" "memberships" "keys" "settings" "unitSettings"

Comma-separated list of related resources to include in the response, for example: companies,memberships,keys,settings,unitSettings

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const accounts = await bulbthings.accounts.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Invite a user

Invite a user to join Bulbthings. This operation will return the existing invite if the email was already used. ⚠️ You also need to create a Membership for the user to have access to a workspace.

Request Body schema: application/vnd.api+json
required
required
object
required
object (Account)

Account objects represent the users of the platform. They can either be a human or an application bot.

label
required
string

The full name to be displayed for this account.

email
required
string

Email address associated with this account.

locale
string or null

Language code of the account as defined in BCP 47

avatarFileId
string or null <uuid>

Identifier of the image file object used as the profile picture of the account.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an account

Retrieve the details of an existing account using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the account to be retrieved.

query Parameters
include
string
Enum: "companies" "memberships" "keys" "settings" "unitSettings"

Comma-separated list of related resources to include in the response, for example: companies,memberships,keys,settings,unitSettings

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update an account

Accounts can only update themselves.

Request Body schema: application/vnd.api+json
required
required
object
required
object (Account)

Account objects represent the users of the platform. They can either be a human or an application bot.

label
string

The full name to be displayed for this account.

email
string

Email address associated with this account.

locale
string or null

Language code of the account as defined in BCP 47

avatarFileId
string or null <uuid>

Identifier of the image file object used as the profile picture of the account.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an account

Delete an account using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the account to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Acknowledgements

Acknowledgements are objects used to record that a user has seen a notification event.

Create an acknowledgement

Create an acknowledgement

Request Body schema: application/vnd.api+json
required
required
object
required
object (Acknowledgement)

Acknowledgements are objects used to record that a user has seen a notification event.

companyId
string <uuid>

Identifier of the workspace the acknowledgement belongs to.

accountId
string <uuid>

Identifier of the account acknowledging the event.

eventId
required
string <uuid>

Identifier of the event being acknowledged.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an acknowledgement

Retrieve the details of an existing acknowledgement using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the acknowledgement to be retrieved.

query Parameters
include
string
Enum: "company" "account" "event"

Comma-separated list of related resources to include in the response, for example: company,account,event

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an acknowledgement

Delete an acknowledgement using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the acknowledgement to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Action Types

Action types describe the possible actions that can be triggered in the system. Actions are physical or abstract operations, for example turning on/off a machine, sending an email or validating a quotation. To control the display of actions, use entity type mappings.

List all action types

Returns a list of action types.

query Parameters
include
string
Value: "entityTypes"

Comma-separated list of related resources to include in the response, for example: entityTypes

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const actionTypes = await bulbthings.actionTypes.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create an action type

Create an action type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Action Type)

Action types describe the possible actions that can be triggered in the system. Actions are physical or abstract operations, for example turning on/off a machine, sending an email or validating a quotation. To control the display of actions, use entity type mappings.

companyId
string or null

Identifier of the workspace the type belongs to or null if the type is public.

schema
required
object

JSON Schema object used to describe the action and its expected input parameters.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an action type

Retrieve the details of an existing action type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the action type to be retrieved.

query Parameters
include
string
Value: "entityTypes"

Comma-separated list of related resources to include in the response, for example: entityTypes

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update an action type

Update an action type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Action Type)

Action types describe the possible actions that can be triggered in the system. Actions are physical or abstract operations, for example turning on/off a machine, sending an email or validating a quotation. To control the display of actions, use entity type mappings.

companyId
string or null

Identifier of the workspace the type belongs to or null if the type is public.

schema
object

JSON Schema object used to describe the action and its expected input parameters.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an action type

Delete an action type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the action type to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Actions

Actions represent operations being asked by a user. Think of it as issue tickets: creating an Action is like someone opening a ticket to ask for an operation to be executed. The action creation emits events that can be listened to by Bulbthings, thirdparties, or your servers in order to triggered all the necessary code and operations. During the lifeycle of the action, whatever client handling the operation will update its status until it reaches the completed or failed states.

List all actions

Returns a list of actions.

query Parameters
include
string
Enum: "actionType" "account" "entity" "events"

Comma-separated list of related resources to include in the response, for example: actionType,account,entity,events

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const actions = await bulbthings.actions.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create an action

Create an action

Request Body schema: application/vnd.api+json
required
required
object
required
object (Action)

Actions represent operations being asked by a user. Think of it as issue tickets: creating an Action is like someone opening a ticket to ask for an operation to be executed. The action creation emits events that can be listened to by Bulbthings, thirdparties, or your servers in order to triggered all the necessary code and operations. During the lifeycle of the action, whatever client handling the operation will update its status until it reaches the completed or failed states.

companyId
string <uuid>

Identifier of the workspace the action belongs to.

entityId
string or null <uuid>

Identifier of the entity that is the subject of the action.

actionTypeId
required
string

Type of action.

accountId
string <uuid>

Identifier of the source account. The source of an action is the account that triggered the action.

label
string or null

Label to be used when displaying the action. By default, the action will be displayed using the action type's schema.title property.

input
required
any

Parameters of the action. The input must match the schema property of the corresponding action type.

status
string
Default: "requested"
Enum: "available" "requested" "completed" "failed"

State of the action.

null or object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an action

Retrieve the details of an existing action using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the action to be retrieved.

query Parameters
include
string
Enum: "actionType" "account" "entity" "events"

Comma-separated list of related resources to include in the response, for example: actionType,account,entity,events

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update an action

Update an action

Request Body schema: application/vnd.api+json
required
required
object
required
object (Action)

Actions represent operations being asked by a user. Think of it as issue tickets: creating an Action is like someone opening a ticket to ask for an operation to be executed. The action creation emits events that can be listened to by Bulbthings, thirdparties, or your servers in order to triggered all the necessary code and operations. During the lifeycle of the action, whatever client handling the operation will update its status until it reaches the completed or failed states.

companyId
string <uuid>

Identifier of the workspace the action belongs to.

entityId
string or null <uuid>

Identifier of the entity that is the subject of the action.

actionTypeId
string

Type of action.

accountId
string <uuid>

Identifier of the source account. The source of an action is the account that triggered the action.

label
string or null

Label to be used when displaying the action. By default, the action will be displayed using the action type's schema.title property.

input
any

Parameters of the action. The input must match the schema property of the corresponding action type.

status
string
Default: "requested"
Enum: "available" "requested" "completed" "failed"

State of the action.

null or object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an action

Delete an action using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the action to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Association Types

Association types describe the different kinds of relationships that exist between entities. An association type is defined between a source and a target entity type and can be shared between multiple targets in the case of overlapping associations.

List all association types

Returns a list of association types.

query Parameters
include
string
Enum: "sourceEntityType" "targetEntityType"

Comma-separated list of related resources to include in the response, for example: sourceEntityType,targetEntityType

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const associationTypes = await bulbthings.associationTypes.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create an association type

Create an association type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Association Type)

Association types describe the different kinds of relationships that exist between entities. An association type is defined between a source and a target entity type and can be shared between multiple targets in the case of overlapping associations.

companyId
string or null

Identifier of the workspace the type belongs to or null if the type is public.

sourceEntityTypeId
required
string

Identifier of the entity type that is the subject of the relationship.

targetEntityTypeId
required
string

Identifier of the entity type that is the target of the relationship.

sourceIsShared
boolean

Specifies if the source entity can be shared, i.e., if multiple associations of this type can exist at the same time for the same source entity.

targetIsShared
boolean

Specifies if the target entity can be shared, i.e., if multiple associations of this type can exist at the same time for the same target entity.

required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an association type

Retrieve the details of an existing association type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the association type to be retrieved.

query Parameters
include
string
Enum: "sourceEntityType" "targetEntityType"

Comma-separated list of related resources to include in the response, for example: sourceEntityType,targetEntityType

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update an association type

Update an association type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Association Type)

Association types describe the different kinds of relationships that exist between entities. An association type is defined between a source and a target entity type and can be shared between multiple targets in the case of overlapping associations.

companyId
string or null

Identifier of the workspace the type belongs to or null if the type is public.

sourceEntityTypeId
string

Identifier of the entity type that is the subject of the relationship.

targetEntityTypeId
string

Identifier of the entity type that is the target of the relationship.

sourceIsShared
boolean

Specifies if the source entity can be shared, i.e., if multiple associations of this type can exist at the same time for the same source entity.

targetIsShared
boolean

Specifies if the target entity can be shared, i.e., if multiple associations of this type can exist at the same time for the same target entity.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an association type

Delete an association type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the association type to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Associations

Entities have relationships by way of associations. An association is a relationship defined between a source and a target entity, possibly restricted to a period of time. When an association type is shareable, a ratio specifies how the relationship is split between the target entities.

List all associations

Returns a list of associations.

query Parameters
include
string
Enum: "associationType" "sourceEntity" "targetEntity"

Comma-separated list of related resources to include in the response, for example: associationType,sourceEntity,targetEntity

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const associations = await bulbthings.associations.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create an association

Create an association

Request Body schema: application/vnd.api+json
required
required
object
required
object (Association)

Entities have relationships by way of associations. An association is a relationship defined between a source and a target entity, possibly restricted to a period of time. When an association type is shareable, a ratio specifies how the relationship is split between the target entities.

accountId
string <uuid>

Identifier of the account which created the association.

companyId
string <uuid>

Identifier of the workspace the association belongs to.

associationTypeId
required
string

Identifier of the type of association.

sourceEntityId
required
string <uuid>

Identifier of the entity that is the target of the relationship.

targetEntityId
required
string <uuid>

Identifier of the entity that is the target of the relationship.

object or null
ratio
string

If the association type is shareable, specifies how to split the overlapping associations by target entity.

quantity
number >= 0
Default: 1

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an association

Retrieve the details of an existing association using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the association to be retrieved.

query Parameters
include
string
Enum: "associationType" "sourceEntity" "targetEntity"

Comma-separated list of related resources to include in the response, for example: associationType,sourceEntity,targetEntity

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update an association

Update an association

Request Body schema: application/vnd.api+json
required
required
object
required
object (Association)

Entities have relationships by way of associations. An association is a relationship defined between a source and a target entity, possibly restricted to a period of time. When an association type is shareable, a ratio specifies how the relationship is split between the target entities.

accountId
string <uuid>

Identifier of the account which created the association.

companyId
string <uuid>

Identifier of the workspace the association belongs to.

associationTypeId
string

Identifier of the type of association.

sourceEntityId
string <uuid>

Identifier of the entity that is the target of the relationship.

targetEntityId
string <uuid>

Identifier of the entity that is the target of the relationship.

object or null
ratio
string

If the association type is shareable, specifies how to split the overlapping associations by target entity.

quantity
number >= 0
Default: 1

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an association

Delete an association using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the association to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Attribute Types

Attribute types describe the different kinds of properties that can be added to entities.

List all attribute types

Returns a list of attribute types.

query Parameters
include
string
Value: "unit"

Comma-separated list of related resources to include in the response, for example: unit

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const attributeTypes = await bulbthings.attributeTypes.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create an attribute type

Create an attribute type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Attribute Type)

Attribute types describe the different kinds of properties that can be added to entities.

schema
required
any

JSON Schema object used to describe the attribute type and validate the values.

object
isReadOnly
boolean

Read-only attributes are reserved for bot account usage. Regular user accounts will not be able to create measurements for this attribute type.

unitId
string or null
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an attribute type

Retrieve the details of an existing attribute type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the attribute type to be retrieved.

query Parameters
include
string
Value: "unit"

Comma-separated list of related resources to include in the response, for example: unit

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update an attribute type

Update an attribute type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Attribute Type)

Attribute types describe the different kinds of properties that can be added to entities.

schema
any

JSON Schema object used to describe the attribute type and validate the values.

object
isReadOnly
boolean

Read-only attributes are reserved for bot account usage. Regular user accounts will not be able to create measurements for this attribute type.

unitId
string or null
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an attribute type

Delete an attribute type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the attribute type to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Catalog mappings

Catalog mappings define which entity types a catalog gives access to. Adding an entity type to a catalog automatically implies adding all of its ancestors and descendant types.

List all catalog mappings

Returns a list of catalog mappings.

query Parameters
include
string
Enum: "catalog" "entityType"

Comma-separated list of related resources to include in the response, for example: catalog,entityType

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const catalogMappings = await bulbthings.catalogMappings.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a catalog mapping

Create a catalog mapping

Request Body schema: application/vnd.api+json
required
required
object
required
object (Catalog mapping)

Catalog mappings define which entity types a catalog gives access to. Adding an entity type to a catalog automatically implies adding all of its ancestors and descendant types.

companyId
string or null <uuid>

Identifier of the workspace the mapping belongs to.

catalogId
required
string <uuid>

Catalog targeted by the mapping.

entityTypeId
required
string

Entity type targeted by the mapping.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a catalog mapping

Retrieve the details of an existing catalog mapping using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the catalog mapping to be retrieved.

query Parameters
include
string
Enum: "catalog" "entityType"

Comma-separated list of related resources to include in the response, for example: catalog,entityType

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a catalog mapping

Update a catalog mapping

Request Body schema: application/vnd.api+json
required
required
object
required
object (Catalog mapping)

Catalog mappings define which entity types a catalog gives access to. Adding an entity type to a catalog automatically implies adding all of its ancestors and descendant types.

companyId
string or null <uuid>

Identifier of the workspace the mapping belongs to.

catalogId
string <uuid>

Catalog targeted by the mapping.

entityTypeId
string

Entity type targeted by the mapping.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a catalog mapping

Delete a catalog mapping using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the catalog mapping to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Catalogs

Catalogs are bundles of entity types that can be used to customise the application for a workspace by only showing a set of entity type categories.

List all catalogs

Returns a list of catalogs.

query Parameters
include
string
Value: "entityTypes"

Comma-separated list of related resources to include in the response, for example: entityTypes

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const catalogs = await bulbthings.catalogs.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a catalog

Create a catalog

Request Body schema: application/vnd.api+json
required
required
object
required
object (Catalog)

Catalogs are bundles of entity types that can be used to customise the application for a workspace by only showing a set of entity type categories.

companyId
string or null <uuid>

Identifier of the workspace the catalog belongs to.

label
required
string

Name of the catalog

description
string or null

Description of the catalog

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a catalog

Retrieve the details of an existing catalog using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the catalog to be retrieved.

query Parameters
include
string
Value: "entityTypes"

Comma-separated list of related resources to include in the response, for example: entityTypes

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a catalog

Update a catalog

Request Body schema: application/vnd.api+json
required
required
object
required
object (Catalog)

Catalogs are bundles of entity types that can be used to customise the application for a workspace by only showing a set of entity type categories.

companyId
string or null <uuid>

Identifier of the workspace the catalog belongs to.

label
string

Name of the catalog

description
string or null

Description of the catalog

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a catalog

Delete a catalog using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the catalog to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Codes

List all codes

Returns a list of codes.

query Parameters
include
string
Value: "entity"

Comma-separated list of related resources to include in the response, for example: entity

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const codes = await bulbthings.codes.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a code

Create a code

Request Body schema: application/vnd.api+json
required
required
object
required
object (Code)
companyId
string <uuid>

Identifier of the workspace the code belongs to.

entityId
required
string <uuid>

Identifier of the entity the code belongs to.

type
required
string
Enum: "auspost" "azteccode" "azteccodecompact" "aztecrune" "bc412" "channelcode" "codablockf" "code11" "code128" "code16k" "code2of5" "code32" "code39" "code39ext" "code49" "code93" "code93ext" "codeone" "coop2of5" "daft" "databarexpanded" "databarexpandedcomposite" "databarexpandedstacked" "databarexpandedstackedcomposite" "databarlimited" "databarlimitedcomposite" "databaromni" "databaromnicomposite" "databarstacked" "databarstackedcomposite" "databarstackedomni" "databarstackedomnicomposite" "databartruncated" "databartruncatedcomposite" "datalogic2of5" "datamatrix" "datamatrixrectangular" "datamatrixrectangularextension" "dotcode" "ean13" "ean13composite" "ean14" "ean2" "ean5" "ean8" "ean8composite" "flattermarken" "gs1-128" "gs1-128composite" "gs1-cc" "gs1datamatrix" "gs1datamatrixrectangular" "gs1northamericancoupon" "gs1qrcode" "hanxin" "hibcazteccode" "hibccodablockf" "hibccode128" "hibccode39" "hibcdatamatrix" "hibcdatamatrixrectangular" "hibcmicropdf417" "hibcpdf417" "hibcqrcode" "iata2of5" "identcode" "industrial2of5" "interleaved2of5" "isbn" "ismn" "issn" "itf14" "japanpost" "kix" "leitcode" "mailmark" "matrix2of5" "maxicode" "micropdf417" "microqrcode" "msi" "onecode" "pdf417" "pdf417compact" "pharmacode" "pharmacode2" "planet" "plessey" "posicode" "postnet" "pzn" "qrcode" "rationalizedCodabar" "raw" "royalmail" "sscc18" "symbol" "telepen" "telepennumeric" "ultracode" "upca" "upcacomposite" "upce" "upcecomposite"

Type of code.

value
required
string

Value of the code.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a code

Retrieve the details of an existing code using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the code to be retrieved.

query Parameters
include
string
Value: "entity"

Comma-separated list of related resources to include in the response, for example: entity

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a code

Update a code

Request Body schema: application/vnd.api+json
required
required
object
required
object (Code)
companyId
string <uuid>

Identifier of the workspace the code belongs to.

entityId
string <uuid>

Identifier of the entity the code belongs to.

type
string
Enum: "auspost" "azteccode" "azteccodecompact" "aztecrune" "bc412" "channelcode" "codablockf" "code11" "code128" "code16k" "code2of5" "code32" "code39" "code39ext" "code49" "code93" "code93ext" "codeone" "coop2of5" "daft" "databarexpanded" "databarexpandedcomposite" "databarexpandedstacked" "databarexpandedstackedcomposite" "databarlimited" "databarlimitedcomposite" "databaromni" "databaromnicomposite" "databarstacked" "databarstackedcomposite" "databarstackedomni" "databarstackedomnicomposite" "databartruncated" "databartruncatedcomposite" "datalogic2of5" "datamatrix" "datamatrixrectangular" "datamatrixrectangularextension" "dotcode" "ean13" "ean13composite" "ean14" "ean2" "ean5" "ean8" "ean8composite" "flattermarken" "gs1-128" "gs1-128composite" "gs1-cc" "gs1datamatrix" "gs1datamatrixrectangular" "gs1northamericancoupon" "gs1qrcode" "hanxin" "hibcazteccode" "hibccodablockf" "hibccode128" "hibccode39" "hibcdatamatrix" "hibcdatamatrixrectangular" "hibcmicropdf417" "hibcpdf417" "hibcqrcode" "iata2of5" "identcode" "industrial2of5" "interleaved2of5" "isbn" "ismn" "issn" "itf14" "japanpost" "kix" "leitcode" "mailmark" "matrix2of5" "maxicode" "micropdf417" "microqrcode" "msi" "onecode" "pdf417" "pdf417compact" "pharmacode" "pharmacode2" "planet" "plessey" "posicode" "postnet" "pzn" "qrcode" "rationalizedCodabar" "raw" "royalmail" "sscc18" "symbol" "telepen" "telepennumeric" "ultracode" "upca" "upcacomposite" "upce" "upcecomposite"

Type of code.

value
string

Value of the code.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a code

Delete a code using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the code to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Companies

Companies represent customer workspaces.

List all companies

Returns a list of companies.

query Parameters
include
string
Enum: "account" "catalog"

Comma-separated list of related resources to include in the response, for example: account,catalog

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const companies = await bulbthings.companies.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a company

Create a company

Request Body schema: application/vnd.api+json
required
required
object
required
object (Company)

Companies represent customer workspaces.

label
required
string

Full name of the company.

accountId
string <uuid>

Identifier of the workspace's owner account.

catalogId
string or null <uuid>

Identifier of the workspace's active catalog.

avatarFileId
string or null <uuid>

Identifier of the image file object used as the profile picture of the company.

locale
string or null

Language code of the company as defined in BCP 47

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a company

Retrieve the details of an existing company using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the company to be retrieved.

query Parameters
include
string
Enum: "account" "catalog"

Comma-separated list of related resources to include in the response, for example: account,catalog

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a company

Update a company

Request Body schema: application/vnd.api+json
required
required
object
required
object (Company)

Companies represent customer workspaces.

label
string

Full name of the company.

accountId
string <uuid>

Identifier of the workspace's owner account.

catalogId
string or null <uuid>

Identifier of the workspace's active catalog.

avatarFileId
string or null <uuid>

Identifier of the image file object used as the profile picture of the company.

locale
string or null

Language code of the company as defined in BCP 47

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a company

Delete a company using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the company to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Entity Type Mappings

Mappings allow you to control how attributes, actions and relationships appear on entity profiles. Mappings apply to an entity type category, which means that all entities belonging to subcategories will also inherit them. You can also restrict mappings to a certain role for more granularity in what users see.

List all entity type mappings

Returns a list of entity type mappings.

query Parameters
include
string
Enum: "entityType" "associationType" "attributeType" "eventType" "actionType" "role"

Comma-separated list of related resources to include in the response, for example: entityType,associationType,attributeType,eventType,actionType,role

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const entityTypeMappings = await bulbthings.entityTypeMappings.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create an entity type mapping

Create an entity type mapping

Request Body schema: application/vnd.api+json
required
required
object
required
object (Entity Type Mapping)

Mappings allow you to control how attributes, actions and relationships appear on entity profiles. Mappings apply to an entity type category, which means that all entities belonging to subcategories will also inherit them. You can also restrict mappings to a certain role for more granularity in what users see.

companyId
string or null <uuid>

Identifier of the workspace the mapping belongs to.

entityTypeId
required
string

Entity type targeted by the mapping.

entityId
string or null <uuid>

Identifier of the entity the mapping is restricted to.

privateForAccountId
string or null <uuid>

Identifier of the account the mapping should only be visible for.

roleId
string or null <uuid>

Identifier of the role the mapping applies to.

type
required
string
Enum: "associationType" "attributeType" "eventType" "actionType"

Type of resource linked to the entity type.

associationTypeId
string or null

Association type linked to the entity type.

attributeTypeId
string or null

Attribute type linked to the entity type.

eventTypeId
string or null

Event type linked to the entity type.

actionTypeId
string or null

Action type linked to the entity type.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an entity type mapping

Retrieve the details of an existing entity type mapping using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the entity type mapping to be retrieved.

query Parameters
include
string
Enum: "entityType" "associationType" "attributeType" "eventType" "actionType" "role"

Comma-separated list of related resources to include in the response, for example: entityType,associationType,attributeType,eventType,actionType,role

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update an entity type mapping

Update an entity type mapping

Request Body schema: application/vnd.api+json
required
required
object
required
object (Entity Type Mapping)

Mappings allow you to control how attributes, actions and relationships appear on entity profiles. Mappings apply to an entity type category, which means that all entities belonging to subcategories will also inherit them. You can also restrict mappings to a certain role for more granularity in what users see.

companyId
string or null <uuid>

Identifier of the workspace the mapping belongs to.

entityTypeId
string

Entity type targeted by the mapping.

entityId
string or null <uuid>

Identifier of the entity the mapping is restricted to.

privateForAccountId
string or null <uuid>

Identifier of the account the mapping should only be visible for.

roleId
string or null <uuid>

Identifier of the role the mapping applies to.

type
string
Enum: "associationType" "attributeType" "eventType" "actionType"

Type of resource linked to the entity type.

associationTypeId
string or null

Association type linked to the entity type.

attributeTypeId
string or null

Attribute type linked to the entity type.

eventTypeId
string or null

Event type linked to the entity type.

actionTypeId
string or null

Action type linked to the entity type.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an entity type mapping

Delete an entity type mapping using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the entity type mapping to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Entity Types

Entity types are the different categories of entities. Each type can have a parent and will inherit attribute types, association types and action types from it.

List all entity types

Returns a list of entity types.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const entityTypes = await bulbthings.entityTypes.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create an entity type

Create an entity type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Entity Type)

Entity types are the different categories of entities. Each type can have a parent and will inherit attribute types, association types and action types from it.

companyId
string or null
label
required
string

Title of the entity type.

description
string or null
parentId
string or null
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an entity type

Retrieve the details of an existing entity type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the entity type to be retrieved.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update an entity type

Update an entity type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Entity Type)

Entity types are the different categories of entities. Each type can have a parent and will inherit attribute types, association types and action types from it.

companyId
string or null
label
string

Title of the entity type.

description
string or null
parentId
string or null
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an entity type

Delete an entity type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the entity type to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Entities

Entities are the main building blocks of asset management. They represent assets, users, organisations or even activities such as maintenances. The API allows you to create, delete, and update your entities. You can retrieve individual entities as well as a list of all your entities.

List all entities

Returns a list of entities.

query Parameters
include
string
Enum: "company" "entityType" "account" "associations" "avatarFile" "files" "codes"

Comma-separated list of related resources to include in the response, for example: company,entityType,account,associations,avatarFile,files,codes

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const entities = await bulbthings.entities.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create an entity

Create an entity

Request Body schema: application/vnd.api+json
required
required
object
required
object (Entity)

Entities are the main building blocks of asset management. They represent assets, users, organisations or even activities such as maintenances. The API allows you to create, delete, and update your entities. You can retrieve individual entities as well as a list of all your entities.

companyId
string <uuid>

Identifier of the workspace the entity belongs to.

entityTypeId
required
string
avatarFileId
string or null <uuid>

Identifier of the image file object used as the profile picture of the entity.

label
string or null

Short label of the entity.

quantity
integer >= 0
Default: 1
status
string
Default: "active"
Enum: "draft" "active" "locked" "archived" "deleted"

Entity profile status.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an entity

Retrieve the details of an existing entity using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the entity to be retrieved.

query Parameters
include
string
Enum: "company" "entityType" "account" "associations" "avatarFile" "files" "codes"

Comma-separated list of related resources to include in the response, for example: company,entityType,account,associations,avatarFile,files,codes

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update an entity

⚠️ The attributes property of an Entity object is read-only. To update attributes you need to create a Measurement object.

Request Body schema: application/vnd.api+json
required
required
object
required
object (Entity)

Entities are the main building blocks of asset management. They represent assets, users, organisations or even activities such as maintenances. The API allows you to create, delete, and update your entities. You can retrieve individual entities as well as a list of all your entities.

companyId
string <uuid>

Identifier of the workspace the entity belongs to.

entityTypeId
string
avatarFileId
string or null <uuid>

Identifier of the image file object used as the profile picture of the entity.

label
string or null

Short label of the entity.

quantity
integer >= 0
Default: 1
status
string
Default: "active"
Enum: "draft" "active" "locked" "archived" "deleted"

Entity profile status.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an entity

Delete an entity using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the entity to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Environments

Retrieve an environment

Retrieve the details of an existing environment using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the environment to be retrieved.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Event Types

Event types describe the different kinds of events that exist for entity types.

List all event types

Returns a list of event types.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const eventTypes = await bulbthings.eventTypes.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create an event type

Create an event type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Event Type)

Event types describe the different kinds of events that exist for entity types.

schema
required
object

JSON Schema used to describe and validate the event data.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an event type

Retrieve the details of an existing event type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the event type to be retrieved.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update an event type

Update an event type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Event Type)

Event types describe the different kinds of events that exist for entity types.

schema
object

JSON Schema used to describe and validate the event data.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an event type

Delete an event type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the event type to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Events

Events represent a change occuring on an entity at a single point in time. Events may describe any change in the entity's lifecycle, failure, confirmation or even user comments.

List all events

Returns a list of events.

query Parameters
include
string
Enum: "eventType" "account" "entity" "actions"

Comma-separated list of related resources to include in the response, for example: eventType,account,entity,actions

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const events = await bulbthings.events.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create an event

Create an event

Request Body schema: application/vnd.api+json
required
required
object
required
object (Event)

Events represent a change occuring on an entity at a single point in time. Events may describe any change in the entity's lifecycle, failure, confirmation or even user comments.

companyId
string <uuid>

Identifier of the workspace the event belongs to.

eventTypeId
required
string

Type of event.

priority
string
Default: "info"
Enum: "info" "warning" "danger" "success"

Level of criticality of the event.

accountId
string <uuid>

Identifier of the event source account. The source of an event is the account that caused or reported the event.

entityId
string or null <uuid>

Identifier of the entity that is the subject of the event.

privateForAccountId
string or null <uuid>

Identifier of the account the event should only be visible for.

time
string <date-time>

Time at which the event occured.

label
string or null

Optional, label to use when displaying the event. By default, the event will be displayed using the event type's schema.title property.

required
object

JSON object containing the event data as well as display information.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve an event

Retrieve the details of an existing event using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the event to be retrieved.

query Parameters
include
string
Enum: "eventType" "account" "entity" "actions"

Comma-separated list of related resources to include in the response, for example: eventType,account,entity,actions

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update an event

Update an event

Request Body schema: application/vnd.api+json
required
required
object
required
object (Event)

Events represent a change occuring on an entity at a single point in time. Events may describe any change in the entity's lifecycle, failure, confirmation or even user comments.

companyId
string <uuid>

Identifier of the workspace the event belongs to.

eventTypeId
string

Type of event.

priority
string
Default: "info"
Enum: "info" "warning" "danger" "success"

Level of criticality of the event.

accountId
string <uuid>

Identifier of the event source account. The source of an event is the account that caused or reported the event.

entityId
string or null <uuid>

Identifier of the entity that is the subject of the event.

privateForAccountId
string or null <uuid>

Identifier of the account the event should only be visible for.

time
string <date-time>

Time at which the event occured.

label
string or null

Optional, label to use when displaying the event. By default, the event will be displayed using the event type's schema.title property.

object

JSON object containing the event data as well as display information.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete an event

Delete an event using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the event to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Files

Files represent documents relevant to a given entity. Files can be of any format and can also be organised into a hierarchical folder structure.

List all files

Returns a list of files.

query Parameters
include
string
Enum: "parentFile" "account" "entity"

Comma-separated list of related resources to include in the response, for example: parentFile,account,entity

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const files = await bulbthings.files.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a file

Retrieve the details of an existing file using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the file to be retrieved.

query Parameters
include
string
Enum: "parentFile" "account" "entity"

Comma-separated list of related resources to include in the response, for example: parentFile,account,entity

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a file

Update a file

Request Body schema: application/vnd.api+json
required
required
object
required
object (File)

Files represent documents relevant to a given entity. Files can be of any format and can also be organised into a hierarchical folder structure.

companyId
string or null <uuid>

Identifier of the workspace the file belongs to.

parentFileId
string or null <uuid>

Identifier of the folder the object is in.

isFolder
boolean
Default: false

Specifies if the object a file or folder.

name
string

Name of the file.

size
number or null

Size of the file object in bytes.

type
string or null

Media type (MIME) of the file. See here.

encoding
string or null

Encoding type of the file.

accountId
string <uuid>

Identifier of the file source account. The source is the account which uploaded the file.

entityId
string or null <uuid>

Identifier of the target source entity. The target is the entity to which the file is attached.

storageId
string or null <uuid>

Identifier of the file on the cloud storage service.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a file

Delete a file using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the file to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Grants

Grants are used to assign roles to a given membership. The role can be scoped to a given Entity, which will restrict it to only entities linked to that scope entity.

List all grants

Returns a list of grants.

query Parameters
include
string
Enum: "company" "membership" "role" "entity"

Comma-separated list of related resources to include in the response, for example: company,membership,role,entity

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const grants = await bulbthings.grants.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a grant

Create a grant

Request Body schema: application/vnd.api+json
required
required
object
required
object (Grant)

Grants are used to assign roles to a given membership. The role can be scoped to a given Entity, which will restrict it to only entities linked to that scope entity.

companyId
string <uuid>

Identifier of the workspace the grant belongs to.

membershipId
required
string <uuid>

Identifier of the membership the grant applies to.

roleId
required
string <uuid>

Identifier of the role that is granted to the membership.

entityId
string or null <uuid>

Identifier of the entity to use as a scope for restricting the granted role.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a grant

Retrieve the details of an existing grant using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the grant to be retrieved.

query Parameters
include
string
Enum: "company" "membership" "role" "entity"

Comma-separated list of related resources to include in the response, for example: company,membership,role,entity

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a grant

Update a grant

Request Body schema: application/vnd.api+json
required
required
object
required
object (Grant)

Grants are used to assign roles to a given membership. The role can be scoped to a given Entity, which will restrict it to only entities linked to that scope entity.

companyId
string <uuid>

Identifier of the workspace the grant belongs to.

membershipId
string <uuid>

Identifier of the membership the grant applies to.

roleId
string <uuid>

Identifier of the role that is granted to the membership.

entityId
string or null <uuid>

Identifier of the entity to use as a scope for restricting the granted role.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a grant

Delete a grant using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the grant to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Hooks

Hooks allow you to be notified when an event occurs and to automatically trigger a script.

List all hooks

Returns a list of hooks.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const hooks = await bulbthings.hooks.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a hook

Create a hook

Request Body schema: application/vnd.api+json
required
required
object
required
object (Hook)

Hooks allow you to be notified when an event occurs and to automatically trigger a script.

isActive
boolean

True if the hook is enabled and will be triggered.

name
required
string

Name of the hook.

url
required
string

URL address the events will be posted to.

triggeredOn
required
Array of strings
Items Enum: "*" "accountCreated" "accountDeleted" "accountUpdated" "acknowledgementCreated" "acknowledgementDeleted" "acknowledgementUpdated" "actionTypeCreated" "actionTypeDeleted" "actionTypeUpdated" "actionCreated" "actionDeleted" "actionUpdated" "associationTypeCreated" "associationTypeDeleted" "associationTypeUpdated" "associationCreated" "associationDeleted" "associationUpdated" "attributeTypeCreated" "attributeTypeDeleted" "attributeTypeUpdated" "catalogMappingCreated" "catalogMappingDeleted" "catalogMappingUpdated" "catalogCreated" "catalogDeleted" "catalogUpdated" "codeCreated" "codeDeleted" "codeUpdated" "companyCreated" "companyDeleted" "companyUpdated" "entityTypeMappingCreated" "entityTypeMappingDeleted" "entityTypeMappingUpdated" "entityTypeCreated" "entityTypeDeleted" "entityTypeUpdated" "entityCreated" "entityDeleted" "entityUpdated" "eventTypeCreated" "eventTypeDeleted" "eventTypeUpdated" "eventCreated" "eventDeleted" "eventUpdated" "fileCreated" "fileDeleted" "fileUpdated" "grantCreated" "grantDeleted" "grantUpdated" "hookCreated" "hookDeleted" "hookUpdated" "keyCreated" "keyDeleted" "keyUpdated" "measurementCreated" "measurementDeleted" "measurementUpdated" "membershipCreated" "membershipDeleted" "membershipUpdated" "pathCreated" "pathDeleted" "pathUpdated" "permissionCreated" "permissionDeleted" "permissionUpdated" "roleCreated" "roleDeleted" "roleUpdated" "settingTypeCreated" "settingTypeDeleted" "settingTypeUpdated" "settingCreated" "settingDeleted" "settingUpdated" "unitSettingCreated" "unitSettingDeleted" "unitSettingUpdated" "unitTypeCreated" "unitTypeDeleted" "unitTypeUpdated" "unitCreated" "unitDeleted" "unitUpdated"

Responses

Request samples

Content type
application/vnd.api+json
{}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a hook

Retrieve the details of an existing hook using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the hook to be retrieved.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a hook

Update a hook

Request Body schema: application/vnd.api+json
required
required
object
required
object (Hook)

Hooks allow you to be notified when an event occurs and to automatically trigger a script.

isActive
boolean

True if the hook is enabled and will be triggered.

name
string

Name of the hook.

url
string

URL address the events will be posted to.

triggeredOn
Array of strings
Items Enum: "*" "accountCreated" "accountDeleted" "accountUpdated" "acknowledgementCreated" "acknowledgementDeleted" "acknowledgementUpdated" "actionTypeCreated" "actionTypeDeleted" "actionTypeUpdated" "actionCreated" "actionDeleted" "actionUpdated" "associationTypeCreated" "associationTypeDeleted" "associationTypeUpdated" "associationCreated" "associationDeleted" "associationUpdated" "attributeTypeCreated" "attributeTypeDeleted" "attributeTypeUpdated" "catalogMappingCreated" "catalogMappingDeleted" "catalogMappingUpdated" "catalogCreated" "catalogDeleted" "catalogUpdated" "codeCreated" "codeDeleted" "codeUpdated" "companyCreated" "companyDeleted" "companyUpdated" "entityTypeMappingCreated" "entityTypeMappingDeleted" "entityTypeMappingUpdated" "entityTypeCreated" "entityTypeDeleted" "entityTypeUpdated" "entityCreated" "entityDeleted" "entityUpdated" "eventTypeCreated" "eventTypeDeleted" "eventTypeUpdated" "eventCreated" "eventDeleted" "eventUpdated" "fileCreated" "fileDeleted" "fileUpdated" "grantCreated" "grantDeleted" "grantUpdated" "hookCreated" "hookDeleted" "hookUpdated" "keyCreated" "keyDeleted" "keyUpdated" "measurementCreated" "measurementDeleted" "measurementUpdated" "membershipCreated" "membershipDeleted" "membershipUpdated" "pathCreated" "pathDeleted" "pathUpdated" "permissionCreated" "permissionDeleted" "permissionUpdated" "roleCreated" "roleDeleted" "roleUpdated" "settingTypeCreated" "settingTypeDeleted" "settingTypeUpdated" "settingCreated" "settingDeleted" "settingUpdated" "unitSettingCreated" "unitSettingDeleted" "unitSettingUpdated" "unitTypeCreated" "unitTypeDeleted" "unitTypeUpdated" "unitCreated" "unitDeleted" "unitUpdated"

Responses

Request samples

Content type
application/vnd.api+json
{}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a hook

Delete a hook using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the hook to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Keys

List all keys

Returns a list of keys.

query Parameters
include
string
Value: "account"

Comma-separated list of related resources to include in the response, for example: account

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const keys = await bulbthings.keys.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a key

Create a key

Request Body schema: application/vnd.api+json
required
required
object
required
object (Key)
accountId
string <uuid>

Identifier of the account the key belongs to.

label
string or null

A short label describing the purpose of the key

value
string

Value of the key. This property is only visible once, at the key creation.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a key

Retrieve the details of an existing key using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the key to be retrieved.

query Parameters
include
string
Value: "account"

Comma-separated list of related resources to include in the response, for example: account

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a key

Update a key

Request Body schema: application/vnd.api+json
required
required
object
required
object (Key)
accountId
string <uuid>

Identifier of the account the key belongs to.

label
string or null

A short label describing the purpose of the key

value
string

Value of the key. This property is only visible once, at the key creation.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a key

Delete a key using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the key to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Measurements

All entity properties are updated through measurements. Even simple attributes such as the brand/size/color of an entity must be measured in order to be recorded. Measurements provide additional context information about the source of the value, the way and time at which it was observed, allowing to record the full history of modifications.

List all measurements

Returns a list of measurements.

query Parameters
include
string
Enum: "attributeType" "account" "entity"

Comma-separated list of related resources to include in the response, for example: attributeType,account,entity

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const measurements = await bulbthings.measurements.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a measurement

Create a measurement

Request Body schema: application/vnd.api+json
required
required
object
required
object (Measurement)

All entity properties are updated through measurements. Even simple attributes such as the brand/size/color of an entity must be measured in order to be recorded. Measurements provide additional context information about the source of the value, the way and time at which it was observed, allowing to record the full history of modifications.

companyId
string <uuid>

Identifier of the workspace the measurement belongs to.

entityId
required
string <uuid>

Identifier of the entity that was measured.

attributeTypeId
required
string

Identifier of the attribute type that was measured.

value
required
any

Value of the measured attribute type.

unitId
string or null

(Optional) For attribute types with units, specify which unit the measurement was done with. Defaults to the attribute type default unit, if any.

isAbsolute
boolean
Default: true

(Optional) For time-series attributes, whether or not the value is absolute or relative to the previous one.

object

(Optional) For time-series attributes, time at which the value was measured.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a measurement

Retrieve the details of an existing measurement using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the measurement to be retrieved.

query Parameters
include
string
Enum: "attributeType" "account" "entity"

Comma-separated list of related resources to include in the response, for example: attributeType,account,entity

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a measurement

Update a measurement

Request Body schema: application/vnd.api+json
required
required
object
required
object (Measurement)

All entity properties are updated through measurements. Even simple attributes such as the brand/size/color of an entity must be measured in order to be recorded. Measurements provide additional context information about the source of the value, the way and time at which it was observed, allowing to record the full history of modifications.

companyId
string <uuid>

Identifier of the workspace the measurement belongs to.

entityId
string <uuid>

Identifier of the entity that was measured.

attributeTypeId
string

Identifier of the attribute type that was measured.

value
any

Value of the measured attribute type.

unitId
string or null

(Optional) For attribute types with units, specify which unit the measurement was done with. Defaults to the attribute type default unit, if any.

isAbsolute
boolean
Default: true

(Optional) For time-series attributes, whether or not the value is absolute or relative to the previous one.

object

(Optional) For time-series attributes, time at which the value was measured.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a measurement

Delete a measurement using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the measurement to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Memberships

List all memberships

Returns a list of memberships.

query Parameters
include
string
Enum: "company" "account" "entity" "grants"

Comma-separated list of related resources to include in the response, for example: company,account,entity,grants

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const memberships = await bulbthings.memberships.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a membership

Create a membership

Request Body schema: application/vnd.api+json
required
required
object
required
object (Membership)
accountId
required
string <uuid>

Identifier of the account the membership is being granted to.

companyId
string <uuid>

Identifier of the workspace the membership refers to.

entityId
string or null <uuid>

Identifier of the entity associated with the account for that company.

isAdmin
boolean
Default: false

Specifies if the account is administrator of the company.

isActive
boolean
Default: true

Specifies if the membership is active or is disabled.

null or object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a membership

Retrieve the details of an existing membership using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the membership to be retrieved.

query Parameters
include
string
Enum: "company" "account" "entity" "grants"

Comma-separated list of related resources to include in the response, for example: company,account,entity,grants

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a membership

Update a membership

Request Body schema: application/vnd.api+json
required
required
object
required
object (Membership)
accountId
string <uuid>

Identifier of the account the membership is being granted to.

companyId
string <uuid>

Identifier of the workspace the membership refers to.

entityId
string or null <uuid>

Identifier of the entity associated with the account for that company.

isAdmin
boolean
Default: false

Specifies if the account is administrator of the company.

isActive
boolean
Default: true

Specifies if the membership is active or is disabled.

null or object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a membership

Delete a membership using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the membership to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Paths

List all paths

Returns a list of paths.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const paths = await bulbthings.paths.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Permissions

List all permissions

Returns a list of permissions.

query Parameters
include
string
Enum: "company" "role"

Comma-separated list of related resources to include in the response, for example: company,role

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const permissions = await bulbthings.permissions.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a permission

Create a permission

Request Body schema: application/vnd.api+json
required
required
object
required
object (Permission)
companyId
string or null <uuid>

Identifier of the workspace the permission belongs to.

roleId
required
string <uuid>

Identifier of the role the permission is granted to.

resource
required
string

Type of resource the permission is giving access to.

filter
string or null

Filter expression used to restrict the resources targeted by the permission.

rights
Array of strings or null

Array of rights given on the permission's resources.

bypassScope
boolean
Default: false

Whether or not this permission should bypass the entity scope filtering when being granted with a role.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a permission

Retrieve the details of an existing permission using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the permission to be retrieved.

query Parameters
include
string
Enum: "company" "role"

Comma-separated list of related resources to include in the response, for example: company,role

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a permission

Update a permission

Request Body schema: application/vnd.api+json
required
required
object
required
object (Permission)
companyId
string or null <uuid>

Identifier of the workspace the permission belongs to.

roleId
string <uuid>

Identifier of the role the permission is granted to.

resource
string

Type of resource the permission is giving access to.

filter
string or null

Filter expression used to restrict the resources targeted by the permission.

rights
Array of strings or null

Array of rights given on the permission's resources.

bypassScope
boolean
Default: false

Whether or not this permission should bypass the entity scope filtering when being granted with a role.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a permission

Delete a permission using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the permission to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Roles

List all roles

Returns a list of roles.

query Parameters
include
string
Enum: "company" "grants" "permissions"

Comma-separated list of related resources to include in the response, for example: company,grants,permissions

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const roles = await bulbthings.roles.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a role

Create a role

Request Body schema: application/vnd.api+json
required
required
object
required
object (Role)
companyId
string <uuid>

Identifier of the workspace the role belongs to.

label
required
string

Name given to the role.

description
string or null

Short description of the role's purpose.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a role

Retrieve the details of an existing role using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the role to be retrieved.

query Parameters
include
string
Enum: "company" "grants" "permissions"

Comma-separated list of related resources to include in the response, for example: company,grants,permissions

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a role

Update a role

Request Body schema: application/vnd.api+json
required
required
object
required
object (Role)
companyId
string <uuid>

Identifier of the workspace the role belongs to.

label
string

Name given to the role.

description
string or null

Short description of the role's purpose.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a role

Delete a role using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the role to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Setting Types

List all setting types

Returns a list of setting types.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const settingTypes = await bulbthings.settingTypes.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a setting type

Create a setting type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Setting Type)
companyId
string or null

Identifier of the workspace the setting type belongs to or null if the setting type is globally available.

schema
required
object

JSON Schema used to describe and validate the setting data.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a setting type

Retrieve the details of an existing setting type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the setting type to be retrieved.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a setting type

Update a setting type

Request Body schema: application/vnd.api+json
required
required
object
required
object (Setting Type)
companyId
string or null

Identifier of the workspace the setting type belongs to or null if the setting type is globally available.

schema
object

JSON Schema used to describe and validate the setting data.

object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a setting type

Delete a setting type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the setting type to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Settings

List all settings

Returns a list of settings.

query Parameters
include
string
Enum: "company" "account" "settingType"

Comma-separated list of related resources to include in the response, for example: company,account,settingType

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const settings = await bulbthings.settings.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a setting

Create a setting

Request Body schema: application/vnd.api+json
required
required
object
required
object (Setting)
companyId
string or null <uuid>

Identifier of the workspace the setting belongs to.

accountId
string or null <uuid>

Identifier of the account the setting belongs to or null if the setting is shared for the company.

settingTypeId
required
string

Type of setting.

value
required
any

Value of the setting.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a setting

Retrieve the details of an existing setting using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the setting to be retrieved.

query Parameters
include
string
Enum: "company" "account" "settingType"

Comma-separated list of related resources to include in the response, for example: company,account,settingType

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Update a setting

Update a setting

Request Body schema: application/vnd.api+json
required
required
object
required
object (Setting)
companyId
string or null <uuid>

Identifier of the workspace the setting belongs to.

accountId
string or null <uuid>

Identifier of the account the setting belongs to or null if the setting is shared for the company.

settingTypeId
string

Type of setting.

value
any

Value of the setting.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a setting

Delete a setting using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the setting to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Unit settings

List all unit settings

Returns a list of unit settings.

query Parameters
include
string
Enum: "company" "account" "attributeType" "unit"

Comma-separated list of related resources to include in the response, for example: company,account,attributeType,unit

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const unitSettings = await bulbthings.unitSettings.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Create a unit setting

Create a unit setting

Request Body schema: application/vnd.api+json
required
required
object
required
object (Unit setting)
companyId
string or null <uuid>

Identifier of the workspace the setting belongs to.

accountId
string or null <uuid>

Identifier of the account the setting belongs to or null if the setting is shared for the company.

attributeTypeId
required
string

Type of setting.

unitId
required
string

Identifier of the unit.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a unit setting

Retrieve the details of an existing unit setting using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the unit setting to be retrieved.

query Parameters
include
string
Enum: "company" "account" "attributeType" "unit"

Comma-separated list of related resources to include in the response, for example: company,account,attributeType,unit

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Delete a unit setting

Delete a unit setting using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the unit setting to be deleted.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ],
  • "meta": {
    },
  • "jsonapi": {
    }
}

Unit types

List all unit types

Returns a list of unit types.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const unitTypes = await bulbthings.unitTypes.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a unit type

Retrieve the details of an existing unit type using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the unit type to be retrieved.

query Parameters
include
string

Comma-separated list of related resources to include in the response, for example: related1,related1.related2

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}

Units

List all units

Returns a list of units.

query Parameters
include
string
Value: "unitType"

Comma-separated list of related resources to include in the response, for example: unitType

object

Return only specific fields in the response on a per-resource basis. Must be a comma-separated list that refers to the name(s) of the fields to be returned. For example: fields[resource1]=field1,field2&fields[resource2]=field3,field4.nested

filter
string

Filtering expression formatted according to Bulbthings' Resource Query Language.

group
string

Aggregating expression formatted according to Bulbthings' Resource Query Language.

sort
string

Sorting expression formatted according to Bulbthings' Resource Query Language.

object

Page limit and offset to use when returning the list of results.

Responses

Request samples 

const units = await bulbthings.units.findAll({
    page: { limit: 10 }
});

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": [
    ],
  • "meta": {
    }
}

Retrieve a unit

Retrieve the details of an existing unit using its unique identifier.

path Parameters
id
required
string <uuid>

The identifier of the unit to be retrieved.

query Parameters
include
string
Value: "unitType"

Comma-separated list of related resources to include in the response, for example: unitType

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "meta": {
    }
}