Telemetry API Contract V1
Status
Section titled “Status”Draft.
Purpose
Section titled “Purpose”The Telemetry API allows authorized users and API clients to query normalized measurement data.
Requirements
Section titled “Requirements”The API must support:
- Tenant-scoped access.
- Organization-scoped access.
- Device filtering.
- Time range filtering.
- Measurement key filtering.
- Pagination or bounded result limits.
- Safe error responses.
- Correlation IDs.
- Authorization checks.
Query Constraints
Section titled “Query Constraints”Unbounded queries are not allowed.
Every telemetry query must include a time range or use a documented default range.
Large exports should use export jobs instead of synchronous API responses.
Security
Section titled “Security”The API must enforce:
- Authentication.
- Tenant authorization.
- Organization authorization.
- Device visibility.
- Export permissions where relevant.
Open Decisions
Section titled “Open Decisions”- Exact endpoint paths.
- Response shape.
- Pagination strategy.
- Maximum query range for synchronous requests.
- Rate limiting.