API Documentation

Home

CoachLINK REST API

REST API for CoachLINK timing system providing access to sessions, devices, timing results, and system status.

ℹī¸ Base URL
https://develop.coachlink.host/api/v1

Authentication

The API uses device credentials authentication. Each device has unique credentials that must be obtained from the CoachCLOUD portal.

Device Credentials Authentication

All API requests require device credentials in the request header:

X-Device-ID: your_device_id
X-Device-Secret: your_device_secret

Obtain your device credentials from the CoachCLOUD admin portal after device registration.

JWT Token (After Login)

After successful login, use the JWT token for subsequent requests:

Authorization: Bearer your_jwt_token

Tokens expire after 24 hours. Use the refresh token endpoint to obtain a new token.

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format:

400 Bad Request - Invalid input parameters
404 Not Found - Resource not found
409 Conflict - Resource already exists
500 Internal Server Error - Server error

Error Response Format

{
  "error": "string",
  "message": "string",
  "code": 400,
  "timestamp": "2024-02-13T18:12:00Z",
  "details": {}
}

Authentication Endpoints

POST /auth/login Device Credentials

Authenticate with device credentials and obtain JWT access token.

Request Headers

X-Device-ID: your_device_id
X-Device-Secret: your_device_secret

Request Body

{
  "email": "user@example.com",
  "password": "user_password"
}

Response 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}
POST /auth/logout Device Credentials

Invalidate the current JWT token and log out the user.

Request Headers

Authorization: Bearer your_jwt_token
X-Device-ID: your_device_id
X-Device-Secret: your_device_secret

Response 200 OK

{
  "success": true,
  "message": "Successfully logged out"
}
POST /auth/refresh Device Credentials

Obtain a new access token using a refresh token.

Request Headers

X-Device-ID: your_device_id
X-Device-Secret: your_device_secret

Request Body

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}

License Management Endpoints

GET /api/v1/admin/license Device Credentials

Retrieve current license information for the device.

Request Headers

X-Device-ID: your_device_id
X-Device-Secret: your_device_secret
Authorization: Bearer your_jwt_token

Response 200 OK

{
  "license_code": "XXXX-XXXX-XXXX-XXXX",
  "status": "active",
  "valid_until": "2025-12-31T23:59:59Z",
  "features": [
    "x2_decoder",
    "p3_decoder",
    "cloud_sync"
  ],
  "device_limit": 5,
  "devices_registered": 2
}
POST /api/v1/admin/license/activate Device Credentials

Activate or update the device license with a new license code.

Request Headers

X-Device-ID: your_device_id
X-Device-Secret: your_device_secret
Authorization: Bearer your_jwt_token

Request Body

{
  "license_code": "XXXX-XXXX-XXXX-XXXX"
}

Response 200 OK

{
  "success": true,
  "message": "License activated successfully",
  "license": {
    "license_code": "XXXX-XXXX-XXXX-XXXX",
    "status": "active",
    "valid_until": "2025-12-31T23:59:59Z",
    "features": [
      "x2_decoder",
      "p3_decoder",
      "cloud_sync"
    ]
  }
}

Device Status Endpoints

GET /api/v1/device/status Device Credentials

Get current device status including hardware info, connectivity, and system health.

Request Headers

X-Device-ID: your_device_id
X-Device-Secret: your_device_secret
Authorization: Bearer your_jwt_token

Response 200 OK

{
  "device_id": "device_123",
  "status": "online",
  "uptime_seconds": 3600,
  "version": "1.0.0",
  "hardware": {
    "cpu_usage": 45.2,
    "memory_usage": 62.8,
    "disk_usage": 35.1,
    "temperature": 42.5
  },
  "connectivity": {
    "internet": "connected",
    "cloud_sync": "active",
    "last_sync": "2024-02-13T18:10:00Z"
  },
  "decoders": {
    "total": 3,
    "active": 2,
    "connected": 2
  }
}

Commands & Data Endpoints

POST /api/v1/commands/audit Device Credentials

Execute audit commands on the timing system.

cURL Example

curl -X POST "http://localhost:8080/api/v1/commands/audit" \
  -H "x-api-key: your-api-key" \
  -H "x-api-secret: your-api-secret" \
  -H "Content-Type: application/json" \
  -d '{"commands": ["402", "20"]}'

Request Headers

x-api-key: your-api-key
x-api-secret: your-api-secret
Content-Type: application/json

Request Body

{
  "commands": ["402", "20"]
}

Response 200 OK

{
  "success": true,
  "results": [
    {
      "command": "402",
      "status": "executed",
      "timestamp": "2024-02-13T18:12:00Z"
    },
    {
      "command": "20",
      "status": "executed",
      "timestamp": "2024-02-13T18:12:00Z"
    }
  ]
}
POST /api/v1/timing/passings Device Credentials

Retrieve raw transponder passing data from Redis with optional filtering.

Request Headers

x-api-key: your-api-key
x-api-secret: your-api-secret
Content-Type: application/json

Request Body (Optional)

{
  "start_time_ms": 1707847920000,
  "end_time_ms": 1707934320000,
  "transponder_id": "12345678",
  "limit": 100
}

Response 200 OK

{
  "success": true,
  "passings": [
    {
      "transponderid": "12345678",
      "rtc_time": 1707847920000,
      "decoder_id": "x2_decoder_1",
      "signal_strength": 85,
      "battery_voltage": 3.2,
      "hits": 5,
      "loop_id": 1
    }
  ],
  "count": 1,
  "start_time_ms": 1707847920000,
  "end_time_ms": 1707934320000
}
POST /api/v1/timing/transponder-sessions Device Credentials

Retrieve transponder session history with first and last detection times.

Request Headers

x-api-key: your-api-key
x-api-secret: your-api-secret
Content-Type: application/json

Request Body (Optional)

{
  "start_time_ms": 1707847920000,
  "end_time_ms": 1707934320000,
  "hours": 24
}

Response 200 OK

{
  "success": true,
  "sessions": [
    {
      "transponderid": "HN-25178",
      "start_time": 1707847920000,
      "end_time": 1707934320000,
      "passing_count": 45
    }
  ],
  "count": 1,
  "start_time_ms": 1707847920000,
  "end_time_ms": 1707934320000
}
GET /api/v1/transponders/active Device Credentials

Get count of active transponders within a specified time window.

cURL Example

curl -X GET "http://localhost:8080/api/v1/transponders/active?minutes=30" \
  -H "x-api-key: your-api-key" \
  -H "x-api-secret: your-api-secret"

Request Headers

x-api-key: your-api-key
x-api-secret: your-api-secret

Query Parameters

minutes integer Time window in minutes (1-1440, default: 10)

Response 200 OK

{
  "active_transponders": 15,
  "time_window_minutes": 30,
  "timestamp": 1707847920000
}
GET /api/v1/system/metrics Device Credentials

Retrieve detailed system performance metrics including CPU, memory, disk, and network statistics.

Request Headers

x-api-key: your-api-key
x-api-secret: your-api-secret

Response 200 OK

{
  "cpu": {
    "usage_percent": 45.2,
    "cores": 8,
    "load_average": [1.5, 1.3, 1.2]
  },
  "memory": {
    "total_mb": 16384,
    "used_mb": 8192,
    "free_mb": 8192,
    "usage_percent": 50.0
  },
  "disk": {
    "total_gb": 500,
    "used_gb": 250,
    "free_gb": 250,
    "usage_percent": 50.0
  },
  "network": {
    "bytes_sent": 1048576000,
    "bytes_received": 2097152000
  },
  "uptime_seconds": 86400,
  "timestamp": 1707847920000
}