Skip to main content
Version: 1.0.0

Tracktics API

Tracktics API provides comprehensive endpoints for managing sports clubs, teams, players, tracking devices, and training sessions with real-time position data and event markers.

Getting Started​

The API follows RESTful principles and returns JSON responses. All timestamps use ISO 8601 format (RFC3339). Base URLs:

  • Staging: https://api.dp.dev.tracktics.systems
  • WebSocket: wss://ws.dp.dev.tracktics.systems

Authentication​

Most endpoints require JWT authentication via Firebase. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

WebSocket Authentication​

WebSocket connections support two authentication methods:

  1. Ticket-based (recommended for browsers):

    • First, obtain a one-time ticket by calling POST /ws/ticket with your Bearer token
    • Connect to the WebSocket using the ticket ID as a query parameter
    • Example: wss://ws.dp.dev.tracktics.systems?ticket=<ticket_id>&path=/position/clubs/{club_id}

  2. Direct Bearer token (not supported in browsers):

    • Include your Firebase JWT token directly in the Authorization header
    • Example: Authorization: Bearer <your-jwt-token>

Pagination​

List endpoints support cursor-based pagination for optimal performance:

Query Parameters:

  • limit (optional): Number of items per page. Maximum and default: 100
  • next_token (optional): Cursor token for retrieving the next page of results
  • order (optional): Sort order - desc (newest first, default) or asc (oldest first)
  • from (optional): Filter items created at or after this timestamp (RFC3339 format)
  • until (optional): Filter items created up until this timestamp (RFC3339 format)

Response Headers:

  • Pagination-Limit: The current page limit
  • Pagination-Next-Token: Cursor token for the next page (only present if more data available)

Example:

GET /clubs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/players?limit=50&order=desc

Response Headers:
Pagination-Limit: 50
Pagination-Next-Token: eyJsYXN0X2lkIjoiLi4uIn0=

Next page:
GET /clubs/.../players?limit=50&next_token=eyJsYXN0X2lkIjoiLi4uIn0=

Rate Limiting​

Rate limiting is not currently implemented but will be defined in future versions. We recommend implementing client-side rate limiting and exponential backoff for retry logic.

Error Handling​

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

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Common status codes:

  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 204 No Content - Request succeeded with no response body
  • 400 Bad Request - Invalid request parameters or body
  • 401 Unauthorized - Missing or invalid authentication token
  • 403 Forbidden - Insufficient permissions for the requested operation
  • 404 Not Found - Resource does not exist
  • 409 Conflict - Resource conflict (e.g., revision mismatch)
  • 500 Internal Server Error - Server-side error

Authentication​

Firebase JWT authentication token

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

JWT