Zelta/Documentation
GitHub

REST API Overview

The Zelta API enables devices to check for updates, download firmware, and report status.

Base URL

https://your-project.supabase.co/functions/v1

Authentication

All API requests require an API key. Include it in the request header:

X-API-Key: zk_live_xxxxxxxxxxxx

Or as a Bearer token:

Authorization: Bearer zk_live_xxxxxxxxxxxx

Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /check-update | Check for available firmware updates | | POST | /report-status | Report update status to server |

Rate Limits

API requests are rate-limited per device to prevent abuse:

| Endpoint | Limit | Window | |----------|-------|--------| | /check-update | 10 requests | per minute | | /report-status | 20 requests | per minute | | /provision-device | 5 requests | per minute (per IP) | | /device-heartbeat | 5 requests | per minute | | /log-events | 60 requests | per minute | | /device-command | 20 requests | per minute |

Rate Limit Response

When rate limited, the API returns HTTP 429:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Limit: 10/min",
  "limit": 10,
  "current": 11,
  "remaining": 0,
  "retry_after": "2025-01-15T10:31:00Z"
}

Response headers include:

  • X-RateLimit-Limit - Maximum requests per window
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - When the window resets (ISO 8601)
  • Retry-After - Seconds until retry

Rate Limit Abuse Detection

Devices that repeatedly exceed rate limits are flagged in the dashboard. Admins can:

  • View flagged devices in the Devices page (orange warning icon)
  • Clear the flag via the device dropdown menu
  • Monitor rate limit hits per device

See Rate Limits Configuration for more details.

Error Handling

All errors return JSON with an error field:

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

Common Error Codes

| Code | HTTP Status | Description | |------|-------------|-------------| | MISSING_API_KEY | 401 | No API key in request | | INVALID_API_KEY | 401 | API key invalid or revoked | | LIMIT_EXCEEDED | 429 | Rate limit exceeded | | INTERNAL_ERROR | 500 | Server error |

API Endpoints

SDKs

Instead of calling the API directly, use our embedded SDK: