Skip to content

API.md

Latest commit

 

History

History
1112 lines (879 loc) · 19.3 KB

API.md

File metadata and controls

1112 lines (879 loc) · 19.3 KB

API Reference

Base URL

http://localhost:3000

All authenticated endpoints require the Authorization header:

curl -H "Authorization:Bearer YOUR_TOKEN_HERE" http://localhost:3000/auth/userinfo

Authentication Endpoints

GET /oauth/google/callback

Google OAuth2 callback handler (auto-redirect from Google)

Response: Redirects to UI with ?authToken=... or ?error=...

GET /auth/userinfo

Get current user information

Auth Required: Yes
Permissions: None (only authenticated user)

Response:

{
  "userId": 5,
  "email": "user@company.com",
  "roles": ["site_operator"],
  "created": 1672531200,
  "ttl": 1672531200
}

POST /auth/token

Regenerate authentication token

Auth Required: Yes
Permissions: None

Request Body:

{
  "ips": ["192.168.1.100"],
  "ttl": 7200,
  "pfx": "pub",
  "scope": "api",
  "roles": ["site_operator"]
}

Response:

{
  "token": "new_token_here"
}

GET /auth/permissions

Get current user's permissions

Auth Required: Yes

Response:

{
  "permissions": {
    "write": true,
    "caps": ["miner", "container", "actions"],
    "superAdmin": false,
    "permissions": [
      "miner:r", "miner:w",
      "container:r", "container:w",
      "actions:r", "actions:w"
    ]
  }
}

GET /auth/site

Get current site name

Auth Required: Yes

Response:

{
  "site": "production-site-01"
}

GET /auth/ext-data

Get extended worker data from ORKs

Auth Required: Yes
Query Parameters:

Parameter Type Required Description
type string Yes Data type to query
query JSON string No MongoDB-style query filter
overwriteCache boolean No Bypass cache

Example:

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/ext-data?type=miner&query=%7B%22status%22%3A%22online%22%7D"

User Management Endpoints

POST /auth/users

Create a new user

Auth Required: Yes
Permissions: users:w

Request Body:

{
  "data": {
    "email": "newuser@company.com",
    "role": "dev"
  }
}

Response:

{
  "success": true
}

Notes:

  • Super admin can create users of any role
  • Admin can create: site_operator, dev, read_only_user
  • Audit log entry created

GET /auth/users

List all users (filtered by role management permissions)

Auth Required: Yes
Permissions: users:w

Response:

{
  "users": [
    {
      "id": 2,
      "email": "operator@company.com",
      "role": "site_operator"
    },
    {
      "id": 3,
      "email": "viewer@company.com",
      "role": "read_only_user"
    }
  ]
}

Notes:

  • Super admin sees all users (except super admin itself)
  • Admin sees only users they can manage
  • Super admin user (ID=1) is never returned

PUT /auth/users

Update user details

Auth Required: Yes
Permissions: users:w

Request Body:

{
  "data": {
    "id": 3,
    "email": "viewer@company.com",
    "role": "dev"
  }
}

Response:

{
  "success": true
}

Restrictions:

  • Cannot update super admin (ID=1)
  • Can only update users you have permission to manage
  • Audit log entry created

POST /auth/users/delete

Delete a user

Auth Required: Yes
Permissions: users:w

Request Body:

{
  "data": {
    "id": 3
  }
}

Response:

{
  "success": true
}

Restrictions:

  • Cannot delete yourself
  • Cannot delete super admin
  • Can only delete users you have permission to manage
  • Audit log entry created

Global Data Endpoints

GET /auth/global/data

Query global data (production costs, container settings, site energy, features)

Auth Required: Yes
Query Parameters:

Parameter Type Required Description
type string Yes productionCosts, containerSettings, siteEnergy, features
gt integer No Greater than (range query)
gte integer No Greater than or equal
lt integer No Less than
lte integer No Less than or equal
limit integer No Maximum results
query JSON string No MongoDB-style query
fields JSON string No Field projection
sort JSON string No Sort specification
offset integer No Pagination offset
groupBy string No Group results by field
overwriteCache boolean No Bypass cache

Example (Container Settings):

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/global/data?type=containerSettings&query=%7B%22site%22%3A%22site-01%22%7D"

Response:

