GTSDB Logo GTSDB Documentation

GTSDB API Documentation

All payloads are in JSON format. Endpoints are either POST / OR TCP.

Write Operations

Write Single Value

Write a new data point for a specific sensor. Timestamp can be omitted to use the current server time. Timestamps are validated to be within the range 2000-2100.

Request Body

{
  "operation": "write",
  "key": "a_sensor1",
  "write": {
    "value": 3224242424333.3335
  }
}

Response Body

{
  "success": true
}

Batch Write

Write multiple data points across different keys in a single request. Maximum 10,000 points per batch.

Request Body

{
  "operation": "batch-write",
  "points": [
    {
      "key": "sensor1",
      "value": 42.5,
      "timestamp": 1717965210
    },
    {
      "key": "sensor1",
      "value": 43.1,
      "timestamp": 1717965211
    },
    {
      "key": "sensor2",
      "value": 99.9,
      "timestamp": 1717965210
    }
  ]
}

Response Body

{
  "success": true
}

Patch Operations

Patch Data Points

Update or insert multiple data points for a specific sensor using CSV or JSON array format. Supports both timestamp,value CSV lines and [{"timestamp":...,"value":...}] JSON arrays.

Request Body

{
  "operation": "data-patch",
  "key": "sensor1",
  "data": "1717965210,123.45\n1717965211,123.46\n1717965212,123.47"
}

Response Body

{
  "success": true
}

Read Operations

Read Data with Time Range and Downsampling

Read data for a specific sensor within a time range with downsampling. Supported aggregation types: avg (default), sum, min, max, first, last, count, median/p50, p95, p99. Timestamps are validated to be within the range 2000-2100.

Request Body

{
  "operation": "read",
  "key": "a_sensor1",
  "read": {
    "start_timestamp": 1717965210,
    "end_timestamp": 1717965211,
    "downsampling": 3,
    "aggregation": "avg"
  }
}

Response Body

{
  "success": true
}

Read Last X Records

Read the last X records for a specific sensor.

Request Body

{
  "operation": "read",
  "key": "a_sensor1",
  "Read": {
    "lastx": 1
  }
}

Response Body

{
  "success": true
}

Multi-Read Data with Time Range

Read data from multiple sensors within a time range with downsampling.

Request Body

{
  "operation": "multi-read",
  "keys": [
    "sensor1",
    "sensor2",
    "sensor3"
  ],
  "read": {
    "start_timestamp": 1717965210,
    "end_timestamp": 1717965211,
    "downsampling": 3
  }
}

Multi-Read Last X Records

Read the last X records from multiple sensors.

Request Body

{
  "operation": "multi-read",
  "keys": [
    "sensor1",
    "sensor2",
    "sensor3"
  ],
  "read": {
    "lastx": 1
  }
}

Export Data

Export sensor data in CSV or JSON format. Supports time range filtering, last X records, and downsampling.

Request Body

{
  "operation": "export",
  "key": "sensor1",
  "export": {
    "format": "csv",
    "start_timestamp": 1717965210,
    "end_timestamp": 1717965211
  }
}

Response Body

{
  "success": true
}

Subscribe Operations

Subscribe to a Key

Subscribe to updates for a specific sensor.

Request Body

{
  "operation": "subscribe",
  "key": "sensor1"
}

Response Body

{
  "success": true
}

Unsubscribe from a Key

Unsubscribe from updates for a specific sensor.

Request Body

{
  "operation": "unsubscribe",
  "key": "sensor1"
}

Response Body

{
  "success": true
}

Key Operations

Get All Keys

Retrieve a list of all sensor keys in the database.

Request Body

{
  "operation": "ids"
}

Response Body

{
  "success": true
}

Get All Keys with Data Point Count

Retrieve all sensor keys along with their data point counts.

Request Body

{
  "operation": "idswithcount"
}

Response Body

{
  "success": true
}

Initialize a New Key

Initialize a new sensor key in the database.

Request Body

{
  "operation": "initkey",
  "key": "new_sensor"
}

Response Body

{
  "success": true
}

Rename a Key

Rename an existing sensor key in the database. Key names are validated to prevent path traversal and unsafe characters.

Request Body

{
  "operation": "renamekey",
  "key": "old_sensor_name",
  "toKey": "new_sensor_name"
}

Response Body

{
  "success": true
}

Delete a Key

Delete a sensor key and all its data from the database.

Request Body

{
  "operation": "deletekey",
  "key": "sensor_to_delete"
}

Response Body

{
  "success": true
}

Reload a Key

Reload a sensor key from disk. Useful after manual file changes or recovery.

Request Body

{
  "operation": "reloadkey",
  "key": "sensor1"
}

Response Body

{
  "success": true
}

Delete Data Points

Delete data points by timestamp range and/or value condition. Timestamps are validated to be within the range 2000-2100.

Request Body

{
  "operation": "deleteDataPoint",
  "key": "sensor1",
  "payload": {
    "operator": ">",
    "value": 100,
    "timestampFrom": 1717965210,
    "timestampTo": 1717965300
  }
}

Response Body

{
  "success": true
}

Compact Key

Manually compact a key's WAL files to reclaim disk space by removing gaps from deleted data points. When compaction_compression is enabled in gtsdb.ini, compacted files are compressed using Facebook's Gorilla algorithm (~8x space reduction). The server also runs automatic background compaction every hour for files exceeding 100MB.

Request Body

{
  "operation": "compact",
  "key": "sensor1"
}

Response Body

{
  "success": true
}

Server & Monitoring

Server Info

Get detailed server information including version, uptime, memory usage, goroutine count, data directory, and configured listen addresses.

Request Body

{
  "operation": "serverinfo"
}

Response Body

{
  "success": true
}

Health Check

Simple health check endpoint. No authentication required. Returns service status and key count.

Request Body

Response Body

{
  "success": true
}

Prometheus Metrics

Prometheus-compatible metrics endpoint. No authentication required. Exposes gtsdb_key_count, gtsdb_data_points_total, gtsdb_uptime_seconds, gtsdb_goroutines, and Go runtime memory/GC metrics.

Request Body

Response Body

{
  "success": true
}

Other Operations

Flush All Data Points

Make sure all data points are written to disk.

Request Body

{
  "operation": "flush"
}

Response Body

{
  "success": true
}

Ping

It is not an operation, but a message sent from the server to the client to check if the connection is still alive. You can ignore this message. (hint: determine by empty data or "ping" message)

Request Body

Response Body

{
  "success": true
}