Smart blaze REST API Reference#

This topic describes the REST API provided by the Smart blaze camera.

The REST API can be used to control of the virtual machine (VM). It allows you to manage the VM lifecycle, upload images, and configure network settings from the command line or using custom scripts.

All API endpoints are accessed via the camera's IP address:

http://${cameraip}

Authentication#

The Smart blaze REST API uses session-based authentication with a challenge-response mechanism to protect against unauthorized access. The default password is unique for each camera and printed on a label on the camera.

All API endpoints (except /login) require authentication via session cookies. Authentication involves three steps:

1. Obtaining a login challenge by sending a GET request to /login
2. Computing the challenge response using the nonce from the challenge
3. Submitting the challenge response to complete authentication

Obtaining a Login Challenge#

Endpoint: /login

Method: GET

Response: HTML page containing a nonce in a hidden form field

Computing the Challenge Response#

The challenge response must be computed as follows:

response = SHA256(nonce + ":" + SHA256(password))

Where:

• nonce is the value from the login challenge.
• password is your plain-text password.
• SHA256 produces a lowercase hexadecimal string.

Example (using the shell):

# Get the nonce from the login page
NONCE=$(curl -s http://${cameraip}/login | grep -oP 'id="challenge-nonce"[^>]*value="\K[^"]+')

# Your password
PASSWORD="blaze-oh-yeah"

# Compute password hash
PASSWORD_HASH=$(echo -n "$PASSWORD" | sha256sum | awk '{print $1}')

# Compute challenge response
RESPONSE=$(echo -n "${NONCE}:${PASSWORD_HASH}" | sha256sum | awk '{print $1}')

Submitting the Challenge Response#

Endpoint: /login

Method: POST

Content-Type: application/x-www-form-urlencoded

Parameters:

Response: Redirects to main page on success. Returns login page with error on failure.

Example:

curl -c cookies.txt -b cookies.txt -X POST http://${cameraip}/login \
  -d "challenge_response=${RESPONSE}"

After successful authentication, include the session cookie in all subsequent API requests:

# Using curl with cookie file
curl -b cookies.txt -X POST http://${cameraip}/vm/restart

Complete Authentication Example#

Here's a complete shell script example:

#!/bin/bash

CAMERA_IP="192.168.1.123"
PASSWORD="blaze-oh-yeah"

# Get login challenge
echo "Getting login challenge..."
NONCE=$(curl -s -c cookies.txt http://${CAMERA_IP}/login | \
    grep -oP 'id="challenge-nonce"[^>]*value="\K[^"]+')

if [ -z "$NONCE" ]; then
    echo "Failed to get login challenge"
    exit 1
fi

# Compute challenge response
PASSWORD_HASH=$(echo -n "$PASSWORD" | sha256sum | awk '{print $1}')
RESPONSE=$(echo -n "${NONCE}:${PASSWORD_HASH}" | sha256sum | awk '{print $1}')

# Login
echo "Logging in..."
curl -s -b cookies.txt -c cookies.txt -X POST http://${CAMERA_IP}/login \
    -d "challenge_response=${RESPONSE}" > /dev/null

# Now you can make authenticated API calls
echo "Making authenticated API call..."
curl -b cookies.txt -X POST http://${CAMERA_IP}/vm/restart

echo "Done"

Security Features#

• Challenge-Response Authentication: Prevents password transmission over the network.
• Rate Limiting: Failed login attempts are rate-limited to prevent brute-force attacks.
• Session Security:
  • HTTP-only cookies (not accessible via JavaScript)
  • SameSite=Strict cookie policy
  • 60-second challenge timeout
• Password Storage: Passwords are stored as SHA256 hashes only.

Users can set a custom password via the web interface.

Session Logout#

To log out and clear the session:

Endpoint: /logout

Method: POST

curl -b cookies.txt -X POST http://${cameraip}/logout

API Endpoints#

For brevity, the examples below show the API calls without the authentication step. In practice, include -b cookies.txt in your curl commands after authenticating.

API Calls for VM Control#

Restarting the VM#

Restart the virtual machine.

Endpoint: /vm/restart

Method: POST

Response: Redirects to main page

Example:

curl -X POST http://${cameraip}/vm/restart

Starting the VM#

Start the virtual machine.

Endpoint: /vm/start

Method: POST

Response: Redirects to main page

Example:

curl -X POST http://${cameraip}/vm/start

Stopping the VM#

Stop the virtual machine.

Endpoint: /vm/stop

Method: POST

Response: Redirects to main page

Example:

curl -X POST http://${cameraip}/vm/stop

API Calls for VM Configuration#

Configuring IP Settings#

Configure the VM's network settings (DHCP or static IP).

Endpoint: /vm/ip

Method: POST

Content-Type: application/x-www-form-urlencoded

Parameters:

Response: Redirects to main page

Example: Configuring Static IP#

curl -X POST http://${cameraip}/vm/ip \
  -d "mode=Manual" \
  -d "address=192.168.1.127/24" \
  -d "gateway=192.168.1.1" \
  -d "dns0=8.8.8.8" \
  -d "dns1=8.8.4.4"

Example: Enabling DHCP#

curl -X POST http://${cameraip}/vm/ip \
  -d "mode=DHCP" \
  -d "address=192.168.1.127/24" \
  -d "gateway=" \
  -d "dns0=" \
  -d "dns1="

Updating VM Settings#

Configure VM behavior settings.

Endpoint: /vm/settings

Method: POST

Content-Type: application/x-www-form-urlencoded

Parameters:

Response: Redirects to main page

Example:

curl -X POST http://${cameraip}/vm/settings \
  -d "wait_console=on"

Image Management#

Listing Available Images#

List all installed VM images with their active status and size.

Endpoint: /vm/images

Method: GET

Response: JSON array of image objects

Response Fields:

Example:

curl http://${cameraip}/vm/images

Response:

[
  {"name": "debian-arm64-min", "is_active": true, "size": "1.2G"},
  {"name": "custom-app", "is_active": false, "size": "2.4G"}
]

Checking VM Image Upload#

Check whether a VM image can be uploaded before transferring the archive. This validates the file name, .tar.gz extension, image name, overwrite constraints, and available storage space using the same checks as the upload endpoint.

Endpoint: /vm/check_image_uploadable

Method: POST

Content-Type: application/json

Request Fields:

Success Response:

{
  "success": true,
  "image_name": "debian-arm64-8GB"
}

If an inactive image with the same name exists and overwrite is false:

{
  "success": false,
  "error": "Image 'debian-arm64-8GB' already exists.",
  "needs_confirmation": true
}

Other validation failures return:

{
  "success": false,
  "error": "Error message"
}

Example:

curl -X POST http://${cameraip}/vm/check_image_uploadable \
  -H "Content-Type: application/json" \
  -d '{"filename":"debian-arm64-8GB.tar.gz","size":2147483648,"overwrite":false}'

Uploading VM Image#

Upload a new VM image archive. The archive should contain the rootfs and kernel files.

Endpoint: /vm/image

Method: POST

Content-Type: multipart/form-data

Parameters:

Supported Archive Contents:

The uploaded archive must contain the following:

• A rootfs file: rootfs.qcow2, rootfs.img, or rootfs.raw
• A kernel file: kernel

For more information, see VM Image Structure.

Response: JSON

Success Response:

{
  "success": true
}

Error Responses:

{
  "success": false,
  "error": "Error message"
}

{
  "success": false,
  "error": "Image 'image-name' already exists.",
  "needs_confirmation": true
}

{
  "success": false,
  "error": "Cannot overwrite the active image: image-name"
}

Example: Uploading and Activating New Image (Default)#

curl -F "file=@debian-arm64-8GB.tar.gz" http://${cameraip}/vm/image

Response:

{"success":true}

Example: Uploading Without Activating#

curl -F "file=@debian-arm64-8GB.tar.gz" "http://${cameraip}/vm/image?set_active=false"

Response:

{"success":true}

Example: Upload Failed (Image Exists)#

curl -F "file=@debian-arm64-8GB.tar.gz" http://${cameraip}/vm/image

Response:

{"error":"Image 'debian-arm64-8GB' already exists.","needs_confirmation":true,"success":false}

Example: Overwriting Existing Image and Activating#

curl -F "file=@debian-arm64-8GB.tar.gz" "http://${cameraip}/vm/image?overwrite=true"

Example: Overwriting Existing Image Without Activating#

curl -F "file=@debian-arm64-8GB.tar.gz" "http://${cameraip}/vm/image?overwrite=true&set_active=false"

Selecting the Active Image#

Change the active VM image to a different installed image.

Endpoint: /vm/select_image

Method: POST

Content-Type: application/x-www-form-urlencoded

Parameters:

Response: Redirects to main page

Example:

curl -X POST http://${cameraip}/vm/select_image \
  -d "image_name=debian-arm64-8GB"

Deleting a VM Image#

Delete an installed VM image.

Endpoint: /vm/delete_image

Method: POST

Content-Type: application/x-www-form-urlencoded

Parameters:

Response: Redirects to main page

Example:

curl -X POST http://${cameraip}/vm/delete_image \
  -d "image_name=old-image"

Renaming a VM Image#

Rename an installed VM image.

Endpoint: /vm/rename_image

Method: POST

Content-Type: application/x-www-form-urlencoded

Parameters:

Response: Redirects to main page

Example:

curl -X POST http://${cameraip}/vm/rename_image \
  -d "old_image_name=debian-arm64-8GB" \
  -d "new_image_name=my-custom-vm"

System Maintenance#

Factory Reset#

Reset the VM to factory defaults. This removes all custom VM images, restores the original rootfs and kernel, and resets the VM configuration.

Endpoint: /vm/factory_reset

Method: POST

Response: JSON

Success Response:

{
  "success": true
}

Error Response:

{
  "success": false,
  "error": "Error message"
}

Example:

curl -X POST http://${cameraip}/vm/factory_reset

Response:

{"success":true}

Error Handling#

API endpoints that return JSON include a success field:

• true: Operation completed successfully.
• false: Operation failed. Check the error field for details.

Some error responses may include additional fields:

• needs_confirmation: Set to true if the operation requires explicit confirmation (e.g., overwriting an existing image).

Common Use Cases#

Uploading and Activating a Custom VM Image#

#!/bin/bash

CAMERA_IP="192.168.1.123"
PASSWORD="blaze-oh-yeah"  # Replace with your camera's password
IMAGE_FILE="my-custom-vm.tar.gz"

# Authenticate
NONCE=$(curl -s -c cookies.txt http://${CAMERA_IP}/login | \
    grep -oP 'id="challenge-nonce"[^>]*value="\K[^"]+')
PASSWORD_HASH=$(echo -n "$PASSWORD" | sha256sum | awk '{print $1}')
RESPONSE=$(echo -n "${NONCE}:${PASSWORD_HASH}" | sha256sum | awk '{print $1}')
curl -s -b cookies.txt -c cookies.txt -X POST http://${CAMERA_IP}/login \
    -d "challenge_response=${RESPONSE}" > /dev/null

# Upload and activate the image archive (default behavior)
RESULT=$(curl -b cookies.txt -F "file=@${IMAGE_FILE}" http://${CAMERA_IP}/vm/image)
echo "$RESULT"

# The VM will automatically restart with the new image

Uploading VM Image Without Activating It#

#!/bin/bash

CAMERA_IP="192.168.1.123"
PASSWORD="blaze-oh-yeah"  # Replace with your camera's password
IMAGE_FILE="backup-vm.tar.gz"

# Authenticate (authentication code omitted for brevity, see above)

# Upload the image without activating it (VM keeps running)
RESULT=$(curl -b cookies.txt -F "file=@${IMAGE_FILE}" \
    "http://${CAMERA_IP}/vm/image?set_active=false")
echo "$RESULT"

# The image is now stored but not active. You can activate it later using /vm/select_image

Switching Between Installed Images#

# Authenticate (see above for full authentication example)
# Then select a different image
curl -b cookies.txt -X POST http://${cameraip}/vm/select_image \
    -d "image_name=debian-arm64-base"

Configuring Static IP for Direct Connection#

# Authenticate first, then configure network
curl -b cookies.txt -X POST http://${cameraip}/vm/ip \
  -d "mode=Manual" \
  -d "address=192.168.1.200/24" \
  -d "gateway=192.168.1.1" \
  -d "dns0=8.8.8.8" \
  -d "dns1="

Automating VM Image Deployment#

#!/bin/bash

CAMERA_IP="192.168.1.123"
PASSWORD="blaze-oh-yeah"  # Replace with your camera's password
IMAGE_FILE="production-vm.tar.gz"

# Function to authenticate
authenticate() {
    echo "Authenticating..."
    NONCE=$(curl -s -c cookies.txt http://${CAMERA_IP}/login | \
        grep -oP 'id="challenge-nonce"[^>]*value="\K[^"]+')

    if [ -z "$NONCE" ]; then
        echo "Failed to get login challenge"
        return 1
    fi

    PASSWORD_HASH=$(echo -n "$PASSWORD" | sha256sum | awk '{print $1}')
    RESPONSE=$(echo -n "${NONCE}:${PASSWORD_HASH}" | sha256sum | awk '{print $1}')

    curl -s -b cookies.txt -c cookies.txt -X POST http://${CAMERA_IP}/login \
        -d "challenge_response=${RESPONSE}" > /dev/null

    return 0
}

# Authenticate
if ! authenticate; then
    echo "Authentication failed"
    exit 1
fi

# Upload VM image without activating it
echo "Uploading VM image to camera..."
RESPONSE=$(curl -s -b cookies.txt -F "file=@${IMAGE_FILE}" \
    "http://${CAMERA_IP}/vm/image?set_active=false")

if echo "$RESPONSE" | grep -q '"success":true'; then
    echo "Upload successful!"
else
    echo "Upload failed:"
    echo "$RESPONSE"
    exit 1
fi

# Activate the uploaded image
echo "Activating new VM image..."
IMAGE_NAME="${IMAGE_FILE%.tar.gz}"
curl -s -b cookies.txt -X POST http://${CAMERA_IP}/vm/select_image \
    -d "image_name=${IMAGE_NAME}"

echo "VM is restarting with new image."

VM Control Web Interface#

For interactive management, access the Smart blaze VM Control web interface:

xdg-open http://${cameraip}

The web interface provides a graphical user interface for the following tasks:

• Viewing the VM status
• Controlling the VM lifecycle (start/stop/restart)
• Configuring network settings
• Uploading and managing VM images
• Monitoring disk usage
• Changing the password

Further Information#

• For information about initial setup and configuration, see Getting Started.