Skip to main content
This guide walks through the endpoints available today:
  1. Authenticate with your API key.
  2. List the venues you have access to.
  3. Fetch a venue’s profile.
  4. Fetch a venue’s treatment catalogue.
Real-time availability and booking creation are coming soon. Until they ship, this API is read-only (venues + treatments).

​
Prerequisites

  • An API key provisioned by the Saoma team (sk_live_…).
  • Node.js 20+ (examples below use fetch, available natively).
Export your key and the base URL once for the whole session: 
export SAOMA_API_KEY="sk_live_..."
export SAOMA_BASE="https://api.saoma.io/v1"

​
1. List the venues you have access to

curl "$SAOMA_BASE/venues" \
  -H "Authorization: Bearer $SAOMA_API_KEY"
Pick a venue and keep its id for the next steps. Cache this list — venue metadata changes rarely.

​
2. Fetch a venue’s profile

curl "$SAOMA_BASE/venues/$VENUE_ID" \
  -H "Authorization: Bearer $SAOMA_API_KEY"
The detail shape includes the venue’s opening_time / closing_time, slot_interval and booking-policy fields — useful to render the venue page.

​
3. Fetch the treatment catalogue

curl "$SAOMA_BASE/venues/$VENUE_ID/treatments" \
  -H "Authorization: Bearer $SAOMA_API_KEY"
Each treatment carries its variants (durations, guest counts, prices). Remember prices are decimal amounts in the treatment’s currency (e.g. 120.00 for 120 €), not cents.

​
Putting it together (Node.js)

const BASE = process.env.SAOMA_BASE;
const headers = { Authorization: `Bearer ${process.env.SAOMA_API_KEY}` };

// 1. List venues
const { data: venues } = await fetch(`${BASE}/venues`, { headers }).then((r) =>
  r.json()
);
const venue = venues[0];

// 2. Venue profile
const { data: profile } = await fetch(`${BASE}/venues/${venue.id}`, {
  headers,
}).then((r) => r.json());

// 3. Treatments
const { data: treatments } = await fetch(
  `${BASE}/venues/${venue.id}/treatments`,
  { headers }
).then((r) => r.json());

console.log(profile.name, "—", treatments.length, "treatments");

​
You’re done 🎉

Next steps:

Error handling

Learn the error format and retry strategy.

Rate limits

Understand quotas and caching best practices.