orbimon

API

Edge (Orbimon OS)

Ingest telemetry and read send interval configuration with a monitor token.

Orbimon OS on the Edge uses a monitor token (omb_mon_…) to send telemetry and read runtime configuration. These endpoints are not used by typical dashboard integrations.

Authentication

Authorization: Bearer omb_mon_…

GET /v1/edge/config

Returns ingest timing for the monitor's organization. Call this on Edge boot (and after ingest responses) so the device sends on the plan interval.

Response 200

{
  "send_interval_seconds": 60
}
FieldDescription
send_interval_secondsHow often the Edge should POST ingest for this organization (updateMonitorInSeconds on the org plan).

Errors

StatusMeaning
401Missing or invalid monitor token
404Monitor not found

POST /v1/ingest

Ingests Starlink telemetry from the Edge. The same send_interval_seconds field is included on success and on rate-limit responses so the device can adjust without calling /edge/config every time.

Success 200

{
  "ack": true,
  "ingested": 30,
  "send_interval_seconds": 60
}

Optional fields (events_ingested, speed_tests_ingested, obstruction_maps_ingested) are unchanged.

Rate limit 429

The API never uses 400 or 422 for ingest rate limits (the Edge dead-letters those status codes).

{
  "error": "Ingest rate limit exceeded. Try again in 12 seconds.",
  "code": "RATE_LIMITED",
  "retry_after": 12,
  "send_interval_seconds": 60
}
FieldDescription
codeAlways RATE_LIMITED for ingest throttling
retry_afterSeconds to wait before retrying ingest
send_interval_secondsOrg send interval (same as /edge/config)

The response includes a Retry-After header with the same value as retry_after.

Enforcement (server)

  • Per monitor: Up to ceil(send_interval_seconds / 30) * 3 ingest requests per window of send_interval_seconds (minimum 2), so a 30s cadence plus flush and obstruction uploads fit with backlog headroom. Failed requests after the limit check do not consume a slot. Limits count HTTP requests, not data points inside a batch.
  • Monthly org quotas (maxRequestsPerMonth) apply to read and render API usage only, not to ingest.
  • KV unavailable: Ingest limits fail open (request is allowed) with a structured server warning so telemetry is not dropped. Monitor creation uses a fail-closed limit check instead.

Payload shape, dish binding, and other ingest errors are documented in the API service (POST /api/v1/ingest handler comments) and are unchanged by plan limits.