StrydeOS API Reference

Total Endpoints

Business Areas

Webhook Integrations

Auth Methods

🏥

Clinic Onboarding & Signup

How clinics join StrydeOS

When a clinic owner signs up, the system creates their account, sets up their workspace, and starts a 30-day free trial. Behind the scenes, this involves creating a secure login (Firebase Auth), a clinic record in the database, and a billing profile with Stripe.

Clinic owners can also invite their clinicians by email. Each invited clinician gets a password-reset link to set up their own login.

Who uses this: Clinic owners signing up, StrydeOS admin provisioning pilot clinics manually

/api/clinic/signup /api/admin/provision-clinic /api/clinic/check-go-live /api/clinic/resend-invite

👤

Clinician Management

Adding and managing clinicians

Clinic owners can add clinicians to their practice. The number of clinicians allowed depends on the billing tier: Solo (1), Studio (2–4), Clinic (5+). Extra seats can be purchased if you need more capacity within your tier.

Each clinician is linked to their PMS practitioner ID so their appointment data flows through automatically.

Who uses this: Clinic owners and admins managing their team

/api/clinicians/add /api/billing/seats

💳

Billing & Subscriptions

How payments work

StrydeOS uses Stripe for all billing. Clinics choose which modules they want (Intelligence, Pulse, Ava, or Full Stack bundle), pick a tier based on clinic size, and select monthly or annual billing (20% discount for annual).

When a clinic subscribes, Stripe tells StrydeOS which modules to activate. If a payment fails, the clinic is marked "past due" but access isn't revoked immediately — giving time to update payment details via the billing portal.

Ava (voice receptionist) has a one-time £250 setup fee in addition to the recurring subscription.

Who uses this: Clinic owners managing their subscription

/api/billing/checkout /api/billing/portal /api/billing/seats /api/billing/webhooks

🔗

Practice Management & HEP Integrations

Connecting your practice software

StrydeOS connects to your existing Practice Management System (PMS) to pull in appointment data, clinician rosters, and patient records. Supported systems: WriteUpp, Cliniko, Halaxy, Zanda (Power Diary). PPS and TM3 support coming soon.

You enter your PMS API key in Settings, test the connection, and StrydeOS starts syncing. Data refreshes automatically — WriteUpp pushes updates in real-time via webhooks; other systems sync on a schedule.

For clinics without API access, you can upload CSV exports of your appointment or patient data. StrydeOS auto-detects common formats or lets you create a custom column mapping.

Home Exercise Programme (HEP) data flows in from your connected HEP provider (Physitrack, Rehab My Patient, or Wibbi) — tracking programme assignments, adherence, and completion rates per patient.

Who uses this: Clinic owners connecting their PMS during onboarding, or uploading CSV exports

/api/pms/save-config /api/pms/test-connection /api/pms/disconnect /api/pms/sync /api/pms/import-csv /api/pms/import-csv/inbound /api/pms/csv-schema /api/pms/import-history /api/hep/save-config /api/hep/test-connection /api/hep/disconnect

📞

Ava — Voice Receptionist

How Ava handles calls and bookings

Ava is StrydeOS's AI voice receptionist, powered by ElevenLabs Conversational AI and Twilio telephony. When a patient calls, Ava answers, understands their request, and can book appointments directly into your PMS.

The booking flow: Patient calls → Ava converses → confirms booking details → n8n automation creates the appointment in your PMS → a copy is saved in StrydeOS for tracking. If the PMS write fails (e.g., the PMS is briefly offline), StrydeOS saves the booking locally and retries automatically.

Call data — duration, outcome (booked, cancelled, escalated, voicemail), transcripts, and sentiment — flows into the Receptionist dashboard so you can see how Ava is performing.

Who uses this: Automated — Ava handles calls; clinic owners view results in the dashboard

/api/ava/agent /api/bookings/create /api/bookings/retry-pms /api/webhooks/elevenlabs

💬

Patient Communications (Pulse)

Automated patient messaging

Pulse sends automated SMS and email messages to patients at the right moment. Six sequences run automatically:

Rebooking prompt — 72 hours after their last session
HEP reminder — before their next appointment
Review prompt — on discharge (includes NPS collection)
Reactivation (90 days) — for patients who haven't returned
Reactivation (180 days) — second nudge for lapsed patients
Insurance pre-auth — before the first session if flagged

