Flight Sessions Endpoints

Access: org_type = Asset Owner, Member+. Access requires active membership (Owner/Pilot) for the asset. See access-control.md.

Live Telemetry: Real-time asset telemetry is ingested via WebSocket, not REST. See Live Telemetry (WebSocket) below.

Flight Sessions Endpoints Summary

Endpoint	Method	Operation Name	Description
`/flight-sessions`	POST	Initiate Flight Session	Start a new session (ad-hoc or linked to a plan)
`/flight-sessions`	GET	Get Flight Sessions	Get all flight sessions
`/flight-sessions/active`	GET	Get Active Session	Active session for an asset (`?asset_uuid=`)
`/flight-sessions/\{session_uuid\}`	GET	Get One Flight Session	Get specific flight session details
`/flight-sessions/\{session_uuid\}/end`	POST	End Flight Session	End an active flight session
`wss://…/flight-sessions/\{session_uuid\}/telemetry`	WS	Live Telemetry Ingest	Stream live telemetry frames from GCS to platform
`/flight-sessions/\{session_uuid\}/telemetry/records`	GET	Get Session Telemetry	Fetch stored telemetry frames for a session
`/flight-sessions/\{session_uuid\}/telemetry`	POST	Upload Offline Telemetry	Upload stored telemetry frames via REST

Initiate Flight Session

POST /flight-sessions

Initiate a new flight session and receive a telemetry ingestion token. Can be linked to an existing flight plan or used for ad-hoc flights. Supply started_at to backdate the session start time when initiating for a flight that began while offline.

Request Body:


{
  "asset_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
  "plan_uuid": "c1d2e3f4-1234-4abc-9000-aabbccddeeff",
  "asset_start_latitude": 28.6139,
  "asset_start_longitude": 77.209,
  "pilot_start_latitude": 28.61,
  "pilot_start_longitude": 77.205,
  "started_at": "2026-06-15T04:30:00Z"
}

Optional Header:

Idempotency-Key: \<opaque caller key\>: up to 255 characters. A retry with the same key and the same request returns the original session_uuid and session_token; the key is scoped to the authenticated user. Reusing a key with a different request returns 409 Conflict with error code IDEMPOTENCY_KEY_REUSED. The Windows adapter uses its local flight identity as this opaque key; it is not part of the telemetry frame or Core telemetry identity.

Field	Type	Description
`asset_uuid`	UUID	Required. Asset performing the flight
`plan_uuid`	UUID	Optional. Omit for ad-hoc flights
`asset_start_latitude` / `asset_start_longitude`	number	Optional. Asset takeoff coordinates
`pilot_start_latitude` / `pilot_start_longitude`	number	Optional. Pilot position at takeoff
`started_at`	ISO 8601 datetime	Optional. Actual flight start time. Omit for live flights (defaults to server time)

Responses:

201 Created:


{
  "message": "Flight session initiated successfully",
  "data": {
    "session_uuid": "f2d9a781-ef56-4233-a7fc-cb3e21a9cce4",
    "session_token": "secure-session-token-xyz"
  }
}

400 Bad Request:


{
  "error": "'asset_uuid' is required"
}

404 Not Found:


{
  "error": "Asset or flight plan not found"
}

409 Conflict:


{
  "error": "Asset is currently active in another session"
}

The same status is returned with error code IDEMPOTENCY_KEY_REUSED when an existing key is reused for a different request.

Get Flight Sessions

GET /flight-sessions

Get all flight sessions. Can be filtered by mission or flight plan.

Query Parameters:

Param	Type	Description
`mission_uuid`	string (optional)	Filter by a specific mission
`plan_uuid`	string (optional)	Filter by a specific flight plan
`page`	int (optional)	Page number (default: 1)
`limit`	int (optional)	Records per page (default: 25, max: 100)

Responses:

200 OK:


{
  "data": [
    {
      "session_uuid": "f2d9a781-ef56-4233-a7fc-cb3e21a9cce4",
      "session_udai_id": "UDAI-SES-2025",
      "plan_uuid": "c1d2e3f4-1234-4abc-9000-aabbccddeeff",
      "asset_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
      "user_uuid": "550e8400-0000-41d4-a716-446655440000",
      "session_token": "secure-session-token-xyz",
      "session_start_time": "2026-06-15T04:30:00Z",
      "session_end_time": "2026-06-15T05:15:00Z",
      "session_expiry": "2026-06-15T16:30:00Z",
      "asset_start_latitude": 28.6139,
      "asset_start_longitude": 77.209,
      "asset_end_latitude": 28.6201,
      "asset_end_longitude": 77.2145,
      "pilot_start_latitude": 28.61,
      "pilot_start_longitude": 77.205,
      "pilot_end_latitude": 28.61,
      "pilot_end_longitude": 77.205,
      "total_area": 15.75,
      "total_distance": 42.3,
      "total_endurance": 45,
      "timestamp": "2026-06-15T04:29:00Z"
    }
  ],
  "pagination": {
    "total_records": 1,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 25,
    "has_next": false,
    "has_previous": false
  }
}

