Admin API

The Admin API provides backend endpoints for managing measurement sessions, retrieving results, storing ground truth data, and accessing historical data. This API is designed for server-side integration and administrative tasks.

Note: The Admin API requires authentication with an API key. All requests must include the Authorization header with a valid bearer token.

Authentication

All API endpoints require authentication using Bearer tokens.

javascript
// Authentication header
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};

// Example authenticated request
const response = await fetch('https://api.vitals.io/admin/v1/vitals/results', {
  method: 'GET',
  headers: headers
});

Base URL

javascript
// Production
https://api.vitals.io/admin/v1

// Staging
https://api-staging.vitals.io/admin/v1

// Development
https://api-dev.vitals.io/admin/v1

Endpoints

GET /api/v1/vitals/results

Retrieve window results for a specific session or multiple sessions.

Request Parameters

  • sessionId (optional): Specific session ID
  • userId (optional): Filter by user ID
  • startDate (optional): Filter by start date (ISO8601)
  • endDate (optional): Filter by end date (ISO8601)
  • limit (optional): Maximum results (default: 100)
  • offset (optional): Pagination offset (default: 0)
javascript
// Example request
const response = await fetch(
  'https://api.vitals.io/admin/v1/vitals/results?userId=user-123&limit=50',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

Response

json
{
  "success": true,
  "data": [
    {
      "sessionId": "session-12345",
      "userId": "user-67890",
      "windowId": 1,
      "timestamp": "2024-02-23T10:30:45Z",
      "vitals": {
        "heartRate": 72.5,
        "hrv": 45.2,
        "respiratoryRate": 16.3,
        "stressIndex": 45,
        "spo2": 97.2,
        "bloodPressure": {
          "systolic": 118,
          "diastolic": 76
        },
        "bloodSugar": 95
      },
      "quality": {
        "signalQuality": 0.78,
        "usableFrameRatio": 0.85,
        "windowStatus": "complete"
      },
      "confidence": 0.75
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

POST /api/v1/vitals/ground-truth

Store ground truth measurements for calibration and validation.

Request Body

json
{
  "sessionId": "session-12345",
  "userId": "user-67890",
  "timestamp": "2024-02-23T10:30:00Z",
  "groundTruth": {
    "heartRate": {
      "value": 71,
      "device": "apple_watch",
      "deviceModel": "Series 8"
    },
    "bloodPressure": {
      "systolic": 120,
      "diastolic": 78,
      "device": "omron",
      "deviceModel": "Series 10"
    },
    "spo2": {
      "value": 98,
      "device": "pulse_oximeter",
      "deviceModel": "Masimo"
    },
    "bloodSugar": {
      "value": 92,
      "device": "glucometer",
      "deviceModel": "Accu-Chek",
      "fasting": true
    }
  },
  "notes": "Morning measurement after rest"
}
javascript
// Example request
const response = await fetch(
  'https://api.vitals.io/admin/v1/vitals/ground-truth',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      sessionId: 'session-12345',
      userId: 'user-67890',
      timestamp: '2024-02-23T10:30:00Z',
      groundTruth: {
        heartRate: {
          value: 71,
          device: 'apple_watch',
          deviceModel: 'Series 8'
        }
      }
    })
  }
);

const data = await response.json();

Response

json
{
  "success": true,
  "data": {
    "id": "gt-98765",
    "sessionId": "session-12345",
    "userId": "user-67890",
    "timestamp": "2024-02-23T10:30:00Z",
    "createdAt": "2024-02-23T10:35:00Z"
  }
}

GET /api/v1/sessions/{sessionId}

Retrieve detailed session data including all windows and measurements.

javascript
// Example request
const response = await fetch(
  'https://api.vitals.io/admin/v1/sessions/session-12345',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

Response

json
{
  "success": true,
  "data": {
    "sessionId": "session-12345",
    "userId": "user-67890",
    "startTime": "2024-02-23T10:30:00Z",
    "endTime": "2024-02-23T10:31:30Z",
    "duration": 90,
    "configuration": {
      "windowDuration": 45,
      "qualityThresholds": {
        "snr": { "minimum": 8 }
      }
    },
    "windows": [
      {
        "windowId": 1,
        "startTime": "2024-02-23T10:30:00Z",
        "endTime": "2024-02-23T10:30:45Z",
        "vitals": {
          "heartRate": 72.5,
          "hrv": 45.2
        },
        "quality": {
          "signalQuality": 0.78
        }
      }
    ],
    "environment": {
      "browser": "Chrome 120.0",
      "os": "Windows 11",
      "camera": "720p @ 30fps"
    }
  }
}

GET /api/v1/users/{userId}/history

Retrieve historical measurement data for a specific user.

Request Parameters

  • startDate (optional): Filter by start date
  • endDate (optional): Filter by end date
  • limit (optional): Maximum results (default: 100)
javascript
// Example request
const response = await fetch(
  'https://api.vitals.io/admin/v1/users/user-67890/history?limit=30',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

Response

json
{
  "success": true,
  "data": {
    "userId": "user-67890",
    "sessions": [
      {
        "sessionId": "session-12345",
        "timestamp": "2024-02-23T10:30:00Z",
        "duration": 90,
        "averagedVitals": {
          "heartRate": 73.2,
          "hrv": 46.8,
          "respiratoryRate": 16.5,
          "stressIndex": 47,
          "spo2": 97.0
        },
        "overallQuality": 0.78
      },
      {
        "sessionId": "session-12346",
        "timestamp": "2024-02-22T15:45:00Z",
        "duration": 120,
        "averagedVitals": {
          "heartRate": 75.1,
          "hrv": 42.3,
          "respiratoryRate": 17.2,
          "stressIndex": 52,
          "spo2": 96.5
        },
        "overallQuality": 0.82
      }
    ],
    "statistics": {
      "totalSessions": 25,
      "averageHeartRate": 74.5,
      "averageHRV": 44.2,
      "trends": {
        "heartRate": "stable",
        "hrv": "slightly_decreasing"
      }
    }
  }
}

GET /api/v1/analytics/aggregate

Retrieve aggregated analytics across multiple users or sessions.

Request Parameters

  • metric: Metric to aggregate (heartRate, hrv, etc.)
  • period: Time period (day, week, month, year)
  • groupBy: Group by (user, session, day, week)
  • startDate (optional): Filter by start date
  • endDate (optional): Filter by end date
javascript
// Example request
const response = await fetch(
  'https://api.vitals.io/admin/v1/analytics/aggregate?metric=heartRate&period=week&groupBy=day',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

Response

json
{
  "success": true,
  "data": {
    "metric": "heartRate",
    "period": "week",
    "groupBy": "day",
    "results": [
      {
        "date": "2024-02-19",
        "average": 73.5,
        "median": 73.0,
        "min": 68,
        "max": 82,
        "stdDev": 4.2,
        "count": 45
      },
      {
        "date": "2024-02-20",
        "average": 74.1,
        "median": 74.0,
        "min": 70,
        "max": 79,
        "stdDev": 3.8,
        "count": 52
      }
    ],
    "summary": {
      "overallAverage": 73.8,
      "trend": "stable",
      "totalMeasurements": 350
    }
  }
}

POST /api/v1/reports/generate

Generate PDF reports for specific sessions or users.

javascript
// Example request
const response = await fetch(
  'https://api.vitals.io/admin/v1/reports/generate',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      sessionId: 'session-12345',
      template: 'clinical-summary',
      includeCharts: true,
      includeRawData: false
    })
  }
);

const data = await response.json();

Response

json
{
  "success": true,
  "data": {
    "reportId": "report-98765",
    "sessionId": "session-12345",
    "status": "completed",
    "downloadUrl": "https://api.vitals.io/reports/report-98765.pdf",
    "expiresAt": "2024-02-24T10:30:00Z",
    "createdAt": "2024-02-23T10:35:00Z"
  }
}

DELETE /api/v1/sessions/{sessionId}

Delete a session and all associated data.

Warning: This operation is irreversible. Use with caution.
javascript
// Example request
const response = await fetch(
  'https://api.vitals.io/admin/v1/sessions/session-12345',
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

Response

json
{
  "success": true,
  "data": {
    "sessionId": "session-12345",
    "deleted": true,
    "deletedAt": "2024-02-23T10:40:00Z"
  }
}

Error Responses

All endpoints follow a consistent error response format.

json
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {
      "field": "Authorization"
    }
  }
}

