Overview and Enabling

Expert Topic for experienced builders.

Big idea

Control Bottango with your own scripts and applications using the Bottango REST API. Some example supported functionality includes starting / stopping specific animations at specific times, and exporting out animation data.

What the Bottango REST API is for

The Bottango REST API allows you to use your own scripts and applications to trigger, control, and get more information on animations in your Bottango project. This could be used to integrate Bottango with your own or other robotic control applications. Or it could be used for you to make a hardware controller to start and stop different animations at a physical button press.

Included in this “advanced features” folder is an example Python script for each command, replicated here in the documentation as well. These should show you how to call each endpoint currently available in the REST API.

What can you do with the Bottango REST API

Here is the major functionality available to you currently in the Bottango REST API:

• Get whether Bottango is currently able to start playing an animation.
• Get information on the animations available in your project, and which animation is currently selected.
• Get information on the current playback state of Bottango, including the signal and movement of all effectors in the project.
• Export animation commands to JSON
• Start / stop playing an animation.
• Start / stop recording live controller input (if a control scheme is selected)
• Set playback time.
• Change the selected animation.
• Drive input into the input recording features of Bottango
• Call “STOP” in Bottango (the same as pressing the escape key on the keyboard).

Enabling the REST API

The Bottango REST API works as a local server on your machine. You call into it with GET and PUT requests the way you would a remote REST API. If you can make and receive JSON in a web request, you can interact with the Bottango REST API.

You can enable the Bottango REST API in a project by toggling the “API Access” toggle in the hardware menu:

Once it is enabled, you will see an “API” notification in the top bar as well:

Connection to the Bottango REST API is by default as a local server on port 59224 (example: localhost:59224/). You can change the port if needed in that same menu.

Security Considerations

With most default network settings, the server runs on the local machine and may also be reachable from other devices on the same LAN (assuming the OS firewall allows inbound traffic on that port).

The REST API does not implement authentication/authorization and assumes requests are trusted. It is not recommended to enable the REST API on networks with untrusted devices or on public/shared networks. It is strongly discouraged to expose the port beyond the local network through network configuration changes such as port forwarding, public IP routing, or VPN access.