Zelta/Documentation
GitHub

Check Update API

The check-update endpoint is called by devices to check for available firmware updates.

Endpoint

POST /functions/v1/check-update

Authentication

Include your API key in the request header:

X-API-Key: zk_live_xxxxxxxxxxxx

Or as Bearer token:

Authorization: Bearer zk_live_xxxxxxxxxxxx

Request Body

{
  "device_id": "device-001",
  "current_version": "1.0.0",
  "product_id": "uuid-optional",
  "hardware_id": "SENSOR_V2"
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | device_id | string | Yes | Unique device identifier | | current_version | string | Yes | Currently installed firmware version | | product_id | string | No | Product UUID (if known) | | hardware_id | string | No | Hardware identifier for product matching |

Response

No Update Available

{
  "update_available": false,
  "device_id": "uuid",
  "current_version": "1.0.0"
}

Update Available

{
  "update_available": true,
  "version": "1.1.0",
  "size": 245760,
  "sha256": "a1b2c3d4e5f6...",
  "signature": "MEUCIQDx...",
  "download_url": "https://storage.supabase.co/...",
  "release_notes": "Bug fixes and improvements",
  "device_id": "uuid",
  "current_version": "1.0.0",
  "firmware_id": "firmware-uuid"
}

| Field | Type | Description | |-------|------|-------------| | update_available | boolean | Whether an update is available | | version | string | New firmware version | | size | number | Firmware size in bytes | | sha256 | string | SHA-256 hash of firmware (hex) | | signature | string | ECDSA signature (Base64) | | download_url | string | Signed URL for download (valid 1 hour) | | release_notes | string | Optional release notes | | firmware_id | string | Firmware UUID for status reporting |

Error Response

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

| Code | HTTP Status | Description | |------|-------------|-------------| | MISSING_API_KEY | 401 | No API key provided | | INVALID_API_KEY | 401 | API key is invalid or revoked | | LIMIT_EXCEEDED | 429 | Monthly update check limit exceeded | | BANDWIDTH_LIMIT_EXCEEDED | 429 | Monthly bandwidth limit exceeded |

Example

cURL

curl -X POST \\
  https://your-project.supabase.co/functions/v1/check-update \\
  -H "Content-Type: application/json" \\
  -H "X-API-Key: zk_live_xxxxxxxxxxxx" \\
  -d '{
    "device_id": "device-001",
    "current_version": "1.0.0"
  }'

C (Embedded)

#include <zelta/zelta.h>

zelta_update_info_t update;
int ret = zelta_check_update(&update);

if (ret == ZELTA_UPDATE_AVAILABLE) {
    printf("Update to %s available\\n", update.version);
    printf("Size: %zu bytes\\n", update.size);
}

Device Auto-Registration

If the device doesn't exist in the database, it will be automatically registered on first check. The device will be:

  • Created with the provided device_id
  • Associated with the product (via product_id or hardware_id matching)
  • Set to "online" status
  • Recorded with current IP address

Rate Limiting

Update checks count against your monthly limit:

| Plan | Monthly Limit | |------|---------------| | Free | 50,000 | | Pro | 500,000 | | Enterprise | Unlimited |

When limit is exceeded, you'll receive a 429 response with code: "LIMIT_EXCEEDED".

Best Practices

  1. Check periodically: Don't check too frequently (every 1-24 hours is typical)
  2. Handle 429 errors: Back off exponentially when rate limited
  3. Cache responses: Don't re-download if version hasn't changed
  4. Use hardware_id: Enables automatic product matching for new devices