Skip to main content
POST

​
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

​
string
required
Experience name (max 120 chars).
​
integer
required
Length of one session in minutes (1..1440).
​
integer
required
Maximum attendees per session (1..10000).
​
object
required
​
object
required
​
string
Long-form description shown on the public booking page.
​
object
Defaults: booking_window: { min_hours_before: 1, max_days_ahead: 60 } and cancellation_policy: { refundable_until_hours_before: 24 }.
​
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.
​
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.
​
string
none, email, or email_and_phone. Defaults to email.
​
integer
Upper bound on seats per single booking (1..50). Defaults to 5.
​
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.
​
object
Same schema as Get Experience.
​
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.
​
string
Present alongside recurrence_required: true. Plain-English instructions on how to make the experience bookable.