Skip to content

SFDP API Reference

Overview

The Secure Fitness Data Pipeline (SFDP) API provides programmatic access to fitness data management, AI coaching, encryption, and marketplace features. This reference details all available endpoints, data structures, and integration examples.

Base URL

https://api.aidddmap.com/v1/sfdp

Authentication

All API requests require authentication using a Bearer token:

Authorization: Bearer <your_token>

Data Structures

FitnessDataPoint

interface FitnessDataPoint {
  timestamp: Date;
  type: string;
  value: number;
  unit: string;
  device: string;
  confidence?: number;
  metadata?: {
    activity?: string;
    intensity?: string;
    duration?: number;
    notes?: string;
  };
}

PredictiveInsight

interface PredictiveInsight {
  id: string;
  type:
    | "trend"
    | "anomaly"
    | "recommendation"
    | "goal"
    | "recovery"
    | "performance"
    | "milestone";
  confidence: number;
  description: string;
  metadata: {
    metric?: string;
    trend?: "increasing" | "decreasing" | "stable";
    impact?: "high" | "medium" | "low";
    timeframe?: string;
    recommendations?: string[];
  };
}

PerformanceMetrics

interface PerformanceMetrics {
  heartRateZones: {
    zone1: number; // Recovery (60-70% max HR)
    zone2: number; // Endurance (70-80% max HR)
    zone3: number; // Tempo (80-90% max HR)
    zone4: number; // Threshold (90-95% max HR)
    zone5: number; // Maximum (95-100% max HR)
  };
  recoveryScore: number;
  trainingLoad: number;
  fatigueLevel: number;
}

Endpoints

Data Management

Upload Fitness Data

POST /data
Content-Type: application/json

Upload new fitness data points to the pipeline.

Request Body:

{
  data: FitnessDataPoint[];
  encryptionMode?: "FHE" | "ZK" | "Basic";
  chunkSize?: number;
}

Response:

{
  success: boolean;
  processedCount: number;
  encryptedCount: number;
  errors?: string[];
}

Get Fitness Data

GET /data

Retrieve fitness data with optional filtering.

Query Parameters:

  • startDate: ISO date string
  • endDate: ISO date string
  • type: Data type filter
  • device: Device filter
  • limit: Maximum records (default: 1000)
  • offset: Pagination offset

Response:

{
  data: FitnessDataPoint[];
  total: number;
  hasMore: boolean;
}

AI Processing

Generate Insights

POST /insights/generate
Content-Type: application/json

Generate AI insights from fitness data.

Request Body:

{
  dataPoints: FitnessDataPoint[];
  types?: string[];  // Insight types to generate
  timeframe?: string;
}

Response:

{
  insights: PredictiveInsight[];
  processingTime: number;
}

Get Performance Metrics

GET /metrics

Retrieve calculated performance metrics.

Query Parameters:

  • startDate: ISO date string
  • endDate: ISO date string
  • metrics: Comma-separated list of desired metrics

Response:

{
  metrics: PerformanceMetrics;
  timestamp: string;
}

Device Management

Register Device

POST /devices
Content-Type: application/json

Register a new fitness device.

Request Body:

{
  type: string;
  name: string;
  capabilities: string[];
  encryptionMode?: "FHE" | "ZK" | "Basic";
}

Response:

{
  deviceId: string;
  status: "active" | "pending";
  encryptionEnabled: boolean;
}

Get Devices

GET /devices

List registered devices.

Response:

{
  devices: Array<{
    id: string;
    type: string;
    name: string;
    status: string;
    lastSync: string;
    encryptionMode: string;
  }>;
}

Data Monetization

Create Token

POST /marketplace/tokens
Content-Type: application/json

Create a new data token for marketplace listing.

Request Body:

{
  dataPoints: string[];  // IDs of data points to tokenize
  price: number;
  currency: string;
  accessRules: {
    duration: string;
    allowedUses: number;
    restrictions: string[];
  };
}

Response:

{
  tokenId: string;
  status: "active" | "pending";
  listingUrl: string;
}

List Tokens

GET /marketplace/tokens

List your data tokens.

Response:

{
  tokens: Array<{
    id: string;
    status: string;
    price: number;
    purchases: number;
    revenue: number;
  }>;
}

WebSocket API

Real-Time Data Stream

// Connect to WebSocket
const ws = new WebSocket("wss://api.aidddmap.com/v1/sfdp/stream");

// Listen for data updates
ws.onmessage = (event) => {
  const data: {
    type: "data" | "insight" | "metric";
    payload: FitnessDataPoint | PredictiveInsight | PerformanceMetrics;
  } = JSON.parse(event.data);
  // Handle the update
};

Error Handling

All endpoints may return the following error responses:

{
  error: {
    code: string;
    message: string;
    details?: any;
  };
  status: number;
}

Common error codes:

  • AUTH_ERROR: Authentication failed
  • INVALID_REQUEST: Invalid request parameters
  • ENCRYPTION_ERROR: Encryption operation failed
  • PROCESSING_ERROR: AI processing failed
  • DEVICE_ERROR: Device operation failed
  • RATE_LIMIT: Rate limit exceeded

Rate Limits

  • Standard tier: 100 requests per minute
  • Premium tier: 1000 requests per minute
  • Enterprise tier: Custom limits

Examples

Upload and Process Data

// Upload fitness data with FHE encryption
const response = await fetch("https://api.aidddmap.com/v1/sfdp/data", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    data: fitnessData,
    encryptionMode: "FHE",
    chunkSize: 100,
  }),
});

// Generate insights from the data
const insights = await fetch(
  "https://api.aidddmap.com/v1/sfdp/insights/generate",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      dataPoints: fitnessData,
      types: ["trend", "recommendation"],
    }),
  },
);

Monitor Real-Time Updates

const ws = new WebSocket("wss://api.aidddmap.com/v1/sfdp/stream");

ws.onmessage = (event) => {
  const { type, payload } = JSON.parse(event.data);

  switch (type) {
    case "data":
      updateFitnessData(payload as FitnessDataPoint);
      break;
    case "insight":
      handleNewInsight(payload as PredictiveInsight);
      break;
    case "metric":
      updateMetrics(payload as PerformanceMetrics);
      break;
  }
};

Tokenize and List Data

// Create a new data token
const token = await fetch(
  "https://api.aidddmap.com/v1/sfdp/marketplace/tokens",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      dataPoints: selectedDataPoints,
      price: 100,
      currency: "USD",
      accessRules: {
        duration: "30d",
        allowedUses: 1000,
        restrictions: ["no_resale", "research_only"],
      },
    }),
  },
);

SDK Support

Official SDKs are available for:

  • JavaScript/TypeScript
  • Python
  • Java
  • Go
  • Ruby

Visit our SDK Documentation for detailed integration guides.

Support

For API support: