REST API Reference

The TrendGate REST API provides programmatic access to all platform features. This reference describes the available endpoints, request/response formats, and authentication requirements.

🔐 Authentication

All API requests require authentication using a Bearer token:

curl https://api.trendgate.ai/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting an API Key

1. Sign in to your TrendGate dashboard
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Copy your key immediately (it won't be shown again)

🌐 Base URL

https://api.trendgate.ai/v1

📝 Request Format

• All requests must include Content-Type: application/json
• Request bodies should be valid JSON
• Dates should be in ISO 8601 format
• All timestamps are in UTC

📊 Response Format

All responses follow a consistent format:

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2024-01-20T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid session date",
    "details": {
      "field": "date",
      "reason": "Date must be in the future"
    }
  },
  "meta": {
    "timestamp": "2024-01-20T10:30:00Z",
    "request_id": "req_abc123"
  }
}

🚀 Core Endpoints

Sessions

List Sessions

GET /sessions

Query parameters:

• instructor_id (string) - Filter by instructor
• member_id (string) - Filter by member
• status (enum) - scheduled, completed, cancelled
• date_from (ISO 8601) - Start date filter
• date_to (ISO 8601) - End date filter
• limit (integer) - Results per page (default: 20, max: 100)
• offset (integer) - Pagination offset

Example:

curl "https://api.trendgate.ai/v1/sessions?instructor_id=inst_123&status=scheduled" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Session

POST /sessions

Request body:

{
  "instructor_id": "inst_123",
  "member_id": "mem_456",
  "date": "2024-02-01T10:00:00Z",
  "duration_minutes": 30,
  "location": {
    "type": "pool",
    "pool_id": "pool_789"
  },
  "notes": "First lesson - water safety basics"
}

Get Session

GET /sessions/{session_id}

Update Session

PATCH /sessions/{session_id}

Request body (partial update):

{
  "date": "2024-02-01T11:00:00Z",
  "notes": "Rescheduled due to weather"
}

Cancel Session

POST /sessions/{session_id}/cancel

Request body:

{
  "reason": "Weather conditions",
  "notify_participants": true
}

Instructors

List Instructors

GET /instructors

Query parameters:

• search (string) - Search by name or email
• certification (string) - Filter by certification type
• available_date (ISO 8601) - Find available instructors
• location (object) - Filter by location (lat/lng/radius)

Get Instructor Profile

GET /instructors/{instructor_id}

Response includes:

• Profile information
• Certifications
• Availability schedule
• Rating and reviews
• Service areas

Update Instructor Profile

PATCH /instructors/{instructor_id}

Get Instructor Availability

GET /instructors/{instructor_id}/availability

Query parameters:

• date_from (ISO 8601) - Start date
• date_to (ISO 8601) - End date
• timezone (string) - Timezone for results (default: UTC)

Members

List Account Members

GET /accounts/{account_id}/members

Create Member

POST /accounts/{account_id}/members

Request body:

{
  "name": "Sarah Johnson",
  "date_of_birth": "2015-03-15",
  "swimming_level": "beginner",
  "medical_notes": "Mild asthma",
  "emergency_contact": {
    "name": "John Johnson",
    "phone": "+1234567890",
    "relationship": "parent"
  }
}

Update Member

PATCH /members/{member_id}

Get Member Progress

GET /members/{member_id}/progress

Bookings

Create Booking

POST /bookings

Request body:

{
  "instructor_id": "inst_123",
  "member_ids": ["mem_456", "mem_789"],
  "sessions": [
    {
      "date": "2024-02-01T10:00:00Z",
      "duration_minutes": 30
    },
    {
      "date": "2024-02-08T10:00:00Z",
      "duration_minutes": 30
    }
  ],
  "payment_method_id": "pm_abc123",
  "notes": "Package of 2 lessons"
}

Get Booking

GET /bookings/{booking_id}

List Account Bookings

GET /accounts/{account_id}/bookings

Payments

List Payment Methods

GET /accounts/{account_id}/payment-methods

Add Payment Method

POST /accounts/{account_id}/payment-methods

Request body:

{
  "stripe_payment_method_id": "pm_1234567890",
  "is_default": true
}

Process Payment

POST /payments

Request body:

{
  "booking_id": "book_123",
  "payment_method_id": "pm_abc123",
  "amount_cents": 5000,
  "currency": "USD"
}

Get Payment History

GET /accounts/{account_id}/payments

🔄 Pagination

List endpoints support cursor-based pagination:

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJvZmZzZXQiOjIwfQ==",
    "total": 145
  }
}

Use the cursor parameter for subsequent requests:

curl "https://api.trendgate.ai/v1/sessions?cursor=eyJvZmZzZXQiOjIwfQ==" \
  -H "Authorization: Bearer YOUR_API_KEY"

⚡ Rate Limiting

• Rate limit: 1000 requests per hour
• Burst limit: 100 requests per minute
• Headers included in responses:
  • X-RateLimit-Limit: Maximum requests per hour
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Unix timestamp when limit resets

🚨 Error Codes

Code	Description
AUTHENTICATION_ERROR	Invalid or missing API key
AUTHORIZATION_ERROR	Insufficient permissions
VALIDATION_ERROR	Invalid request parameters
NOT_FOUND	Resource not found
CONFLICT	Resource conflict (e.g., double booking)
RATE_LIMIT_EXCEEDED	Too many requests
SERVER_ERROR	Internal server error

🧪 Testing

Use our sandbox environment for testing:

https://api-sandbox.trendgate.ai/v1

Test API keys can be generated in your dashboard under Settings → API Keys → Sandbox Keys.

📚 SDKs

Official SDKs are available for:

• JavaScript/TypeScript
• Python
• Ruby
• Go

JavaScript Example

import { TrendGate } from "@trendgate/sdk";

const client = new TrendGate({
  apiKey: process.env.TRENDGATE_API_KEY,
});

// List upcoming sessions
const sessions = await client.sessions.list({
  status: "scheduled",
  dateFrom: new Date(),
});

// Create a booking
const booking = await client.bookings.create({
  instructorId: "inst_123",
  memberIds: ["mem_456"],
  sessions: [
    {
      date: new Date("2024-02-01T10:00:00Z"),
      durationMinutes: 30,
    },
  ],
});

🔗 Related Resources

• Authentication Guide
• Webhooks Reference
• tRPC API
• API Changelog