Hardware API

A capability-based device integration system. Devices declare what they can do, exercises declare what capabilities they can use, and the system matches them automatically.

Quick Start

GET /api/devices/registry — Browse device descriptors

GET /api/devices/registry/schema — Descriptor JSON schema + capabilities

POST /api/devices/registry/propose — Submit a new device

GET /api/devices/registry/stats — Registry statistics

Core Concepts

Device Descriptor

What a device IS and CAN DO — its capabilities, params, metrics, and connection protocol.

Hardware Enhancement

What an exercise CAN USE — capabilities it benefits from (e.g. variable_resistance, force_measurement).

Device Program

Timed command sequences for interval/ramp workouts — steps with triggers, actions, and params.

Capability Vocabulary

24 standard capabilities across 4 categories. Devices and exercises reference these by ID.

Load

variable_resistanceeccentric_controlisometric_holdspeed_controlincline_controlresistance_control

Tracking

force_measurementposition_trackingvelocity_trackingpower_trackingcadence_trackingdistance_trackingpace_trackingheart_rate_monitorheart_rate_passthroughstep_countergps_trackingaccelerometerbalance_measurement

Feedback

haptic_feedbackaudio_feedbackvisual_feedback

Control

programmable_sequencerow_simulation

Device Tiers

Native

Full OWS protocol support. Real-time WebSocket communication, zero-latency control, full metrics streaming.

Standard

BLE FTMS, ANT+ FE-C. Industry-standard protocols for treadmills, bikes, rowers, heart rate monitors.

Basic

Manual/limited. Custom JSON descriptors, HTTP polling, or user-entered data.

API Endpoints

GET/api/devices/registry

List all built-in device descriptors. Add ?include=community to include approved community contributions.

Query Params
include (string) — "community" to include approved community descriptors
ResponseDeviceDescriptor[]
GET/api/devices/registry/schema

Returns the JSON schema for device descriptors, the capability vocabulary, and an example descriptor.

Response{ schema, capabilities, example }
GET/api/devices/registry/stats

Registry statistics: built-in count, community count, breakdown by category.

Response{ builtIn: { total, byCategory }, community: { total, approved, pending, rejected, byCategory } }
POST/api/devices/registry/proposeRequires userId in body

Submit a new device descriptor for community review. Validates against the schema and checks for duplicates.

Request Body
descriptor (DeviceDescriptor) — Full device descriptor object
submittedBy (string) — User ID of the submitter
citations (Citation[]) — Optional supporting links (manufacturer docs, teardowns, etc.)
context (string) — Optional notes about the submission
Response{ decision, reasoning, entryId, descriptorId }
GET/api/devices/registry/feedback?registryEntryId=...

Get community votes for a registry entry.

Response{ feedback, upCount, downCount, total }
POST/api/devices/registry/feedback

Vote on a device descriptor (up/down).

Request Body
registryEntryId (string) — Registry entry ID
userId (string) — Voter user ID
vote ("up" | "down") — Vote direction
comment (string) — Optional comment
Response{ feedbackId, newConfidence }

Contributing Devices

Ask the AIEasiest

Tell the AI about your device and it will suggest hardware enhancements for your exercises automatically.

  1. Connect your device on the Connections page
  2. Ask the AI to create an exercise using your device
  3. The AI will include hardware enhancements based on your device capabilities
JSON DescriptorIntermediate

Create a JSON descriptor for your device following the schema. Paste it in the "Custom Device" tab on the Connections page.

  1. Fetch the schema from /api/devices/registry/schema
  2. Create a JSON file following the schema
  3. Open Connections → Add Device → Custom Device tab
  4. Paste your JSON and validate
Submit to RegistryIntermediate

Submit your device descriptor to the public registry so other users can benefit.

  1. Create and validate your descriptor (Custom Device tab)
  2. Click "Submit to Registry" to propose it
  3. The submission goes through validation and admin review
  4. Once approved, it appears in the Compatible Devices list for all users
Validate DescriptorsEasiest

Vote on pending device descriptors to help the community. Your votes affect the confidence score.

  1. Browse pending descriptors on the Connections page
  2. Review the descriptor details and capabilities
  3. Vote up if accurate, down if incorrect
  4. Optionally leave a comment with details

Example Descriptor

{
  "id": "garmin-forerunner-965",
  "name": "Garmin Forerunner 965",
  "manufacturer": "Garmin",
  "category": "sensor",
  "capabilities": [
    "heart_rate_monitor",
    "gps_tracking",
    "cadence_tracking",
    "pace_tracking",
    "distance_tracking"
  ],
  "controllableParams": {},
  "reportedMetrics": {
    "heart_rate_bpm": { "unit": "bpm", "rate_hz": 1 },
    "cadence_spm": { "unit": "spm", "rate_hz": 1 },
    "pace_min_km": { "unit": "min/km", "rate_hz": 1 },
    "distance_km": { "unit": "km", "rate_hz": 1 }
  },
  "connection": {
    "discovery": ["ble"]
  },
  "notes": "GPS multisport watch with optical HR, running dynamics."
}

The Hardware API is open. Device descriptors include provenance tracking, contributor history, and confidence scores. No account required to browse the registry.