Device Identification

The Device Identification API predicts the vendor of IoT devices using partial or complete metadata. It is designed for incremental queries: you can call the API multiple times for the same device as new evidence becomes available (e.g., OUI → DHCP → hostnames).

Access is restricted. API keys are issued only upon request. Please contact the maintainers to request access.

Base URL

https://dev-id-1.tailcedbd.ts.net

Authentication

All requests must include a valid API key in the header: x-api-key: <api_key>

Example: curl -H "x-api-key: <api-key>" https://dev-id-1.tailcedbd.ts.net/health

Endpoints

GET /health

Check if the API is live.

curl -s https://dev-id-1.tailcedbd.ts.net/health \
  -H "x-api-key: <api-key>"

Response:

{
  "status": "ok",
  "device": "cuda" 
}

POST /predict

Submit device metadata for vendor prediction.

Request body:

{
  "fields": {
    "OUI": "string",
    "DHCP Hostname": "string",
    "User Agent": "string",
    "Remote Hostnames": ["string"],
    "mDNS": "string",
    "SSDP": "string",
    "Netdisco Info": "string",
    "Talks to Ads": true
  }
}

Response body:

{
  "Explanation": "...",
  "Vendor": "..."
}

Field Reference

Field	Type	Description
fields.OUI	string	Organizationally Unique Identifier from the device MAC address.
fields.DHCP Hostname	string	Hostname advertised via DHCP.
fields.User Agent	string	User agent string observed in network traffic.
fields.Remote Hostnames	array	List of external domains contacted by the device.
fields.mDNS	string	Multicast DNS data broadcast by the device.
fields.SSDP	string	Simple Service Discovery Protocol response from the device.
fields.Netdisco Info	string	Additional discovery info (e.g., UPnP, SNMP).
fields.Talks to Ads	boolean	Whether the device contacts known advertising/analytics domains.

Example Usage:

curl -s -X POST "https://dev-id-1.tailcedbd.ts.net/predict" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <api_key>" \
  -d '{
    "fields": {
      "DHCP Hostname": "echo-dot-1234.local",
      "Remote Hostnames": "alexa.amazon.com+device-metrics-us.amazon.com",
      "User Agent": "AlexaMediaPlayer/3.0",
      "Talks to Ads": false
    }
  }' 

Response:

{
  "Explanation": "The device is an Echo Dot.",
  "Vendor": "Amazon"
}

You may start with partial information (e.g., only DHCP Hostname or OUI) and incrementally add more fields (e.g., Remote Hostnames, User Agent, Netdisco Info) to refine predictions.

Notes

• API keys are issued on request only.
• Call /predict multiple times as new fields become available.
• Flexible: Works with partial input (e.g., only OUI, only hostnames).
• Identical queries cached for 10 minutes.
• HTTPS provided via Tailscale Funnel.