Manually add a lock controller

POST

/controllers

Manually register a lock controller when mDNS auto-discovery is unavailable or fails.

Use cases:

mDNS service disabled on controller

Network configuration blocking mDNS broadcasts

Manual IP address configuration

Testing and development

Behavior:

Creates controller record with provided details

Automatically provisions specified number of lockers (default: 20)

Validates hostname uniqueness (duplicate hostnames rejected)

Logs operation with source tracking

Initial operational status set to true (health check will update)

Important:

Hostname must be unique in the system

If IP address provided, controller reachable via IP (mDNS optional)

Request

Authorization

Basic Auth

Send your HTTP requests with an

Authorization

header that contains the word Basic followed by a space and a base64-encoded string username:password

Example:

Authorization: Basic *****************

API Key

Add parameter in header

X-Session-Token

Example:

X-Session-Token: ********************

Body Params application/jsonRequired

Examples

Responses

🟢201Created

application/json

Controller created successfully

Body

🟠400Bad Request

🟠409Conflict

🔴500Internal Server Error

Request Example

Shell

JavaScript

Java

Swift

cURL

Controller with IP addressController with only hostname (mDNS required)

curl --location --request POST '/controllers' \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "South Bank",
    "hostname": "luxer-abc123.local",
    "ipAddress": "192.168.1.100",
    "port": 8080,
    "lockerCount": 20
}'

Response Example

201 - Example 1

{
    "success": true,
    "controller": {
        "id": 0,
        "name": "string",
        "hostname": "string",
        "ipAddress": "string",
        "port": 8080,
        "operational": true,
        "operationalLastChecked": "2019-08-24T14:15:22Z",
        "lastSeen": "2019-08-24T14:15:22Z",
        "reasonCode": "CONTROL_BOARD_UNREACHABLE",
        "reason": "string",
        "lockerCount": 0,
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z"
    },
    "lockersCreated": 0
}

Modified at 2025-11-27 00:06:25

List all lock controllers

Trigger manual mDNS scan