[
  {
    "site": "site-01",
    "model": "MicroBT-D40",
    "parameters": {
      "runningSpeed": 100,
      "startTemp": 25,
      "stopTemp": 85,
      "coolOilSetTemp": 40,
      "coolOilAlarmTemp": 75,
      "coolWaterAlarmTemp": 45
    },
    "thresholds": {
      "waterTemperature": {
        "criticalLow": 10,
        "alarmLow": 20,
        "normal": 35,
        "alarmHigh": 45,
        "criticalHigh": 50
      },
      "oilTemperature": {
        "criticalLow": 15,
        "alert": 30,
        "normal": 40,
        "alarm": 75,
        "criticalHigh": 85
      }
    }
  }
]

Example (Production Costs):

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/global/data?type=productionCosts&gte=202401&lte=202412"

Response:

[
  {
    "site": "site-01",
    "year": 2024,
    "month": 10,
    "energyCostsUSD": 1000.00,
    "operationalCostsUSD": 1000.00
  }
]

POST /auth/global/data

Set global data

Auth Required: Yes
Permissions: features:w
Query Parameters: type (required)

Request Body (Production Costs):

{
  "data": {
    "site": "site-01",
    "year": 2024,
    "month": 10,
    "energyCostsUSD": 1000.00,
    "operationalCostsUSD": 1000.00
  }
}

Request Body (Site Energy):

{
  "data": {
    "site": "site-01",
    "energyExclusionThresholdMwh": 100.5
  }
}

Request Body (Container Settings):

{
  "data": {
    "site": "site-01",
    "model": "MicroBT-D40",
    "parameters": {
      "runningSpeed": 100,
      "startTemp": 25,
      "stopTemp": 85,
      "coolOilAlarmTemp": 75,
      "coolWaterAlarmTemp": 45,
      "coolOilSetTemp": 40,
      "hotOilAlarmTemp": 80,
      "hotWaterAlarmTemp": 50,
      "exhaustFansRunTemp": 60,
      "alarmPressure": 150,
      "miner1CoolingConsumptionW": 500,
      "miner1MinPowerW": 3000,
      "miner2CoolingConsumptionW": 500,
      "miner2MinPowerW": 3000
    },
    "thresholds": {
      "waterTemperature": {
        "criticalLow": 10,
        "alarmLow": 20,
        "normal": 35,
        "alarmHigh": 45,
        "criticalHigh": 50
      },
      "oilTemperature": {
        "criticalLow": 15,
        "alert": 30,
        "normal": 40,
        "alarm": 75,
        "criticalHigh": 85
      },
      "tankPressure": {
        "criticalLow": 50,
        "alarmLow": 80,
        "normal": 100,
        "alarmHigh": 140,
        "criticalHigh": 160
      },
      "supplyLiquidPressure": {
        "criticalLow": 60,
        "alarmLow": 90,
        "normal": 110,
        "alarmHigh": 150,
        "criticalHigh": 170
      }
    }
  }
}

Response:

{
  "success": true
}

GET /auth/featureConfig

Get static feature configuration (from config)

Auth Required: Yes

Response:

{
  "comments": true,
  "inventory": false,
  "lvCabinetWidgets": true,
  "poolStats": true,
  "powerAvailable": true,
  "reporting": true,
  "settings": true,
  "isOneMinItvEnabled": false,
  "powerModeTimeline": false,
  "totalSystemConsumptionChart": false,
  "exportHistKpiDashboard": false,
  "showMinerConsumptionDashboard": false,
  "totalSystemConsumptionHeader": false,
  "energyProvision": true
}

GET /auth/features

Get dynamic feature flags (from storage)

Auth Required: Yes

Response:

{
  "experimentalDashboard": true,
  "advancedMetrics": false,
  "autoScaling": true
}

POST /auth/features

Set feature flags

Auth Required: Yes
Permissions: features:w

Request Body:

{
  "data": {
    "experimentalDashboard": true,
    "advancedMetrics": true,
    "autoScaling": false
  }
}

Response:

{
  "success": true
}

GET /auth/global-config

Get global configuration from all ORKs

Auth Required: Yes
Query Parameters: fields (optional JSON projection), overwriteCache

Response:

[
  {
    "isAutoSleepAllowed": true
  },
  {
    "isAutoSleepAllowed": false
  }
]

POST /auth/global-config

Set global configuration on all ORKs

Auth Required: Yes
Permissions: features:w

