API Documentation – Married By Josh

Machine-readable catalog: /.well-known/api-catalog (RFC 9727)

Availability

Endpoint: GET https://marriedbyjosh.com/api/availability Content-Type: application/json OpenAPI spec: /.well-known/openapi/availability.json

Read-only feed of dates Josh is already booked on, over an 18-month horizon. Underlying source is Josh’s private Google Calendar, queried via Google’s FreeBusy API — so no event titles, attendees, or details are ever exposed, only busy time ranges.

Response shape

{
  "generated_at": "2026-04-24T11:37:24.679Z",
  "timezone": "Australia/Hobart",
  "horizon": { "from": "2026-04-24", "to": "2027-10-24" },
  "busy_dates": ["2026-04-26", "2026-05-03", "2026-07-11"],
  "busy_ranges": [
    { "start": "2026-04-26T11:30:00+10:00", "end": "2026-04-26T13:00:00+10:00" }
  ]
}
  • busy_dates — sorted list of calendar dates (in Australia/Hobart) with at least one existing commitment. Use this for simple “is this date free?” checks.
  • busy_ranges — raw ISO 8601 time ranges behind those dates, for agents that need more granularity.

Caveats

  • Absent dates are probably free but not guaranteed — confirm by sending an enquiry.
  • Cached at the edge for up to one hour; very recent calendar changes may take minutes to appear.
  • Response is CORS-open (Access-Control-Allow-Origin: *) — feel free to call it from a browser.

Errors

503 Service Unavailable is returned when the upstream calendar is down or authentication is failing. Retry with backoff.

Markdown for Agents

Every HTML page on this site also serves a clean Markdown version when requested with Accept: text/markdown (Cloudflare’s proposal). Try:

curl -H "Accept: text/markdown" https://marriedbyjosh.com/about

Contact

Questions, integration ideas, or found a bug in a response? Email josh@withers.co.