Brain Web API
The Brain Web API is a RESTful API that allows your application to interact with our devices and Web services. All available data as represented by resources, can be accessed and manipulated over HTTP via resource URIs in a state-less operation and client-server communication architecture model.
The basic API URI format is as follows:
|scheme||http or https||Brain uses Hypertext Transfer Protocol (Secure) as scheme|
|host||server.intellifi.nl||Address of the Brain server.|
|path||/api/resource-type/resource-id/||Path to resource-types and an individual resource. Each segment is separated with a slash (/).|
|query||?q1=value1&q2=value2||An optional query component that starts with question mark (?). Each extra query needs to be prefixed with an ampersand (&) delimiter for separation.|
The Brain offers a collection of resource types. The lists below represents a limited overview. A full list can be found in the API itself using path
/api or the Web API reference.
- spots: Smartspot device configuration and status.
- items: Items tagged with RFID, Bluetooth or other technologies.
- locations: Locations that can be used to report Items to.
- subscriptions: Event subscriptions and configuration.
- events: Events generated via the subscriptions.
The Web API uses JSON as its main encoding format. This means that the body for create and modify requests should be in JSON. The data of the returned responses is default returned as JSON but can be changed to CSV as well.
To change the output encoding to CSV, specify the .csv extension at the end of the path field for your URI. Example: https://server.intellifi.nl/api/resource-type.csv?q1=value1
The following HTTP methods are generally supported across all resource types. It may also be possible that other HTTP methods are available for specific resources. Please see the Web API reference for more information.
- POST: Create a new resource.
- PUT: Modify one resource.
- GET: Get one, multiple or all resources.
- DELETE: Deletes a resource.
Required HTTP header
The following HTTP header needs to be added to all requests with a request body:
Types of Access
All resource data
To access the data of a resource type, the path needs to contain the name of that resource type, for example items. Queries, depending on how specific they are, can return one, multiple or all resource data for that resource type. The following example returns all available data: https://server.intellifi.nl/api/resource-type
Single resource data
There are two options to access the data of a single resource:
- Use the ID of the resource as query:
- Specify the resource ID at the end of the path:
Returned data in case of the GET request on all resources within a resource type, use an envelope structure that contains a header and the result data. The header contains information about your request such as the total matches, number of returned resources and whether the returned data is paginated.
Pagination will occur when the amount of matching data is too large to return in a single response. The API returns the first chunk of data and offers a method the receive the following chunk for as long as needed to receive all data. For more information about pagination and how to use it see Pagination.
Note: When requesting a single resource using option 2 (see Types of Access above), won't return the data using this envelope structure.
There are a two options to authenticate your application with the Web API. Both of these options use a API key. This key can be generated in User and API key management using the Management Console.
- Add the HTTP Header
X-Api-Keyto the request and add the api key as header value,
- Add the API key as query element to the URI,
for example: https://server.intellifi.nl/api/resource-type/?key=111111-2222-3333-4444444444
A third way (but not meant for applications) is to login to the Brain Management Console. A session cookie will be created and grants you access to the API if you access it from your browser. Using this option, it's highly recommended to install a JSON viewer plugin to format the returned data.
Beside the standard queries using resource properties, the Brain offers advanced queries. More information about these queries and how to use them can be found in the Querying section.
Events and configuration
More information about how the Brain can generate events and how to configure this using event subscriptions can be found in the Events section.
OpenAPI Specification and Try-out
This API offers an OpenAPI specification and try-out that contains all detailed information about each resource type, their properties and how to access them. The specification file, generated reference documentation and try-out page can be found at intellifi-nl.github.io/brain-rest-api-spec and is also available on a Brain through the path
/api-doc since Brain software version 2.8.0.
Here are a couple recommended tools that can help you to start discovering the web API capabilities without programming.