Common Error Codes

  • INVALID_API_KEY: Invalid or expired API key
  • UNAUTHORIZED: User lacks permission for this operation
  • NOT_FOUND: Resource not found
  • INVALID_REQUEST: Invalid request parameters
  • RATE_LIMIT_EXCEEDED: Too many requests
  • SERVER_ERROR: Internal server error

Rate Limiting

API requests are rate limited to ensure fair usage.

  • Standard Tier: 1000 requests/minute
  • Pro Tier: 5000 requests/minute
  • Enterprise: Custom limits

SDK Integration Example

javascript
// Admin API client wrapper
class VitalsAdminAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://api.vitals.io/admin/v1';
  }
  
  async request(endpoint, options = {}) {
    const url = `${this.baseURL}${endpoint}`;
    const headers = {
      'Authorization': `Bearer ${this.apiKey}`,
      'Content-Type': 'application/json',
      ...options.headers
    };
    
    const response = await fetch(url, { ...options, headers });
    const data = await response.json();
    
    if (!response.ok) {
      throw new Error(data.error?.message || 'API request failed');
    }
    
    return data;
  }
  
  async getResults(filters = {}) {
    const params = new URLSearchParams(filters);
    return this.request(`/vitals/results?${params}`);
  }
  
  async storeGroundTruth(data) {
    return this.request('/vitals/ground-truth', {
      method: 'POST',
      body: JSON.stringify(data)
    });
  }
  
  async getSession(sessionId) {
    return this.request(`/sessions/${sessionId}`);
  }
  
  async getUserHistory(userId, options = {}) {
    const params = new URLSearchParams(options);
    return this.request(`/users/${userId}/history?${params}`);
  }
  
  async generateReport(options) {
    return this.request('/reports/generate', {
      method: 'POST',
      body: JSON.stringify(options)
    });
  }
}

// Usage
const admin = new VitalsAdminAPI('your-api-key');

const results = await admin.getResults({ userId: 'user-123' });
const session = await admin.getSession('session-456');
const report = await admin.generateReport({ sessionId: 'session-456' });

Next Steps