Get Active Flight Session

GET /flight-sessions/active?asset_uuid={asset_uuid}

Returns the currently active (not yet ended) flight session for a given asset, if one exists. Used by the GCS adapter to resume an in-progress session after a restart without creating a duplicate.

Query Parameters:

Param	Type	Description
`asset_uuid`	UUID (required)	Asset to look up. Empty or missing UUID returns `400`.

Responses:

200 OK:


{
  "data": {
    "session_uuid": "f2d9a781-ef56-4233-a7fc-cb3e21a9cce4",
    "session_udai_id": "UDAI-SES-2025",
    "plan_uuid": "c1d2e3f4-1234-4abc-9000-aabbccddeeff",
    "asset_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
    "user_uuid": "550e8400-0000-41d4-a716-446655440000",
    "session_token": "secure-session-token-xyz",
    "session_start_time": "2026-06-15T04:30:00Z",
    "session_end_time": null,
    "session_expiry": "2026-06-15T16:30:00Z",
    "asset_start_latitude": 28.6139,
    "asset_start_longitude": 77.209,
    "asset_end_latitude": null,
    "asset_end_longitude": null,
    "pilot_start_latitude": 28.61,
    "pilot_start_longitude": 77.205,
    "pilot_end_latitude": null,
    "pilot_end_longitude": null,
    "total_area": null,
    "total_distance": null,
    "total_endurance": null,
    "timestamp": "2026-06-15T04:29:00Z"
  }
}

The payload shape matches Get One Flight Session. For an active session, session_end_time and end-position / totals fields are typically null until the session is ended.

400 Bad Request:


{
  "error": "Validation failed",
  "message": "asset_uuid is required"
}

404 Not Found:


{
  "error": "Not found",
  "message": "No active flight session found for this asset"
}

Get One Flight Session

GET /flight-sessions/{session_uuid}

Get specific flight session details.

Responses:

200 OK:


{
  "data": {
    "session_uuid": "f2d9a781-ef56-4233-a7fc-cb3e21a9cce4",
    "session_udai_id": "UDAI-SES-2025",
    "plan_uuid": "c1d2e3f4-1234-4abc-9000-aabbccddeeff",
    "asset_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
    "user_uuid": "550e8400-0000-41d4-a716-446655440000",
    "session_token": "secure-session-token-xyz",
    "session_start_time": "2026-06-15T04:30:00Z",
    "session_end_time": "2026-06-15T05:15:00Z",
    "session_expiry": "2026-06-15T16:30:00Z",
    "asset_start_latitude": 28.6139,
    "asset_start_longitude": 77.209,
    "asset_end_latitude": 28.6201,
    "asset_end_longitude": 77.2145,
    "pilot_start_latitude": 28.61,
    "pilot_start_longitude": 77.205,
    "pilot_end_latitude": 28.61,
    "pilot_end_longitude": 77.205,
    "total_area": 15.75,
    "total_distance": 42.3,
    "total_endurance": 45,
    "timestamp": "2026-06-15T04:29:00Z"
  }
}

404 Not Found:


{
  "error": "Flight session not found"
}

End Flight Session

POST /flight-sessions/{session_uuid}/end

End an active flight session and persist final metrics.

Responses:

200 OK:


{
  "message": "Flight session ended successfully",
  "data": {
    "session_uuid": "f2d9a781-ef56-4233-a7fc-cb3e21a9cce4",
    "session_token": "secure-session-token-xyz"
  }
}

404 Not Found:


{
  "error": "Flight session not found"
}

Live Telemetry (WebSocket)

Flight telemetry is NOT a REST endpoint. It is handled entirely via WebSocket.


WS wss://api.udai.live/v1/flight-sessions/{session_uuid}/telemetry?token={session_token}

The GCS authenticates using the session_token returned by POST /flight-sessions. It establishes a WebSocket on session start and pushes frames at ≤2 Hz.