Request Body:

{
  "data": {
    "isAutoSleepAllowed": false
  }
}

Response:

[
  { "success": true },
  { "success": true }
]

Things Management Endpoints

GET /auth/list-things

List all things (miners, containers, sensors)

Auth Required: Yes
Query Parameters:

Parameter Type Description
query JSON string MongoDB-style query filter
status string Filter by status
offset integer Pagination offset
limit integer Results per page
fields JSON string Field projection
sort JSON string Sort specification
overwriteCache boolean Bypass cache

Example:

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/list-things?query=%7B%22status%22%3A%22online%22%7D&limit=50"

Response:

[
  [
    {
      "id": "miner-01",
      "type": "miner",
      "status": "online",
      "hashrate": 110000000000000,
      "temperature": 65,
      "power": 3250
    },
    {
      "id": "container-01",
      "type": "container",
      "status": "online",
      "oilTemp": 42,
      "waterTemp": 38
    }
  ]
]

GET /auth/list-racks

List racks by type

Auth Required: Yes
Query Parameters: type (required, e.g., "miner", "container"), overwriteCache

Example:

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/list-racks?type=miner"

Response:

[
  [
    "rack-01",
    "rack-02",
    "rack-03"
  ]
]

GET /auth/settings

Get thing settings

Auth Required: Yes
Query Parameters: rackId (required)

Response:

[
  {
    "success": {
      "rackId": "rack-01",
      "entries": {
        "targetTemp": 65,
        "fanSpeed": 80,
        "powerLimit": 3500
      }
    }
  }
]

PUT /auth/settings

Save thing settings

Auth Required: Yes
Permissions: Write required

Request Body:

{
  "rackId": "rack-01",
  "entries": {
    "targetTemp": 70,
    "fanSpeed": 85,
    "powerLimit": 3400
  }
}

Response:

[
  { "success": true }
]

POST /auth/thing/comment

Add comment to a thing

Auth Required: Yes
Permissions: comments:w

Request Body:

{
  "rackId": "rack-01",
  "thingId": "miner-01",
  "comment": "Replaced thermal paste and cleaned fans"
}

Response:

[
  { "success": true }
]

PUT /auth/thing/comment

Edit existing comment

Auth Required: Yes
Permissions: comments:w

Request Body:

{
  "rackId": "rack-01",    // Required
  "thingId": "miner-01",  // Required
  "comment": "Updated comment text",  // Required
  "id": "comment-123",    // Optional (but recommended for identification)
  "ts": 1672531200000     // Optional
}

Note: While id and ts are not schema-required, providing them helps identify which comment to update.

DELETE /auth/thing/comment

Delete comment

Auth Required: Yes
Permissions: comments:w

Request Body:

{
  "rackId": "rack-01",    // Required
  "thingId": "miner-01",  // Required
  "id": "comment-123",    // Optional (but recommended for identification)
  "ts": 1672531200000     // Optional
}

Note: While id and ts are not schema-required, providing them helps identify which comment to delete.

GET /auth/worker-config

Get worker configuration from ORKs

Auth Required: Yes
Query Parameters:

Parameter Type Required Description
type string Yes Worker type (e.g., "miner")
fields JSON string No Field projection
overwriteCache boolean No Bypass cache

Example:

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/worker-config?type=miner"

Response:

[
  {
    "type": "miner",
    "config": {
      "pollingInterval": 5000,
      "healthCheckTimeout": 3000,
      "maxRetries": 3
    }
  }
]

GET /auth/thing-config

Get thing configuration from ORKs

Auth Required: Yes
Query Parameters: type (required), requestType (required)

Actions & Voting Endpoints

GET /auth/actions

Query actions across all ORKs

Auth Required: Yes
Query Parameters:

Parameter Type Required Description
queries JSON string Yes Array of query objects
groupBatch boolean No Group by batch UID
overwriteCache boolean No Bypass cache

Example:

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/actions?queries=%5B%7B%22status%22%3A%22pending%22%7D%5D"

Response:

[
  {
    "actions": [
      {
        "id": 1,
        "type": "restart",
        "status": "pending",
        "voter": "operator@company.com",
        "created": 1672531200000
      }
    ]
  }
]

GET /auth/actions/batch

Get multiple actions by IDs

Auth Required: Yes
Query Parameters: ids (comma-separated, required), overwriteCache

