Public API Reference

The Public API at api.siliconwit.io provides read access to your devices, telemetry, alerts, and account data. All endpoints require an API key.

Base URL: https://api.siliconwit.io/v1

Authentication

Include your API key as a Bearer token:

curl https://api.siliconwit.io/v1/devices \
  -H "Authorization: Bearer swk_your_key_here"

Devices

List Devices

GET /v1/devices

Returns all your devices with pagination.

Query parameters:

Parameter	Type	Default	Description
limit	integer	50	Results per page (max 100)
offset	integer	0	Number of results to skip
status	string	-	Filter by status: active or paused

Example:

curl "https://api.siliconwit.io/v1/devices?status=active&limit=10" \
  -H "Authorization: Bearer swk_your_key"

Response:

{
  "data": [
    {
      "id": "dev_a1b2c3d4",
      "name": "Temperature Sensor",
      "type": "sensor",
      "description": "Office temperature monitor",
      "status": "active",
      "settings": {},
      "last_seen": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 10,
    "offset": 0
  }
}

Get Device

GET /v1/devices/:id

Returns a single device by ID.

Example:

curl https://api.siliconwit.io/v1/devices/dev_a1b2c3d4 \
  -H "Authorization: Bearer swk_your_key"

Response:

{
  "data": {
    "id": "dev_a1b2c3d4",
    "name": "Temperature Sensor",
    "type": "sensor",
    "description": "Office temperature monitor",
    "status": "active",
    "settings": {},
    "last_seen": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Get Latest Telemetry

GET /v1/devices/:id/telemetry/latest

Returns the most recent telemetry reading for a device.

Example:

curl https://api.siliconwit.io/v1/devices/dev_a1b2c3d4/telemetry/latest \
  -H "Authorization: Bearer swk_your_key"

Response:

{
  "data": {
    "id": "tel_xyz789",
    "time": "2025-01-15T10:30:00Z",
    "data": {
      "temperature": 25.5,
      "humidity": 60
    }
  }
}

Returns {"data": null} if the device has no telemetry data.

Get Telemetry History

GET /v1/devices/:id/telemetry

Returns historical telemetry data within a time range.

Query parameters:

Parameter	Type	Default	Description
range	string	24h	Time range: 1h, 6h, 24h, 7d, 30d
limit	integer	100	Max results (max 1000)

Example:

curl "https://api.siliconwit.io/v1/devices/dev_a1b2c3d4/telemetry?range=7d&limit=500" \
  -H "Authorization: Bearer swk_your_key"

Response:

{
  "data": [
    {
      "id": "tel_xyz789",
      "time": "2025-01-15T10:30:00Z",
      "data": {"temperature": 25.5, "humidity": 60}
    },
    {
      "id": "tel_xyz788",
      "time": "2025-01-15T10:15:00Z",
      "data": {"temperature": 25.3, "humidity": 61}
    }
  ],
  "query": {
    "device_id": "dev_a1b2c3d4",
    "requested_range": "7d",
    "range": "7d",
    "limit": 500,
    "data_retention_days": 30
  }
}

Alerts

List Alerts

GET /v1/alerts

Returns all your configured alerts.

Query parameters:

Parameter	Type	Default	Description
limit	integer	50	Results per page (max 100)
offset	integer	0	Number of results to skip

Example:

curl https://api.siliconwit.io/v1/alerts \
  -H "Authorization: Bearer swk_your_key"

Response:

{
  "data": [
    {
      "id": "alert_abc123",
      "device_id": "dev_a1b2c3d4",
      "name": "High Temperature",
      "condition": {"field": "temperature", "operator": ">", "value": 40},
      "actions": ["email"],
      "severity": "warning",
      "enabled": true,
      "cooldown": 300,
      "last_triggered": "2025-01-15T08:00:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-10T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 50,
    "offset": 0
  }
}

Get Alert

GET /v1/alerts/:id

Returns a single alert by ID.

Get Alert History

GET /v1/alerts/:id/history

Returns trigger events for an alert.

Query parameters:

Parameter	Type	Default	Description
limit	integer	50	Max results (max 100)

Response:

{
  "data": [
    {
      "id": "evt_001",
      "device_id": "dev_a1b2c3d4",
      "condition_value": 42.1,
      "severity": "warning",
      "acknowledged": false,
      "acknowledged_at": null,
      "triggered_at": "2025-01-15T08:00:00Z"
    }
  ]
}

Account

Get Usage

GET /v1/account/usage

Returns your current plan, device counts, and usage statistics.

Example:

curl https://api.siliconwit.io/v1/account/usage \
  -H "Authorization: Bearer swk_your_key"

Response:

{
  "data": {
    "plan": {
      "plan": "starter",
      "status": "active",
      "device_limit": 10,
      "data_retention_days": 30,
      "current_period_start": "2025-01-01T00:00:00Z",
      "current_period_end": "2025-02-01T00:00:00Z"
    },
    "devices": {
      "total": 5,
      "active": 4,
      "paused": 1,
      "limit": 10
    },
    "telemetry": {
      "data_points_24h": 1440
    },
    "alerts": {
      "total": 3,
      "active": 2
    }
  }
}

List API Keys

GET /v1/account/keys

Returns metadata for all your API keys (not the keys themselves).

Response:

{
  "data": [
    {
      "id": "key_abc123",
      "key_prefix": "swk_AbCd",
      "name": "Production Server",
      "last_used_at": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "revoked_at": null
    }
  ]
}

Error Responses

All errors return a JSON object with an error field:

{
  "error": "Device not found"
}

Common error codes:

Status	Meaning
400	Bad request (invalid parameters)
401	Missing or invalid API key
403	Account suspended or on free plan
404	Resource not found (or not owned by you)
500	Server error

Rate Limits

Rate limits depend on your subscription plan:

Plan	Per-minute	Daily
Starter	60	10,000
Business	300	50,000
Scale	600	100,000
Enterprise	Set by admin	Set by admin

Every response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Per-minute limit
X-RateLimit-Remaining	Remaining requests this minute
X-RateLimit-Daily-Limit	Daily limit
X-RateLimit-Daily-Remaining	Remaining requests today (resets at midnight UTC)

When you exceed a limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Data Retention

Telemetry queries are capped to your plan’s data retention window. For example, if your plan includes 30 days of retention and you request range=30d, the query succeeds. If you request a range beyond your retention, it is automatically capped to the maximum your plan allows.

The effective range is included in the query object of telemetry responses.

Next Steps

• API Keys - Create and manage keys
• API Overview - Device API vs Public API
• HTTP Data Ingestion - Send data from devices via HTTP