Server connection acknowledgement:


{
  "type": "connection_ack"
}

Frame (GCS → Platform):


{
  "session_uuid": "f2d9a781-ef56-4233-a7fc-cb3e21a9cce4",
  "asset_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
  "asset_uin": "UINIF1315",
  "timestamp": "2026-06-16T07:32:15.000Z",
  "latitude": 28.6145,
  "longitude": 77.2093,
  "altitude_agl": 45.2,
  "absolute_altitude_m": 260.5,
  "heading": 270,
  "horizontal_speed": 12.4,
  "vertical_speed": 0.3,
  "climb_mps": 0.3,
  "groundspeed_mps": 12.4,
  "roll_deg": 2.1,
  "pitch_deg": -1.5,
  "yaw_deg": 270,
  "gps_fix_type": 3,
  "satellites_visible": 14,
  "battery_remaining_percent": 82,
  "battery_voltage_v": 22.4,
  "battery_current_a": 18.5,
  "is_armed": true,
  "is_in_air": true,
  "flight_mode": "AUTO",
  "status_text": "Flying"
}

Server acknowledgement per frame:


{
  "type": "telemetry_ack",
  "timestamp": "2026-06-16T07:32:15.100Z"
}

Telemetry frames are written to the telemetry_frames hypertable (TimescaleDB) as they arrive, and retrievable via Get Session Telemetry below. For live fan-out to airspace subscribers, see Airspace Awareness API - Live Telemetry Fan-out.

Get Session Telemetry

GET /flight-sessions/{session_uuid}/telemetry/records

Fetch stored telemetry frames for a session, ordered by timestamp ascending. Supports time-range filtering and pagination.

Query Parameters:

Param	Type	Description
`from`	ISO 8601 datetime (optional)	Return frames at or after this timestamp
`to`	ISO 8601 datetime (optional)	Return frames at or before this timestamp
`page`	int (optional)	Page number (default: 1)
`limit`	int (optional)	Frames per page (default: 500, max: 1000)

Responses:

200 OK:


{
  "data": [
    {
      "session_uuid": "f2d9a781-ef56-4233-a7fc-cb3e21a9cce4",
      "asset_uuid": "e7a6d7a1-ffb2-4d62-bd7a-034fb8a34a55",
      "asset_uin": "UDAI-AST-001",
      "timestamp": "2026-06-15T04:30:01Z",
      "latitude": 28.6145,
      "longitude": 77.2095,
      "altitude_agl": 45.2,
      "heading": 185,
      "horizontal_speed": 12.5,
      "battery_remaining_percent": 82,
      "is_armed": true,
      "is_in_air": true,
      "flight_mode": "AUTO"
    }
  ],
  "pagination": {
    "total_records": 2700,
    "total_pages": 6,
    "current_page": 1,
    "per_page": 500,
    "has_next": true,
    "has_previous": false
  }
}

400 Bad Request: Invalid page or limit value.
404 Not Found:


{
  "error": "Flight session not found"
}

Upload Offline Telemetry

POST /flight-sessions/{session_uuid}/telemetry

Upload a batch of stored telemetry frames for a flight session. Used when frames could not be sent live due to connectivity loss. Frames are sorted by timestamp server-side before insert. The requesting user must be the session owner.

Note: Session and asset identity (session_uuid, asset_uuid, asset_uin) are stamped server-side from the session record - the adapter does not need to include them in each frame. Session-level metrics (total_distance, total_endurance) are not recomputed from uploaded frames; raw archived frames are always complete and accurate.

Request Body:


{
  "frames": [
    {
      "timestamp": "2026-06-15T04:30:01Z",
      "latitude": 28.6145,
      "longitude": 77.2095,
      "altitude_agl": 45.2,
      "absolute_altitude_m": 260.5,
      "heading": 185,
      "horizontal_speed": 12.5,
      "vertical_speed": 0.5,
      "battery_voltage_v": 22.4,
      "battery_current_a": 18.5,
      "battery_remaining_percent": 82,
      "is_armed": true,
      "is_in_air": true,
      "flight_mode": "AUTO"
    }
  ]
}

Responses:

202 Accepted:


{
  "accepted": 47,
  "session_uuid": "f2d9a781-ef56-4233-a7fc-cb3e21a9cce4"
}

400 Bad Request:


{
  "error": "'frames' must not be empty"
}

403 Forbidden:


{
  "error": "You do not own this session"
}

404 Not Found:


{
  "error": "Flight session not found"
}