Public Sessions API Integration Guide

Oakline provides an API-key-protected, read-only sessions API for providers that want to list current public sessions on their own website. The external website controls the HTML and styling; Oakline remains the source for session availability and booking links.

For a public overview, see Forest School booking API.

Availability and Authentication

API access must be enabled for the tenant. Every request requires the tenant API key in the X-API-Key header.

Do not paste a real key into public documentation, support messages or source control. A key placed directly in browser JavaScript is visible to website visitors. Use a server-side request or proxy when the key must remain private.

Endpoints

List public session occurrences:

GET /api/v1/public/tenants/{tenant-slug}/sessions

Get one public occurrence:

GET /api/v1/public/tenants/{tenant-slug}/sessions/{occurrence-id}

The non-versioned /api/public/... aliases are also available. New integrations should use /api/v1/public/....

Safe Server-Side Request

Use placeholders in shared examples:

curl --request GET \
  'https://oakline.app/api/v1/public/tenants/demo/sessions?from=2026-09-01&limit=20' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_TENANT_API_KEY'

Store the real key in an environment variable or secret store on the provider's server.

Optional Query Parameters

from: start date or date expression accepted by the endpoint; defaults to the current date.
to: optional final date.
limit: result limit, capped by the endpoint.
cursor: opaque pagination cursor returned by the previous response.

Requests are rate limited to 60 per minute per IP.

List Response

The list endpoint returns:

occurrence and template IDs;
session title and public description;
start and end date/time values;
public location name;
price and tenant currency;
capacity, remaining places and full state;
age range;
public session image URL;
sorting value;
tenant-specific Oakline booking URL;
pagination details;
limited tenant presentation settings.

Example with fictional data:

{
  "data": [
    {
      "id": 4182,
      "template_id": 311,
      "title": "Acorn Explorers",
      "description_short": "A weekly woodland group...",
      "start_at": "2026-09-12T09:30:00",
      "end_at": "2026-09-12T12:00:00",
      "location_name": "Birch Meadow",
      "price": { "amount": 18, "currency": "GBP" },
      "capacity": { "total": 12, "remaining": 3, "is_full": false },
      "age_range": { "min": 5, "max": 11 },
      "image_url": "https://example.test/session.webp",
      "sort_order": 1,
      "booking_url": "https://demo.oakline.app/booking?session_id=4182"
    }
  ],
  "pagination": { "limit": 20, "has_more": false, "next_cursor": null }
}

Private Data Boundary

The public sessions controller does not return:

child or family records;
medical, SEND or consent information;
bookings or attendee names;
payment or balance information;
staff records;
private messages.

Render into Native HTML

The API returns JSON rather than a fixed iframe. Your server can request the data and your website can render its own accessible HTML cards or lists. Use each returned booking_url for the booking action so the family enters the correct Oakline tenant flow.

Escape all returned text before inserting it into HTML. Treat URLs as untrusted input and allow only expected https destinations.

Powered by Oakline Attribution

A provider or developer may include a “Powered by Oakline” link. The public sessions controller does not make attribution a technical requirement, so do not describe it as mandatory.

Errors

401: API key missing or invalid.
403: API access is not enabled for the tenant.
404: tenant or session not found.
429: rate limit exceeded.
500: server error.

Contact Oakline support if API enablement or the tenant slug needs to be confirmed.