Voodoo RoboticsDeveloper Portal

REST API Overview

Simple, powerful pick-to-light integration — the way it should be.

Two Different APIs

Voodoo Robotics supports two different APIs for interacting with Pick-to-Light devices. Integration between your warehouse management system (WMS) or Enterprise Resource Management Solution (ERP) is easy.

  • Recommended (REST API): For full-featured integrations, use the REST API with JSON payloads and standard HTTP methods. It supports device management, bulk operations, locations, orders, sequences, and closed-loop workflows.
  • Fallback (QueryString GET): If you need the simplest possible integration, use a query string with a GET request. It works well for initial evaluation, one-device commands, and systems with limited HTTP capabilities, but it does not follow REST principles.

Order-based picking

If your WMS or ERP already has order data, use the Orders API and Android picking app. The prebuilt GUI can run on a potentially inexpensive Android handheld scanner and saves you from building a picker interface from scratch.

Base URLs

All API requests are made against one of two base URLs depending on your server deployment:

Hosted (Multi-Tenant) Big Block: https://www.voodoodevices.com/api/
Self-Hosted Big Block: https://your-server-address/api/

Core Endpoints

Base URL: https://www.voodoodevices.com/api/
MethodEndpointDescription
GET/device/List all devices in your account (Index)
GET/device/{DeviceID}/Inspect a single device (voltage, uptime, etc.)
POST/device/{DeviceID}/Update/command a single device
POST/devices/Update multiple devices in one call
GET/turbo/List all Turbos
GET/turbo/{SerialNo}/Inspect a single Turbo
POST/user/login/Authenticate and obtain session/token
GET/location-aliases/List all location aliases
POST/location-aliases/Create a location alias
GET/orders/List all orders
POST/orders/Create a new order
GET/sequence/List all sequences
POST/sequence/Create a new sequence
GET/launchsequence/{seqID}/Launch or relaunch a sequence

Tip

POST and PUT are equivalent in our REST API since there is no separate object creation mechanism for devices. You can submit data as application/json or application/xml.

OpenAPI Specification

OAS 3.0

This API is fully OpenAPI Specification (OAS 3.0) compliant. The machine-readable spec unlocks powerful integrations:

  • Postman: use Import → Link and paste the spec URL — all endpoints, parameters, and example bodies load automatically.
  • AI coding tools (GitHub Copilot, Cursor, ChatGPT, etc.): paste the spec URL to generate client code with the documented field names and auth headers, then test and refine it against your environment.
  • SDK generators: produce typed clients in any language with tools like openapi-generator or fern.

Spec URL (Devices & Turbos):

https://bblock-demo.voodoorobotics.com/devices/openapi.json

For a complete, production-focused workflow, use the Voodoo Oracle to turn the specification and an existing integration example into a tested project with deployment instructions.

Index Request

Get a list of all devices in your account. Use a GET request on the endpoint /api/device/. You can use XML or JSON in your request.

Inspect Request

Once you have a particular DeviceID, you can get more information about that device (voltage, uptime, etc.). Use a GET request on the endpoint/api/device/FFFFFF:EEEEEE/.

Update Request

Update the message on a device. Use a POST request on the endpoint/api/device/FFFFFF:EEEEEE/.

Update Multiple Devices

Update multiple devices in one API call. Use a POST request on the endpoint /api/devices/ (note the plural). This saves time and resources by consolidating API calls. See the multiple devices FAQ entry for a worked example with the correct endpoint.

Most Simple Example

In just five lines of Python code, you can send a simple command to a device. Notice that the example uses a single requests.Session() object — reusing the same HTTP connection avoids paying the DNS, TCP, and TLS setup cost on every request. See the connection overhead FAQ entry for timing measurements and a deeper explanation.

import requests, json

session = requests.Session()
url = "https://www.voodoodevices.com/api/"

x = session.post(url + "user/login/",
    json={'username': 'yourusername', 'password': 'yourpassword'})
z = json.loads(x.text)

session.post(
    url + "device/E8D008:619874/",
    headers={'referer': url, 'x-csrf-token': z['token']},
    json={'command': 'flash', 'line1': 'Hello', 'line2': 'There', 'seconds': 60},
)
Preview these values in the simulator

Step-by-Step Example

A more complete example demonstrating device info retrieval, device listing, and messaging:

import requests

API_KEY = 'your_api_key_here'
url = 'https://www.voodoodevices.com/api/'

headers = {
    'API-KEY': f'{API_KEY}',
    'Content-Type': 'application/json',
}

def get_device_info(device_id):
    """Retrieve all Cloud Display Device attributes from Big Block."""
    response = requests.get(f"{url}device/{device_id}/", headers=headers)
    return response.json()

def get_device_list():
    """Return a list of all Device IDs in Big Block."""
    response = requests.get(f"{url}device/", headers=headers)
    return response.json()

def send_message(device_id, line1, line2, color='r', seconds=60):
  """Send a simple two-line message to a device."""
  data = {
    'command': 'flash',
    'line1': line1,
    'line2': line2,
    'color': color,
    'seconds': seconds,
  }
    response = requests.post(f"{url}device/{device_id}/", headers=headers, json=data)
    return response.json()

# Usage examples:
# device_info = get_device_info('D4E825:8B665D')
# device_list = get_device_list()
# send_message('D4E825:8B665D', 'Take 5', 'Red Widgets', color='r')

Python REST API Video Guides

These walkthroughs show how to turn repeated API calls into reusable Python functions and how to retrieve information from Big Block.

REST API: Defining Functions

Build reusable Python functions for common Big Block REST API calls.

Watch on YouTube

REST API: Getting Info from Big Block

Use REST GET requests to retrieve device and system information from Big Block.

Watch on YouTube

Inspect Turbos

Similar to the device endpoint, you can use the turbo endpoint to get information about your Turbos. Use a GET request on/api/turbo/ or/api/turbo/SERIALNO/.

# List all Turbos
response = requests.get(f"{url}turbo/", headers=headers)
turbos = response.json()

# Get info for a specific Turbo
response = requests.get(f"{url}turbo/1000044044404/", headers=headers)
turbo_info = response.json()

Note

You can write your integration code in any language. Python is used in these examples because it is easy for any programmer to read and understand the critical steps.

Commands vs. Statics

Understanding the difference between commands (time-bound, generate ACK/NACK) and statics (persistent, no timeout) is essential for building reliable integrations. See the Commands vs. Statics Quick Reference for detailed guidance on field classification, timeouts, and best practices.

Related Pages

Commands vs. Statics

Essential guide to command vs. static behavior

Location Alias API

Device location management and multi-location aliases

Orders API

Structured fulfillment with an Android picking app

Sequence API

Create and manage step-based sequences

Authentication

Auth methods: Basic, API-KEY, Session, OAuth2