When patients reply to a review prompt with an NPS score (0–10), StrydeOS automatically parses it and logs it to the Reputation dashboard. All messages are tracked: open rates, click rates, and whether the patient rebooked.

Who uses this: Automated — triggered by patient events; clinic owners view results in Pulse dashboard

/api/comms/send /api/n8n/callback /api/webhooks/writeupp

📊

Data Pipeline & Metrics

How your KPIs are calculated

Every day at 6:00 AM UTC, StrydeOS runs its data pipeline. This pulls the latest data from your PMS, syncs patient and appointment records, computes the seven KPI metrics (follow-up rate, HEP compliance, programme assignment, utilisation, DNA rate, revenue per session, NPS), and triggers any due communications.

WriteUpp clinics also get near real-time updates — when an appointment is created or changed in WriteUpp, a webhook fires and StrydeOS re-computes within seconds.

For new clinics, a one-time 90-day backfill pulls historical data so you have context from day one.

Who uses this: Runs automatically; clinic owners or superadmins can trigger manually

/api/pipeline/run /api/pipeline/backfill /api/metrics/compute /api/pms/sync

🔒

Compliance & Data Privacy

Patient data rights and compliance

StrydeOS supports GDPR and data privacy requirements out of the box:

Subject Access Requests (SAR) — patients can request a copy of all their data. Clinic owners export it as JSON with one click. All exports are audit-logged.
Data Deletion — patients can request deletion. The system marks records for removal with a 30-day grace period before purging.
BAA (Business Associate Agreement) — US clinics can accept a BAA clickthrough for HIPAA compliance.
Audit Trail — sensitive actions (data exports, config changes, SAR fulfilment) are logged with timestamps, user IDs, and IP addresses.

Who uses this: Clinic owners handling patient data requests

/api/compliance/sar /api/compliance/sar/[id]/export /api/compliance/sar/[id]/delete /api/compliance/baa

⚙️

Admin & Diagnostics

StrydeOS internal tools

These endpoints are used by the StrydeOS team (superadmins) to monitor system health, diagnose integration issues, and manage clinics.

The integration health dashboard shows sync success rates across all clinics — if a PMS connection is degrading, the team can see it before the clinic owner notices.

Who uses this: StrydeOS superadmins only

/api/admin/integration-health /api/debug/writeupp-probe

Endpoints

Token-Authed

Webhooks

Cron Jobs

🔑

Authentication Methods

Five authentication patterns

Method	Header	Used By
Firebase ID Token	Authorization: Bearer <idToken>	Dashboard users (24 endpoints)
Cron Secret	Authorization: Bearer <CRON_SECRET>	Vercel Cron (pipeline/run, metrics/compute, bookings/retry-pms)
Webhook Secret	x-webhook-secret: <secret>	WriteUpp, n8n, Ava bookings
Stripe Signature	stripe-signature: <sig>	Stripe billing webhooks
ElevenLabs Signature	x-elevenlabs-signature: <sig>	ElevenLabs voice webhooks

Roles: owner admin clinician superadmin — enforced via requireRole() in auth-guard.ts

🏥

Clinic Onboarding

▶

POST /api/clinic/signup

Self-serve clinic registration — creates auth user, clinic workspace, Stripe customer, and starts 30-day trial.

Public

Request Body

clinicName: string    ← required
email:      string    ← required
password:   string    ← required (min 8)
profession: string    ← optional
clinicSize: string    ← optional
country:    "uk"|"us"|"au" ← optional

Response (201)

{ uid, clinicId, email }

Errors

400 — Missing required fields
409 — Email already registered
500 — Internal server error

Notes

Idempotent — returns 409 if email exists (not a crash)
Creates: Firebase Auth user, users doc, clinics doc (with compliance config derived from country), Stripe customer
Trial: 30 days from signup, all modules accessible
Sets onboardingV2.stage: "signup_complete"

▶

POST /api/admin/provision-clinic

Superadmin manual clinic provisioning — used when onboarding pilot clinics or converting qualified leads.

Admin Secret superadmin

Request Body

clinicName:     string  ← required
ownerEmail:     string  ← required
ownerFirstName: string  ← optional
ownerLastName:  string  ← optional
pmsType:        string  ← optional
country:        "uk"|"us"|"au" ← opt
plan:           string  ← optional
notionLeadId:   string  ← optional

Headers

x-admin-secret: <STRYDE_ADMIN_SECRET>
Authorization:  Bearer <token> (opt)

Response (201)

{ uid, clinicId, email,
  passwordResetLink }

▶

POST /api/clinic/check-go-live

Checks if all admin/owner users have completed first login; promotes clinic from "onboarding" to "live" if ready.

Token any authenticated

Request

No body — clinicId from token

Response (200)

{ promoted: boolean,
  alreadyLive?: boolean,
  reason?: "no_admin_users"|"pending_logins" }

▶

POST /api/clinic/resend-invite

Resend clinician invite email (password-reset link via Resend or Firebase fallback).

Token owner / admin

Request Body

email:       string ← required
clinicianId: string ← optional

Response (200)

{ sent: true }
— or if Resend not configured —
{ sent: false, link, note }

👤

Clinician Management

▶

POST /api/clinicians/add

Add a clinician to the clinic. Enforces seat limits by billing tier (Solo: 1, Studio: 4, Clinic: unlimited).

Token owner / admin

Request Body

name:           string ← required
role:           string ← default "Physiotherapist"
pmsExternalId:  string ← optional (PMS practitioner ID)
physitrackId:   string ← optional

Response (201)

{ id: string,
  clinician: { id, name, role, pmsExternalId,
    physitrackId, active, avatar, createdAt } }

Errors

403 — Seat limit reached
  { error, currentCount, limit, canPurchaseSeat }

💳

Billing

▶

POST /api/billing/checkout

Create Stripe Checkout session for module subscriptions. Returns redirect URL.

Token owner / admin

Request Body

modules:        ["intelligence"|"pulse"|"ava"|"fullstack"][] ← required
tier:           "solo"|"studio"|"clinic" ← default "studio"
interval:       "month"|"year"          ← default "month"
includeAvaSetup: boolean               ← adds £250 one-time

Response (200)

{ url: string }  ← Stripe Checkout URL

▶

POST /api/billing/portal

Create Stripe Customer Portal session — manage subscription, update payment, view invoices.

Token owner / admin

Request

No body — clinicId from token

Response (200)

{ url: string }  ← Stripe Portal URL

▶

POST /api/billing/seats

Purchase additional clinician seats on existing subscription (1–10 at a time).

Token owner / admin

Request Body

quantity: number ← 1–10, default 1

Response (200)

{ success: true, extraSeats: number }

▶

POST /api/billing/webhooks

Stripe webhook — syncs subscription status to Firestore feature flags. Handles created, updated, deleted, and payment_failed events.

Stripe Signature

Events Handled

customer.subscription.created/updated — activates modules based on Stripe line items; syncs billing info, tier, seats
customer.subscription.deleted — deactivates all modules
invoice.payment_failed — marks billing as past_due (does NOT revoke access)

🔗

PMS & HEP Integrations

▶

POST /api/pms/save-config

Save PMS API credentials. Stores in server-only collection; updates clinic doc for display.

Tokenowner / admin

Request Body

provider: "writeupp"|"cliniko"|"halaxy"|"zanda" ← default "writeupp"
apiKey:   string ← required
baseUrl:  string ← optional (custom API URL)

Response (200)

{ ok: true }

▶

POST /api/pms/test-connection

Test PMS API credentials before saving — fires a lightweight probe to verify access.

Tokenowner / admin

Request Body

provider: string
apiKey:   string ← required

Response

200: { ok: true, resolvedBase? }
400: { ok: false, error }

▶

POST /api/pms/disconnect

Disconnect PMS integration — deletes config, resets clinic fields.

Tokenowner / admin

Request

No body

Response (200)

{ ok: true }

▶

POST /api/pms/sync

Sync appointments from PMS to Firestore (4-week window). Runs for all clinics or a specific one.

CronTokensuperadmin

Response (200)

{ results: [{ clinicId, ok, count?, error? }] }

▶

POST /api/pms/import-csv

