Areas and availability

Before creating bookings, discover the areas you can sell and read their availability. In 1Club a bookable padel court is an area; store the mapping between your courts and 1Club area ids on your side.

List areas

Returns the organization’s bookable areas. Filter by club or sport to get just the padel courts.

curl "https://api.1club.ai/v1/platform/areas?sport=padel" \
  -H "Authorization: Bearer 1club_sk_live_..."

Query parameters:

clubId (optional) - only return areas belonging to this club
sport (optional) - only return areas whose type lists this sport, for example padel

Response:

[
  {
    "id": 51,
    "name": "Court 1",
    "clubId": 8,
    "sports": ["padel"],
    "pricePerHour": 24,
    "maxConcurrentBookings": 1,
    "operatingHours": {
      "monday": [{ "open": "08:00", "close": "22:00" }],
      "tuesday": [{ "open": "08:00", "close": "22:00" }]
    }
  }
]

Use each area’s id as the areaId when creating a booking.

Area availability

Returns everything you need to render a court’s calendar for a window: the club timezone, operating hours, the intervals already taken (busy), and ready-made open slots with remaining capacity.

curl "https://api.1club.ai/v1/platform/areas/51/availability?from=2026-07-20T00:00:00Z&to=2026-07-21T00:00:00Z&slotMinutes=60" \
  -H "Authorization: Bearer 1club_sk_live_..."

Query parameters:

from (required) - window start, ISO date-time
to (required) - window end, ISO date-time, at most 31 days after from
slotMinutes (optional) - slot granularity: 15, 30, 60 (default), 90, or 120

Response:

{
  "areaId": 51,
  "from": "2026-07-20T00:00:00.000Z",
  "to": "2026-07-21T00:00:00.000Z",
  "timezone": "Europe/Madrid",
  "maxConcurrentBookings": 1,
  "version": "48213",
  "operatingHours": {
    "monday": { "enabled": true, "openTime": "08:00", "closeTime": "22:00" }
  },
  "busy": [
    { "startTime": "2026-07-20T17:00:00.000Z", "endTime": "2026-07-20T18:00:00.000Z" }
  ],
  "slots": [
    { "start": "2026-07-20T06:00:00.000Z", "end": "2026-07-20T07:00:00.000Z", "capacity": 1, "remaining": 1, "bookable": true },
    { "start": "2026-07-20T15:00:00.000Z", "end": "2026-07-20T16:00:00.000Z", "capacity": 1, "remaining": 0, "bookable": false }
  ]
}

timezone - the IANA timezone the operatingHours are expressed in. Operating hours are per-weekday local times; slots are already resolved to absolute UTC instants for you (DST included), so prefer slots over re-deriving from operatingHours.
slots - open slots computed from effective bookable hours (club ∩ area) minus busy, honouring maxConcurrentBookings. remaining is how many of capacity are still free; bookable is remaining > 0 and no hard block.
busy and operatingHours are still returned raw if you’d rather compute slots yourself. An area with maxConcurrentBookings greater than 1 can hold that many overlapping bookings before a slot is full.
version - a consistency token (the highest change sequence for this area). Compare it to the sequence on an availability webhook to know whether this read already reflects that change.

Conditional requests

The response sends an ETag built from version. Send it back as If-None-Match to get a cheap 304 Not Modified when nothing has changed — useful as a polling fallback where you don’t run webhooks.

curl "https://api.1club.ai/v1/platform/areas/51/availability?from=...&to=..." \
  -H "Authorization: Bearer 1club_sk_live_..." \
  -H 'If-None-Match: "48213-60"'

Club availability grid

Render a whole club’s calendar in one request instead of one call per court.

curl "https://api.1club.ai/v1/platform/availability?clubId=8&sport=padel&from=2026-07-20T00:00:00Z&to=2026-07-21T00:00:00Z&slotMinutes=60" \
  -H "Authorization: Bearer 1club_sk_live_..."

Query parameters: clubId (optional), sport (optional), from/to (required, ≤ 31 days), slotMinutes (optional).

{
  "clubId": 8,
  "timezone": "Europe/Madrid",
  "from": "2026-07-20T00:00:00.000Z",
  "to": "2026-07-21T00:00:00.000Z",
  "cursor": "48213",
  "areas": [
    {
      "areaId": 51,
      "name": "Court 1",
      "sports": ["padel"],
      "pricePerHour": 24,
      "maxConcurrentBookings": 1,
      "version": "48213",
      "operatingHours": { "monday": { "enabled": true, "openTime": "08:00", "closeTime": "22:00" } },
      "busy": [{ "startTime": "2026-07-20T17:00:00.000Z", "endTime": "2026-07-20T18:00:00.000Z" }],
      "slots": [{ "start": "2026-07-20T06:00:00.000Z", "end": "2026-07-20T07:00:00.000Z", "capacity": 1, "remaining": 1, "bookable": true }]
    }
  ]
}

The top-level cursor is the reconciliation cursor at read time — store it and pass it to the change feed to catch up later.

Availability change feed

Returns every availability change for your organization after a cursor, in order. Pair it with webhooks: webhooks push changes in near real time; this feed lets you catch up exactly after any missed delivery, so your calendar never drifts.

curl "https://api.1club.ai/v1/platform/availability/changes?since=48000&limit=100" \
  -H "Authorization: Bearer 1club_sk_live_..."

Query parameters: since (required cursor; 0 for the start of retention), limit (optional, default 100, max 500).

{
  "changes": [
    {
      "sequence": "48213",
      "clubId": 8,
      "areaId": 51,
      "from": "2026-07-20T17:00:00.000Z",
      "to": "2026-07-20T18:00:00.000Z",
      "reason": "booking.created",
      "occurredAt": "2026-07-20T16:32:04.115Z"
    }
  ],
  "cursor": "48213",
  "hasMore": false
}

To reconcile: pass your last stored cursor, apply each change by re-pulling /availability for the affected area and window, then store the new cursor. Keep paging while hasMore is true.

On first sync you have no cursor — do a full grid pull and start from the cursor it returns (starting from 0 for a live club replays its whole history). The feed serves a rolling history; if your cursor predates it after a long outage, re-baseline with a full grid pull. Some changes (e.g. area.updated) carry a coarse, wide from/to window rather than a single slot — re-pull the whole window. See the webhooks guide for the full reconciliation flow.

Availability is a snapshot. 1Club remains the source of truth: booking creation re-checks availability atomically, so a slot that was open a moment ago may be rejected if it was taken in between. Always handle a booking rejection gracefully — and use webhooks plus this feed to keep the snapshot fresh.

​List areas

​Area availability

​Conditional requests

​Club availability grid

​Availability change feed

List areas

Area availability

Conditional requests

Club availability grid

Availability change feed