Devices API

Endpoints for registering, listing, retrieving devices, and sending heartbeats.

List devices

GET /api/v1/devices

Returns devices for an organization with optional filters.

Query Parameters

Parameter	Type	Required	Description
org_id	string	Yes	Organization identifier
platform	string	No	Filter by platform
status	string	No	Filter by status
limit	integer	No	Maximum records to return (default 100, max 1000)
offset	integer	No	Records to skip (default 0)

Request

curl "https://api.octomil.com/api/v1/devices?org_id=org_demo&limit=20" \
  -H "Authorization: Bearer $OCTOMIL_API_KEY"

Response

{
  "devices": [
    {
      "id": "dev_abc123",
      "device_identifier": "iphone-001",
      "org_id": "org_demo",
      "platform": "ios",
      "status": "active",
      "last_seen_at": "2026-02-23T16:30:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

---

Retrieve a device

GET /api/v1/devices/{device_id}

Retrieves detailed information about a registered device, including platform, capabilities, status, and last heartbeat.

Parameters

Parameter	Type	Description
device_id	string	The user-provided device identifier

Request

curl https://api.octomil.com/api/v1/devices/laptop-001 \
  -H "Authorization: Bearer $OCTOMIL_API_KEY"

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "device_id": "laptop-001",
  "platform": "python",
  "capabilities": {
    "cpu": "4-core",
    "memory_gb": 8,
    "gpu": false
  },
  "status": "active",
  "last_heartbeat": "2025-07-01T12:05:00Z",
  "created_at": "2025-07-01T12:00:00Z"
}

---

Register a device

POST /api/v1/devices/register

Registers a new device with the orchestration server. The server generates a unique API key and returns it in the response. Store this key securely -- it cannot be retrieved again.

Returns 409 Conflict if a device with the same device_id already exists.

Parameters

Parameter	Type	Required	Description
device_id	string	Yes	Unique, user-chosen identifier (1-255 chars)
platform	string	No	python, ios, android, or edge. Default: python
capabilities	object	No	Free-form JSON describing device hardware

Request

curl -X POST https://api.octomil.com/api/v1/devices/register \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "laptop-001",
    "platform": "python",
    "capabilities": {"cpu": "4-core", "memory_gb": 8, "gpu": false}
  }'

Response (201 Created)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "device_id": "laptop-001",
  "api_key": "<returned-once-redacted>",
  "platform": "python",
  "status": "active",
  "created_at": "2025-07-01T12:00:00Z"
}

Store your API key securely

The API key is returned only once during device registration. It cannot be retrieved again.

---

Send a heartbeat

PUT /api/v1/devices/{device_id}/heartbeat

Updates the device heartbeat timestamp and optionally reports device metrics. The server may include instructions in the response, such as a pending training round.

Parameters

Path: device_id (string)

Body:

Parameter	Type	Description
status	string	Reported device status: active or inactive
metrics	object	Optional metrics snapshot (cpu_usage_percent, memory_usage_percent, battery_level, etc.)

Request

curl -X PUT https://api.octomil.com/api/v1/devices/laptop-001/heartbeat \
  -H "Authorization: Bearer $OCTOMIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "metrics": {"cpu_usage_percent": 42.5, "memory_usage_percent": 61.0, "battery_level": 85}
  }'

Response

{
  "status": "active",
  "last_heartbeat": "2025-07-01T12:10:00Z",
  "pending_round_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "message": "Training round 18 is awaiting your participation."
}

---

Errors

Status	Error	Description
400	bad_request	Invalid or missing request fields
401	unauthorized	Missing or invalid API key
404	not_found	Resource does not exist
409	conflict	Resource already exists or state conflict
429	rate_limited	Too many requests; check Retry-After
500	internal_error	Unexpected server error