Skip to content

API Reference

This document describes the REST API endpoints available in the NestEgress Service. All endpoints are accessed via the base URL https://api.space-dots-ingest-stg.click.

Interactive Documentation: For live testing and interactive exploration of the API, visit the Swagger UI at https://api.space-dots-ingest-stg.click/api-docs.

Authentication

Most endpoints require client credentials authentication. You'll need client credentials (client ID and secret) provided by your administrator.

Note: The following endpoints are public and do not require authentication.

Public Endpoints

Health Check

GET /health

Check if the service is running and healthy.

Response:

{
  "status": "authenticated",
  "timestamp": "2025-02-26T18:07:29.123Z",
  "message": "Authentication successful"
}

Time-Series Data Frames

GET /api/time-series-dataframe

Get paginated time-series data frames containing satellite telemetry data.

Query Parameters:

  • page (optional): Page number, default: 1
  • limit (optional): Items per page (max: 500), default: 50

Response:

{
  "data": [
    {
      "unixTimestampMs": 1704067200000,
      "datasetId": "mission-001",
      "frameNumber": 1,
      "positionEciXKm": 6871.0,
      "positionEciYKm": 0.0,
      "positionEciZKm": 0.0,
      "latitudeDeg": 0.0,
      "longitudeDeg": 0.0,
      "altitudeKm": 6871.0,
      "velocityEciVxKmS": 7.6,
      "velocityEciVyKmS": 0.0,
      "velocityEciVzKmS": 0.0,
      "omegaXRadS": 0.001,
      "omegaYRadS": 0.0,
      "omegaZRadS": 0.0,
      "quaternionQ0": 1.0,
      "quaternionQ1": 0.0,
      "quaternionQ2": 0.0,
      "quaternionQ3": 0.0,
      "tmSystemStatusTemperature": 25.5,
      "tmMax31865Data0Temperature": 23.5,
      "tmBmm350Data0MagneticField0": 25.3,
      "tmBmm350Data0MagneticField1": -12.7,
      "tmBmm350Data0MagneticField2": 42.1
    }
  ],
  "meta": {
    "total": 1000,
    "page": 1,
    "limit": 50,
    "totalPages": 20
  }
}

GET /api/time-series-dataframe/:id

Get a single time-series data frame by its frame number ID.

Path Parameters:

  • id: Frame number (integer)

Response: Returns a single TimeSeriesDataFrame object.

Sensor Data (Bulk Operations)

POST /api/sensor-data/bulk

Insert multiple sensor data records in a single request.

Request Body:

[
  {
    "sensorId": "temperature-sensor-001",
    "timestamp": 1704067200000,
    "value": 23.5,
    "unit": "C",
    "metadata": {
      "location": "payload-bay",
      "accuracy": 0.1
    }
  }
]

Response:

{
  "message": "Inserted 1 records",
  "ids": [1]
}

POST /api/sensor-data/clear

Clear all sensor data from the database. Use with caution.

Response:

{
  "message": "All sensor data cleared"
}

Protected Endpoints (Require Authentication)

The following endpoints require client credentials. Contact your administrator for access.

Sensor Data Operations

GET /api/sensor-data

Get all sensor data records.

GET /api/sensor-data/paginated

Get sensor data with pagination.

Query Parameters:

  • page (optional): Page number, default: 1
  • limit (optional): Items per page, default: 5

GET /api/sensor-data/count

Get count of sensor data records.

Query Parameters:

  • filterSensorName (optional): Filter by sensor ID

GET /api/sensor-data/sensor-names

Get unique sensor names in the database.

GET /api/sensor-data/range

Get sensor data within a specific time range.

Query Parameters:

  • startTime: Unix timestamp (milliseconds)
  • endTime: Unix timestamp (milliseconds)
  • limit (optional): Maximum records to return
  • offset (optional): Pagination offset

GET /api/sensor-data/timestamp-range

Get the minimum and maximum timestamps available.

GET /api/sensor-data/by-sensor/:sensorId

Get all data for a specific sensor.

Path Parameters:

  • sensorId: Sensor identifier

GET /api/sensor-data/:id

Get a specific sensor data record by ID.

Path Parameters:

  • id: Record ID (integer)

POST /api/sensor-data

Create a new sensor data record.

Request Body: Same as bulk operation but single object.

Data Types

TimeSeriesDataFrame

Contains comprehensive satellite telemetry data including:

  • Position and velocity in ECI coordinates
  • Geodetic coordinates (latitude, longitude, altitude)
  • Angular rates
  • Quaternion orientation
  • System status telemetry
  • Sensor data for various sensor types (temperature, magnetic field, acceleration, etc.)

SensorData

Individual sensor reading with:

  • sensorId: Identifier for the sensor device
  • timestamp: Unix timestamp in milliseconds
  • value: Numerical measurement value
  • unit: Measurement unit (e.g., "C", "Pa", "m/s²")
  • metadata: Additional JSON payload with sensor-specific information

Error Responses

{
  "statusCode": 401,
  "message": "Unauthorized",
  "timestamp": "2025-02-26T18:07:29.123Z",
  "path": "/api/sensor-data"
}

Common Status Codes:

  • 200: Success
  • 201: Resource created
  • 400: Bad request (invalid parameters)
  • 401: Unauthorized (missing or invalid credentials)
  • 403: Forbidden (insufficient permissions)
  • 404: Resource not found
  • 500: Internal server error

Rate Limiting

Rate limiting may be implemented based on client credentials for production usage.

CORS

Cross-Origin Resource Sharing is configured for production usage with appropriate origin restrictions.