Skip to main content
This guide will show you how to bind, unbind, and monitor devices using the Plaud Device API.

​
Using the Device API

1

Create an API Token

Create an API token using your client credentials to securely access the API.
PLAUD_API_TOKEN = <your_api_token_here>
2

Bind or Unbind a Device

A recording’s ownership is inherited from the user account that owns the device. Therefore, you must bind a device to a user before uploading any recordings.
  • Bind Device
  • Unbind Device
Bind a device to a user account. If the device has no association with any account, this API will return a device_id, an unique identifier under current App.
import requests

PLAUD_API_TOKEN = "<your_api_token_here>"
BASE_URL = "https://api.plaud.ai/api"
headers = {
    "Authorization": f"Bearer {PLAUD_API_TOKEN}",
    "Content-Type": "application/json"
}

def bind_device(owner_id, device_type, serial_number):
    """Bind a device to an account"""
    response = requests.post(
        f"{BASE_URL}/devices/bind",
        headers=headers,
        json={
            "owner_id": owner_id,
            "sn_type": device_type,  # "notepin", "note", "notepro"
            "sn": serial_number
        }
    )
    response.raise_for_status()
    return response.json()

# Example usage
device = bind_device(
    owner_id="user_12345",
    device_type="notepin", 
    serial_number="NP20240001"
)

print(f"Device bound successfully!")
print(f"Device ID: {device['id']}")
3

Get Device Information

After binding a device, you can use its device_id to fetch its status and health metrics.
# This snippet assumes 'BASE_URL' and 'headers' are defined as in the previous steps.
# PLAUD_API_TOKEN = "<your_api_token_here>"

def get_device_info(device_id):
    """Get device status and health metrics"""
    response = requests.get(
        f"{BASE_URL}/devices/{device_id}",
        headers=headers
    )
    response.raise_for_status()
    return response.json()

# Example usage using the ID from the binding step
# device_id = bound_device['id']
device_id = "<your_device_id>" 
device_info = get_device_info(device_id)

print(f"✅ Device info for {device_id}:")
print(f"   Battery: {device_info.get('battery')}%")
print(f"   Storage: {device_info.get('free_space')}MB available")
4

Execute the Code

To run the full workflow, you can combine the Python snippets into a single script. Create a file named example.py:
import requests

PLAUD_API_TOKEN = "<your_api_token_here>"
BASE_URL = "https://api.plaud.ai/api"
headers = {
    "Authorization": f"Bearer {PLAUD_API_TOKEN}",
    "Content-Type": "application/json"
}

def bind_device(owner_id, device_type, serial_number):
    """Bind a device to an account"""
    response = requests.post(
        f"{BASE_URL}/devices/bind",
        headers=headers,
        json={
            "owner_id": owner_id,
            "sn_type": device_type,  # "notepin", "note", "notepro"
            "sn": serial_number
        }
    )
    response.raise_for_status()
    return response.json()

def get_device_info(device_id):
    """Get device status and health metrics"""
    response = requests.get(
        f"{BASE_URL}/devices/{device_id}",
        headers=headers
    )
    response.raise_for_status()
    return response.json()

# Main execution
if __name__ == "__main__":
    print("Binding device...")
    bound_device = bind_device(
        owner_id="user_12345",
        device_type="notepin", 
        serial_number="NP20240001"
    )
    device_id = bound_device.get('id')
    print(f"Device bound successfully with ID: {device_id}")

    if device_id:
        print(f"\nFetching info for device {device_id}...")
        device_info = get_device_info(device_id)
        print(f"✅ Device info retrieved:")
        print(f"   Battery: {device_info.get('battery')}%")
        print(f"   Storage: {device_info.get('free_space')}MB available")
Then, run it from your terminal:
python example.py
You should see device_id and health information printed to the console.

​
Monitoring Metrics

When you fetch device information, you can monitor the following metrics.
MetricDescriptionAlert Threshold
Battery LevelDevice battery percentage< 20%
Storage UsageUsed storage percentage> 90%
WiFi SignalWiFi signal strength (dBm)< -70 dBm
Last UpdateTime since last status update> 24 hours
Binding StatusWhether device is bound to userUnbound devices

​
Common Error Scenarios

OperationError CodeCause
BindingDevice Already BoundIf the device is already bound to another user, you’ll receive a 400 error with detail DEVICE_BOUND
UnbindingDevice Not FoundWhen unbinding, if the device isn’t found, you’ll receive a 400 error with detail DEVICE_NOT_FOUND
MonitoringDevice Not FoundIf the device doesn’t exist in the system, returns 404
MonitoringInvalid Status DataIf the status update is malformed, returns 422 validation error
MonitoringRate Limit ExceededIf too many status updates are sent, returns 429

​
Next Steps

Explore the API reference for more information on the Device API and its details.