API Documentation

v1.0

Public REST API for searching ski schools, resorts, instructors, and related data. All endpoints are read-only and require no authentication.

OpenAPI Spec MCP Server Docs

Base URL:https://findaskischool.com/api/v1

Auth:None required

Format:JSON

Resources

Rate Limiting Webhooks MCP Server Docs OpenAPI Spec (JSON)

API Explorer

Test endpoints directly from your browser — no authentication required

Quick Examples

Endpoint

GET

Query Parameters

qstring

countrystring

resortstring

activitystring

levelstring

languagestring

school_typestring

certifiedstring

featuredstring

pageinteger

limitinteger

sortstring

Request URL

https://findaskischool.com/api/v1/schools?q=chamonix&limit=3

Schools Endpoints(2)

Response Format

All endpoints return a consistent JSON structure. Successful responses include a data field with the result, and paginated endpoints also include a meta object.

Success Response

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 24,
    "total_pages": 2
  }
}

Error Response

{
  "success": false,
  "error": {
    "message": "School not found",
    "status": 404
  }
}

Rate Limiting

All API endpoints are rate-limited to ensure fair usage and protect against abuse. Rate limits are applied per IP address using a sliding window algorithm.

Tier	Limit	Window	Applies To
`Public API`	100 req	1 minute	All `/api/v1/*` endpoints
`AI Features`	5 req	1 minute	AI matching, concierge, help center AI (unauthenticated)
`AI (Authenticated)`	15 req	1 minute	AI features for signed-in users
`MCP Server`	60 req	1 minute	MCP read-only tools at `/mcp`
`Form Submit`	3 req	1 minute	Contact forms, school submissions

Rate Limit Headers

Every API response includes standard rate limit headers:

X-RateLimit-Limit: 100        # Maximum requests allowed in window
X-RateLimit-Remaining: 87    # Requests remaining in current window
X-RateLimit-Reset: 42        # Seconds until window resets
Retry-After: 42              # (Only on 429) Seconds to wait before retrying

When rate limited, you will receive a 429 Too Many Requests response. Please implement exponential backoff in your integration. For higher limits, contact us at [email protected].

Webhooks

Coming Soon

Webhooks allow your application to receive real-time notifications when events occur on Find a Ski School. Configure a webhook endpoint to receive HTTP POST callbacks for the events you care about.

Stripe Payment Webhooks

Payment-related webhooks are powered by Stripe and delivered to /api/stripe/webhook. These are used internally for processing subscription payments, booking payments, and refunds.

Event	Description
`checkout.session.completed`	Fired when a customer completes a Stripe Checkout session (subscription or one-time payment)
`invoice.payment_succeeded`	Recurring subscription payment was successful
`invoice.payment_failed`	Subscription payment failed (triggers retry logic)
`customer.subscription.updated`	Subscription plan changed (upgrade/downgrade)
`customer.subscription.deleted`	Subscription cancelled or expired
`charge.refunded`	A payment charge was refunded

Planned Webhook Events

The following webhook events are planned for future API releases. Subscribe to receive notifications when these become available.

Event	Description	Status
`booking.created`	New booking created for your school	Planned
`booking.confirmed`	Booking confirmed by school or instructor	Planned
`booking.cancelled`	Booking cancelled by student or school	Planned
`review.created`	New review posted for your school	Planned
`school.updated`	School profile was updated	Planned
`instructor.added`	New instructor added to your school	Planned

Webhook Payload Format

When available, webhook payloads will follow this structure:

POST https://your-server.com/webhook
Content-Type: application/json
X-FASS-Signature: sha256=abc123...

{
  "event": "booking.created",
  "timestamp": "2026-03-30T12:00:00Z",
  "data": {
    "id": 42,
    "schoolId": 1,
    "studentName": "John Doe",
    "lessonType": "Private Ski Lesson",
    "date": "2026-04-15",
    "status": "pending"
  }
}

Interested in webhook access? Contact us at [email protected] to be notified when webhooks become available for your integration.

Find a Ski School API v1.0 · findaskischool.com