Skip to main content
POST
/
experiences
curl -X POST \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sunset Yoga",
    "duration_minutes": 60,
    "default_capacity": 20,
    "location": { "type": "in_person", "city": "San Francisco" },
    "pricing": { "currency": "USD", "amount": 25 },
    "providers": ["sm_alice123"],
    "default_recurrence": {
      "provider_id": "sm_alice123",
      "timezone": "America/Los_Angeles",
      "start_date": "2026-08-01",
      "cadence": { "frequency": "weekly", "interval": 1, "days_of_week": [2, 4] },
      "end_condition": { "type": "never" },
      "session_templates": [
        { "start_time_of_day": "18:00", "capacity": 20, "provider_id": "sm_alice123" }
      ]
    }
  }' \
  "https://www.gomry.com/api/v1/experiences"

{
  "data": {
    "id": "AbCdEfGhIjKlMnOpQrSt",
    "name": "Sunset Yoga",
    "status": "active",
    "registration_status": "open",
    "duration_minutes": 60,
    "default_capacity": 20,
    "pricing": { "model": "per_session", "currency": "usd", "amount": 25 },
    "scheduling_rules": {
      "booking_window": { "min_hours_before": 1, "max_days_ahead": 60 },
      "cancellation_policy": { "refundable_until_hours_before": 24 }
    },
    "created_at": "2025-07-15T10:00:00.000Z",
    "updated_at": "2025-07-15T10:00:00.000Z"
  }
}

​
Create Experience

Creates a new experience (recurring offering — yoga class, workshop, coaching slot, …) in your organization.
An experience without a recurrence has no bookable time slots. The experience template (name, price, duration, location, …) is only half of what an attendee sees. The other half is a recurrence — the cadence (frequency, interval, days of week) plus session templates (start time, capacity, provider) that produces the actual bookable date/time grid.This endpoint helps you in two ways so you never ship an unbookable experience:
  1. Auto-default: if you supply at least one providers[] entry and omit default_recurrence, the API auto-attaches a starter recurrence (Mon–Fri 9am, UTC, never-ending, capacity = default_capacity). You can edit or replace it later via POST /v1/experiences/{id}/recurrences.
  2. Explicit default_recurrence field: pass the full recurrence body inline and we create both atomically.
If you omit default_recurrence and pass no providers, the response will include recurrence_required: true plus a hint string — the experience exists but won’t show slots until you call Create Recurrence yourself.
Requires the experiences:write scope.

​
Idempotency

Pass an Idempotency-Key header (max 255 chars) to make POST retries safe. The first request executes the create; subsequent requests with the same key within 24 hours replay the original response verbatim — including the original status code — and add an Idempotent-Replay: true response header. Keys are scoped per API key, so two integrations can use the same key value without collision. Two concurrent requests with the same key return 409 idempotent_request_in_progress to the second caller.

​
Request Body

​
name
string
required
Experience name (max 120 chars).
​
duration_minutes
integer
required
Length of one session in minutes (1..1440).
​
default_capacity
integer
required
Maximum attendees per session (1..10000).
​
location
object
required
​
pricing
object
required
​
description
string
Long-form description shown on the public booking page.
​
scheduling_rules
object
Defaults: booking_window: { min_hours_before: 1, max_days_ahead: 60 } and cancellation_policy: { refundable_until_hours_before: 24 }.
​
providers
string[]
List of SpaceMember IDs running this experience. Strongly recommended — supplying at least one provider triggers the auto-default recurrence behavior described in the warning above. The first ID in the array is used as the provider for the auto-default.
​
default_recurrence
object
Optional. When supplied, a recurrence is created in the same request and the auto-default is skipped. Same shape as the body of Create Recurrence: provider_id, timezone, start_date, cadence, end_condition, session_templates, and optional status. See that endpoint for field-level docs and validation rules.
​
required_contact_method
string
none, email, or email_and_phone. Defaults to email.
​
max_booking_quantity
integer
Upper bound on seats per single booking (1..50). Defaults to 5.
​
space_identifier
string
Space the experience belongs to. Defaults to GENERAL (the organization-wide bucket).

​
Response

Returns the created experience with 201 Created. When no recurrence could be attached (omitted default_recurrence and empty providers), the response also carries recurrence_required: true plus a hint string telling you how to fix it.
​
data
object
Same schema as Get Experience.
​
recurrence_required
boolean
Present and true only when the experience was created without a recurrence. Omitted from the response otherwise. Until you attach a recurrence, the experience will not show bookable slots.
​
hint
string
Present alongside recurrence_required: true. Plain-English instructions on how to make the experience bookable.
curl -X POST \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sunset Yoga",
    "duration_minutes": 60,
    "default_capacity": 20,
    "location": { "type": "in_person", "city": "San Francisco" },
    "pricing": { "currency": "USD", "amount": 25 },
    "providers": ["sm_alice123"],
    "default_recurrence": {
      "provider_id": "sm_alice123",
      "timezone": "America/Los_Angeles",
      "start_date": "2026-08-01",
      "cadence": { "frequency": "weekly", "interval": 1, "days_of_week": [2, 4] },
      "end_condition": { "type": "never" },
      "session_templates": [
        { "start_time_of_day": "18:00", "capacity": 20, "provider_id": "sm_alice123" }
      ]
    }
  }' \
  "https://www.gomry.com/api/v1/experiences"

{
  "data": {
    "id": "AbCdEfGhIjKlMnOpQrSt",
    "name": "Sunset Yoga",
    "status": "active",
    "registration_status": "open",
    "duration_minutes": 60,
    "default_capacity": 20,
    "pricing": { "model": "per_session", "currency": "usd", "amount": 25 },
    "scheduling_rules": {
      "booking_window": { "min_hours_before": 1, "max_days_ahead": 60 },
      "cancellation_policy": { "refundable_until_hours_before": 24 }
    },
    "created_at": "2025-07-15T10:00:00.000Z",
    "updated_at": "2025-07-15T10:00:00.000Z"
  }
}