OddessyDOCUMENTATION
PLATFORM API Live

Oddessy Platform HTTP API

A documented contract for account, device, enrolment, telemetry, release, OTA and agent-token operations.

Last updated 27 July 2026 ยท Documentation version 2026.07
Machine-readable contract

Download the current OpenAPI 3.1.2 YAML or JSON. It includes device bootstrap, integration management, authenticated inbound IoT webhooks and signed outbound webhook destinations.

Base URL

https://platform.oddessy.io/api

Account and fleet

GET/api/accountCognito user
GET/api/devicesTenant devices
PATCH/api/devices/{deviceId}Name/location
POST/api/enrolmentsOne-time enrolment

Device protocol

POST/api/device/enrolToken exchange
POST/api/device/bootstrapSigned verified installer
POST/api/device/heartbeatTelemetry + OTA poll
Private camera snapshots

Edge 0.3.2 can use the heartbeat to request a five-minute, device-scoped upload for a new inference JPEG. Its exact size and SHA-256 are signed. After verification, authenticated GET /api/devices responses include a separate ten-minute viewing URL. The edge opens no inbound camera port.

Monitoring and model decisions

GET/api/monitorsRules + current state
POST/api/monitorsCreate threshold rule
PATCH/api/monitors/{monitorId}Update or pause
DELETE/api/monitors/{monitorId}Remove rule
GET/api/alertsActive + transition history
GET/api/determinationsRecent VLM/VLA outcomes
POST/api/determinationsRetain + evaluate outcome
Datadog-style state transitions

Device metrics and normalized model outcomes evaluate tenant-scoped warning and critical thresholds. The platform retains recovery transitions for 180 days and determinations for 90 days. Stable source event IDs prevent a repeated heartbeat from replaying the same decision.

IoT integrations

GET/api/integrationsTenant connections
POST/api/integrationsCreate + shown-once secret
PATCH/api/integrations/{integrationId}Update connection
DELETE/api/integrations/{integrationId}Remove connection
POST/api/integrations/{integrationId}/rotate-secretRotate shown-once secret
GET/api/integrations/{integrationId}/eventsRecent normalized events
GET/api/iot/devicesDiscovered endpoints
POST/api/webhooks/{integrationId}Generic signed JSON
POST/api/webhooks/{integrationId}/uplinkTTN uplink

Releases and agent access

GET/api/releasesApproved metadata
GET/api/download?key=...Signed download
POST/api/devices/{deviceId}/otaLinux OTA intent
GET/api/tokensAgent tokens
POST/api/tokensCreate shown-once token
DELETE/api/tokens/{tokenId}Revoke token

Public access request

POST/api/invite-requestsStructured platform request

Versioning

The current web API remains under /api while the public contract stabilises. Breaking contract changes will be introduced through a versioned path or documented deprecation window. MCP has its own negotiated protocol version.