Upload CSV for one-time appointment or patient import. Auto-detects schema or uses custom mapping.

Tokenowner / admin

Request (FormData)

file:     File (CSV) ← required
fileType: "appointments"|"patients" ← required
schemaId: string ← optional (auto-detect if omitted)

Response (200)

{ ok, count, imported, skipped, errors[] }

▶

POST /api/pms/import-csv/inbound

Inbound email CSV import — called by Mailgun/SendGrid when a CSV is emailed to import-{clinicId}@ingest.strydeos.com.

Webhook Secret

Request (FormData)

file:      File (CSV) ← required
fileType:  "appointments"|"patients"
recipient: string ← extracts clinicId from email
clinicId:  string ← explicit override

Headers

x-inbound-secret: <CSV_INBOUND_SECRET>

▶

POST /api/pms/csv-schema

Create/update custom CSV column mapping schema for non-standard PMS exports.

Tokenowner / admin

Request Body

name:       string  ← custom provider name
fileType:   "appointments"|"patients" ← required
fieldMap:   Record<csvHeader, canonicalField> ← required
dateFormat: "uk"|"us"|"iso" ← default "uk"
statusMap:  Record<source, target> ← appointments only

Canonical Fields

date, time, endDate, endTime,
patientId, patientFirst, patientLast,
patientEmail, patientPhone, patientDob,
practitioner, practitionerId,
type, status, notes, price, duration

▶

GET /api/pms/import-history

List past CSV imports for the clinic (paginated, most recent first).

Tokenowner / admin

Query Params

limit: number ← 1–100, default 30

Response (200)

{ ok, imports: [{ id, fileName, fileType,
  importedAt, count, status, errors }] }

▶

POST /api/hep/save-config

Save HEP integration credentials (API key for Physitrack, Rehab My Patient, or Wibbi).

Tokenowner / admin

Request Body

provider: "physitrack" | "rehab_my_patient" | "wibbi" ← required
apiKey:   string ← required

Response (200)

{ ok: true }

▶

POST /api/hep/test-connection

Test HEP API credentials before saving.

Tokenowner / admin

Response

200: { ok: true }
400: { ok: false, error }

▶

POST /api/hep/disconnect

Disconnect HEP integration — deletes config, resets clinic fields.

Tokenowner / admin

Response (200)

{ ok: true }

📞

Ava — Voice & Bookings

▶

POST /api/ava/agent

Create or update ElevenLabs Convai agent — builds system prompt from clinic config, stores agent ID.

Tokenauthenticated

Request

No body — config pulled from clinic doc

Response (200)

{ agent_id, message }

Agent Tools

book_appointment — create booking via PMS
check_availability — query open slots
update_booking — modify existing appointment
transfer_to_reception — warm transfer to clinic reception desk

▶

POST /api/ava/provision-number

Provisions a dedicated UK phone number for the clinic's Ava instance. Buys number, configures SIP trunk, creates ElevenLabs agent if needed.

Tokenowner / admin / superadmin

Request Body

locality:  string ← optional, e.g. "London" for local number

Response (200)

{ phone, agent_id, trunk_sid, message }

Conflict (409)

{ error: "Already provisioned", phone }

Notes

Rate-limited: 2 requests / minute (costs money)
Uses Firestore transaction to prevent double-purchase
Stores number, agent ID, and trunk SID atomically

▶

POST /api/ava/transfer

Webhook for ElevenLabs transfer_to_reception tool. Warm-transfers the live call to the clinic's reception number via Twilio.

HMAC-SHA256

Trigger

Called by ElevenLabs when Ava's
transfer_to_reception tool fires
(complaint, escalation, human help needed)

Response (200)

{ result: "Call is being transferred..." }
// or graceful fallback message if transfer fails

Flow

Verifies ElevenLabs webhook signature
Resolves clinic from agent_id
Redirects live Twilio call to reception number via TwiML
If transfer fails: returns fallback message so Ava takes caller details instead

▶

POST /api/ava/transfer-twiml

TwiML endpoint for warm transfer. Plays comfort message, dials reception with 30s timeout, handles no-answer fallback.

Twilio Signature

TwiML Flow

