Quick Reference¶

Codes, values, and cheat sheets

Appointment Type Codes¶

Code	Duration	Use Case
`B`	15 min	Follow-up, refill, quick question
`2`	30 min	New concern, checkup, symptom
`3`	45 min	Annual physical, comprehensive
`P`	15 min	Phone/virtual consultation

Mapping from Patient Speech¶

Patient Says	Maps To
"refill", "follow-up", "results"	B
"new problem", "checkup", "concern"	2
"physical", "annual", "comprehensive"	3
"phone call", "virtual", "telehealth"	P

Call Outcomes¶

Outcome	Description
`booked`	Appointment created
`rescheduled`	Appointment moved
`cancelled`	Appointment cancelled
`registered`	New patient registered
`waitlisted`	Added to waitlist
`transferred`	Transferred to staff
`abandoned`	Caller hung up
`error`	System error occurred

Call Intents¶

Intent	Description
`book`	Book new appointment
`reschedule`	Change existing appointment
`cancel`	Cancel appointment
`register`	New patient registration
`info`	Clinic information request
`other`	Other/unclear intent

Transfer Reasons¶

Reason	Triggers
`medical_question`	Symptom, medication, test result
`billing`	Payment, insurance, cost
`frustrated`	After 2 failed attempts
`registration_error`	Registration failed
`patient_request`	"Let me speak to someone"

Language Codes¶

Code	Language	Voice
`en`	English	Azure Clara (en-CA)
`zh`	Mandarin Chinese	Azure Xiaoxiao (zh-CN)

Day of Week¶

Value	Day
0	Sunday
1	Monday
2	Tuesday
3	Wednesday
4	Thursday
5	Friday
6	Saturday

Waitlist Status¶

Status	Description
`pending`	Awaiting contact
`contacted`	Staff reached out
`registered`	Now a patient
`cancelled`	Removed from list

User Roles¶

Role	Access
`vitara_admin`	Platform administrator - all clinics, all settings
`clinic_manager`	Single clinic - own clinic settings, preferences

HTTP Status Codes¶

Code	Meaning
200	Success
400	Bad request (invalid params)
401	Unauthorized (invalid API key)
404	Not found
429	Rate limited
500	Internal server error
503	Service unavailable

Error Codes¶

Code	Description
`PATIENT_NOT_FOUND`	Patient not in EMR
`APPOINTMENT_NOT_FOUND`	Appointment doesn't exist
`NO_AVAILABILITY`	No slots available
`INVALID_REQUEST`	Invalid parameters
`OSCAR_UNAVAILABLE`	EMR unreachable
`UNAUTHORIZED`	Invalid credentials
`RATE_LIMITED`	Too many requests
`INTERNAL_ERROR`	Server error

Docker Commands¶

# Start all services
docker compose up -d

# Stop all services
docker compose down

# View logs
docker compose logs -f

# Restart specific service
docker compose restart vitara-voice-agent

# Check health
docker compose ps

# Enter database
docker exec -it vitara-db psql -U vitara -d vitara

# Backup database
docker exec vitara-db pg_dump -U vitara vitara > backup.sql

API Endpoints Summary¶

Patient¶

Endpoint	Purpose
`POST /api/vapi/search-patient-by-phone`	Find by phone
`POST /api/vapi/search-patient`	Find by name
`POST /api/vapi/get-patient`	Get details

Clinic¶

Endpoint	Purpose
`POST /api/vapi/get-clinic-info`	Clinic settings
`POST /api/vapi/get-providers`	Provider list

Appointments¶

Endpoint	Purpose
`POST /api/vapi/find-earliest-appointment`	Find slot
`POST /api/vapi/check-appointments`	List appointments
`POST /api/vapi/create-appointment`	Book
`POST /api/vapi/update-appointment`	Reschedule
`POST /api/vapi/cancel-appointment`	Cancel

Registration¶

Endpoint	Purpose
`POST /api/vapi/register-new-patient`	Register
`POST /api/vapi/add-to-waitlist`	Add to waitlist

Call¶

Endpoint	Purpose
`POST /api/vapi/transfer-call`	Transfer
`POST /api/vapi/log-call`	Log metadata

Health¶

Endpoint	Purpose
`GET /health`	Health check

Admin API (v1.5.0+)¶

Endpoint	Purpose
`POST /api/auth/login`	User login
`POST /api/auth/logout`	User logout
`POST /api/auth/refresh`	Refresh access token
`GET /api/auth/me`	Get current user
`GET /api/admin/clinics`	List clinics (paginated)
`POST /api/admin/clinics`	Create clinic
`GET /api/admin/clinics/:id`	Get clinic details
`PUT /api/admin/clinics/:id`	Update clinic
`GET /api/admin/users`	List users (paginated)
`POST /api/admin/users`	Create user
`GET /api/admin/audit-logs`	List audit logs

Rate Limits¶

Endpoint	Limit	Burst
General API	100/min	20
create-appointment	20/min	5
health	Unlimited	-

Environment Variables¶

# Required - Database
POSTGRES_PASSWORD=        # Database password

# Required - Environment
NODE_ENV=production       # Environment

# Required - OSCAR Integration
OSCAR_API_URL=           # OSCAR REST Bridge
OSCAR_API_KEY=           # OSCAR API key

# Required - Vapi Integration
VAPI_WEBHOOK_SECRET=     # Vapi signature
VAPI_BEARER_TOKEN=       # Bearer token auth

# Required - Clinic
TRANSFER_NUMBER=         # Staff phone

# Required - Admin System (v1.5.0+)
JWT_SECRET=              # Access token signing key
JWT_REFRESH_SECRET=      # Refresh token signing key
ENCRYPTION_KEY=          # Credential encryption

# Optional - Admin System
JWT_EXPIRES_IN=1h        # Access token expiry
JWT_REFRESH_EXPIRES_IN=7d # Refresh token expiry
EMR_DEMO_MODE=true       # Enable demo responses

# Optional - EMR Abstraction (v1.4.0+)
USE_EMR_ADAPTER=false    # Enable adapter pattern
EMR_ADAPTER_CLINICS=     # Comma-separated clinic IDs

Ports¶

Service	Internal	External
PostgreSQL	5432	-
Voice Agent	3001	-
NGINX HTTP	80	9080
NGINX HTTPS	443	9443

Paths¶

Path	Description
`/opt/vitara-platform/`	Production deployment
`/home/ubuntu/vitara-platform/`	Development
`/etc/letsencrypt/live/vitaravox.ca/`	SSL certificates
`/var/lib/docker/volumes/vitara-db-data/`	Database volume