RESTful API Reference¶

Welcome to the BrainStem RESTful API reference documentation. This interface provides access to the BrainStem protocol over HTTP as well as additional information about system versions, attached USB devices, and bulk data transfers.

Use of the RESTful API requires either BrainD, or one of the applications built on BrainD, such as ControlRoom.

Receiving information from the RESTful interface occurs through an HTTP GET request. Sending or setting information occurs through a PUT interface.

The current version of the RESTful interface is v1. Changes that do not break a RESTful API will not constitute a version change. Removing features or making significant changes will result in a version change. Deploying breaking changes may be necessary for legal, performance, or security reasons. When a new version is released, the current version will remain supported for one year and may become unavailable anytime after this period.

API Version v1¶

GET http://<IPADDRESS>:<PORT>/api/v1/<ENDPOINT>/<PARAMETERS>
PUT http://<IPADDRESS>:<PORT>/api/v1/<ENDPOINT>/<PARAMETERS> {BODY}

Endpoint Struture Definition¶
Parameter	Request Type	Description
IPADDRESS	GET, PUT	IP Address of BrainD server hosting RESTful endpoints.
PORT	GET, PUT	Port that BrainD server is listening for connections. Default is `9005`.
ENDPOINT	GET, PUT	RESTful API endpoint to access.
PARAMETERS	GET, PUT	Command parameters for the given ENDPOINT.
BODY	PUT	HTTP `PUT` payload for the given ENDPOINT and PARAMETERS.

The available options for the ENDPOINT parameter are listed below:

Available Endpoints¶
Service	Description
acronameDevices	Enumeration of attached Acroname devices
acronameDevicesState	Bulk Endpoint containing telemetry about all attached Acroname devices
brainstem	Raw access to BrainStem API for a device
devices	List of all USB devices connected to the host computer
version	Software Versions

The response body for all RESTful API calls will be encapsulated in a transaction envelope. This envelope will provide error information, request context, and other useful fields about the request and the response payload for the specific API call.