Say: "One moment — I'm connecting you now."
Dial: Reception number (from Firestore, never from query params — toll fraud prevention)
Timeout: 30 seconds → status callback

▶

POST /api/ava/transfer-twiml/status

Dial status callback — handles no-answer/busy/failed after transfer attempt. Apologises and promises callback.

Twilio Signature

Dial Outcomes

completed / answered: Empty TwiML (call connected successfully)
busy / no-answer / failed: "The team aren't available — someone will call you back."

▶

POST /api/bookings/create

Create booking from Ava voice call. Writes to PMS + mirrors in Firestore. Supports partial success (PMS fails, local succeeds).

Webhook Secret

Request Body

clinicId:            string ← required
patientFirstName:     string ← required
patientLastName:      string ← required
patientPhone:         string ← required (E.164)
clinicianExternalId:  string ← required
dateTime:             string ← required (ISO 8601)
patientEmail:         string ← optional
durationMinutes:      number ← default 45
appointmentType:      string ← optional
notes:                string ← optional
callId:               string ← ElevenLabs call ID
idempotencyKey:       string ← dedup key

Response (200)

{ ok, appointmentId, pmsExternalId,
  patientExternalId }

Partial Success (207)

{ ok, partial: true,
  pmsExternalId: null,
  warning: "PMS write failed..." }

▶

POST /api/bookings/retry-pms

Retry failed PMS write-backs for Ava bookings. Cron job — finds all failed writes and re-attempts.

Cron

Response (200)

{ ok, retried, failed, skipped, results[] }

Notes

Skips appointments in the past
Max 10 retries per appointment
Audit-logged per attempt

▶

POST /api/webhooks/elevenlabs

ElevenLabs webhook — receives call_started, call_ended, call_analyzed events. Persists call data to Firestore.

HMAC-SHA256

Events

call_started — creates voiceInteractions doc (callId, callerPhone, startTimestamp)
call_ended — merges duration, recording URL, disconnection reason
call_analyzed — merges summary, sentiment, outcome, transcript, custom analysis

▶

POST /api/webhooks/elevenlabs

ElevenLabs webhook — stores call log with outcome heuristic from summary keywords.

Webhook

Outcome Mapping

Summary contains "book/appt"   → booked
Summary contains "cancel"       → follow_up_required
Summary contains "voicemail"    → voicemail
Summary contains "escalat"      → escalated
Summary contains "success"      → resolved

💬

Communications

▶

POST /api/comms/send

Send SMS (Twilio) or email (Resend) to patient and log to comms_log collection.

Tokenauthenticated

Request Body

clinicId:     string ← required
patientId:    string ← required
patientName:  string ← required
sequenceType: string ← required
channel:      "sms"|"email" ← required
to:           string ← required
body:         string ← required
subject:      string ← required for email
templateVars: Record ← optional

Sequence Types

hep_reminder
rebooking_prompt
pre_auth_collection
review_prompt
reactivation_90d
reactivation_180d

▶

POST /api/n8n/callback

n8n automation callback — handles outbound delivery status and inbound SMS replies. Auto-parses NPS scores from review_prompt replies.

Webhook Secret

Outbound Callback

clinicId, patientId, sequenceType,
channel, logId, executionId,
outcome: "booked"|"unsubscribed"|"no_action"
openedAt?, clickedAt?

Inbound Reply

type: "inbound_reply"
clinicId, fromPhone (E.164),
replyText, receivedAt?

NPS parsing: "8", "8/10", "eight" → 8
≥9 = promoter, 7-8 = passive, <7 = detractor

▶

POST /api/webhooks/writeupp

WriteUpp real-time webhook — triggers targeted mini-pipeline (sync → patients → compute → comms) on PMS events.

Webhook Secret

Headers

x-webhook-secret: <WRITEUPP_WEBHOOK_SECRET>
x-strydeos-clinic-id: ← optional direct clinic ID

Pipeline Stages Triggered

Stage 2: syncAppointments (4-week window)
Stage 3: syncPatients
Stage 5: computePatientFields
triggerCommsSequences

📊

Pipeline & Metrics

▶

GET POST /api/pipeline/run

Main pipeline entry point — runs full data sync + metrics computation + comms trigger. Daily cron at 06:00 UTC.