Example:

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/actions/batch?ids=1,2,3"

GET /auth/actions/:type/:id

Get single action

Auth Required: Yes
Path Parameters: type (action type), id (action ID)

POST /auth/actions/voting

Submit an action for approval

Auth Required: Yes
Permissions: Write required

Request Body:

{
  "query": { "id": "miner-01" },
  "action": "restart",
  "params": ["graceful"]
}

Response:

[
  {
    "id": 123,
    "errors": []
  }
]

Notes:

  • Action includes voter email from authenticated user
  • Permissions are passed to ORKs for validation

POST /auth/actions/voting/batch

Submit batch of actions

Auth Required: Yes
Permissions: Write required

Request Body:

{
  "batchActionsPayload": [
    {
      "query": { "id": "miner-01" },
      "action": "restart",
      "params": []
    },
    {
      "query": { "id": "miner-02" },
      "action": "restart",
      "params": []
    }
  ],
  "batchActionUID": "batch-123-uuid"
}

Response:

[
  {
    "id": 124,
    "errors": []
  }
]

PUT /auth/actions/voting/:id/vote

Vote on a pending action

Auth Required: Yes
Permissions: Write required

Path Parameters: id (action ID)

Request Body:

{
  "approve": true
}

Response:

[
  { "success": true }
]

DELETE /auth/actions/voting/cancel

Cancel pending actions

Auth Required: Yes
Permissions: Write required
Query Parameters: ids (comma-separated action IDs)

Example:

curl -X DELETE -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/actions/voting/cancel?ids=1,2,3"

Response:

[
  { "success": true }
]

Logs & Monitoring Endpoints

GET /auth/tail-log

Get real-time tail logs from ORKs

Auth Required: Yes
Query Parameters:

Parameter Type Required Description
key string Yes Log key (e.g., "stat-5m", "stat-1h")
type string No Thing type filter
tag string No Tag filter
start integer No Start timestamp (ms)
end integer No End timestamp (ms)
offset integer No Pagination offset
limit integer No Results limit
fields JSON string No Field projection
aggrFields JSON string No Aggregation fields
aggrTimes JSON array No Aggregation time windows
mergeSitesData boolean No Merge data across sites
applyAggrCrossthg boolean No Apply cross-thing aggregation
overwriteCache boolean No Bypass cache

Example:

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/tail-log?key=stat-5m&limit=100"

Response:

[
  {
    "timestamp": 1672531200000,
    "thingId": "miner-01",
    "hashrate": 110000000000000,
    "temperature": 65,
    "power": 3250
  }
]

GET /auth/tail-log/multi

Get tail logs for multiple keys

Auth Required: Yes
Query Parameters:

Parameter Type Required Description
keys JSON array Yes Array of log keys
Other params - No Same as tail-log

Example:

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/tail-log/multi?keys=%5B%22stat-5m%22%2C%22stat-1h%22%5D"

GET /auth/tail-log/range-aggr

Get aggregated logs for custom time ranges

Auth Required: Yes
Query Parameters:

Parameter Type Required Description
keys JSON array Yes Array of query objects with type, startDate, endDate
overwriteCache boolean No Bypass cache

Example:

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/tail-log/range-aggr?keys=%5B%7B%22type%22%3A%22stat-5m%22%2C%22startDate%22%3A%221672531200000%22%2C%22endDate%22%3A%221672534800000%22%7D%5D"

GET /auth/history-log

Get historical logs from ORKs

Auth Required: Yes
Query Parameters:

Parameter Type Required Description
logType string Yes "alerts" or "info"
start integer No Start timestamp (ms)
end integer No End timestamp (ms)
startExcl integer No Start exclusive timestamp
endExcl integer No End exclusive timestamp
offset integer No Pagination offset
limit integer No Results limit
tag string No Tag filter
query JSON string No MongoDB-style query
fields JSON string No Field projection
overwriteCache boolean No Bypass cache

Example (Alerts):

curl -H "Authorization:Bearer TOKEN" \
  "http://localhost:3000/auth/history-log?logType=alerts&start=1672531200000&end=1672617600000"

Response:

[
  {
    "timestamp": 1672531200000,
    "level": "warning",
    "thingId": "miner-01",
    "message": "Temperature threshold exceeded",
    "details": {
      "temperature": 85,
      "threshold": 80
    }
  }
]