Cron (daily 06:00 UTC)Tokenowner / admin / superadmin

POST Body (manual trigger)

clinicId?: string ← optional (all clinics if omitted for superadmin)

Response (200)

{ ok, result } or { results: [...] }

▶

POST /api/pipeline/backfill

One-time 90-day historical backfill — runs full pipeline with 13-week lookback.

CronToken

POST Body

clinicId?: string

▶

POST /api/metrics/compute

Compute weekly KPI metrics (follow-up rate, HEP compliance, utilisation, DNA rate, revenue/session, NPS).

CronTokenowner / admin / superadmin

Request Body

clinicId?:  string ← optional (all clinics if omitted)
weeksBack?: number ← 1–12, default 6

Response (200)

{ clinicId, written } or { results: [...] }

🔒

Compliance & Privacy

▶

POST GET /api/compliance/sar

Create or list Subject Access Requests. POST creates a new SAR; GET lists all SARs for the clinic.

Tokenowner / admin

POST Body

type:        "access"|"correction"|"deletion" ← required
requestedBy: string ← required
patientId?:  string
description: string ← required

GET Response (200)

{ requests: [{
  id, type, status, requestedBy,
  patientId, description,
  responseDeadline, ← 30 days from creation
  completedAt, createdAt, updatedAt
}] }

▶

POST /api/compliance/sar/[id]/export

Export all patient data for an access-type SAR — returns patient record, appointments, comms log, and outcome scores as JSON.

Tokenowner / admin

Response (200)

{ success, data: {
  exportedAt, patientId, clinicId,
  patient: { ... },
  appointments: [ ... ], ← up to 1000
  comms_log: [ ... ],    ← up to 1000
  outcome_scores: [ ... ]← up to 1000
} }

▶

POST /api/compliance/sar/[id]/delete

Mark patient data for deletion — 30-day grace period before purge. Only valid for deletion-type SARs.

Tokenowner / admin

Response (200)

{ success, message, gracePeriodEnd }

▶

POST /api/compliance/baa

Record BAA (Business Associate Agreement) acceptance — required for US clinics (HIPAA compliance).

Tokenowner / admin

Request Body

clinicId: string ← required

Response (200)

{ success, baaSignedAt }

⚙️

Admin & Diagnostics

▶

GET /api/admin/integration-health

Aggregated integration health across all clinics — sync success rates, latencies, error patterns over a configurable time window.

Tokensuperadmin

Query Params

days: number ← 1–90, default 30

Response (200)

{ clinics: [{
  clinicId, clinicName, pmsProvider,
  integrations: {
    [provider]: {
      totalSyncs, successfulSyncs,
      successRate, avgDurationMs,
      lastSuccessAt, lastFailureAt,
      lastErrors, status: "healthy"|"degraded"|"down"
    }
  }
}] }

▶

POST /api/debug/writeupp-probe

Diagnostic probe for WriteUpp field names — returns raw API response key shapes to debug mapping issues. Blocked in production.

Tokensuperadmindev/staging only

Request Body

clinicId: string ← required

Response (200)

{ ok, summary: {
  dateFrom, dateTo, totalReturned,
  keyShape: [{ keys, sample }],
  confirmedFields, parseError?
} }

▶

GET /api/status

Live platform health — pings 17 services in parallel using real status page APIs (Statuspage, Google Cloud Status) and direct HTTP probes. 60s cache. Public endpoint, CORS enabled.

PublicCORS *

Auth

None — public endpoint
CORS: Access-Control-Allow-Origin: *

Response (200)

{
  overall: "operational"|"degraded"|"down",
  checkedAt: ISO 8601,
  services: {
    [key]: {
      name, status: "operational"|"degraded"|"down",
      latency: number ← ms, -1 if unreachable,
      checkedAt, statusSource: "statuspage"|"ping",
      uptimeHistory: number[] ← 30 entries (1=up, 0.5=degraded, 0=down)
    }
  }
}

Services checked (17):
Statuspage API: Vercel, Stripe, Twilio, Sentry, ElevenLabs
Google Cloud:   Firebase / Firestore
HTTP ping:      StrydeOS, Resend, n8n, WriteUpp,
                Cliniko, Halaxy, Zanda, Physitrack, Heidi, Google Places