Developer
API Documentation
This directory contains API documentation for the Kulcare platform services.
Available API Documentation
Healthcare Services
- Teleconsultation API ✅
- Session management endpoints
- Video call participation (doctor, patient, family)
- Recording management with HIPAA compliance
- Real-time WebSocket events
- Device testing and connection quality
- Complete error code reference
API Overview
Base URLs
Staging: https://api-stg.kulcare.com
Production: https://api.kulcare.com
Development: http://localhost:8000Authentication
All API requests require JWT authentication:
Authorization: Bearer <token>Common Headers
Content-Type: application/json
Accept: application/json
X-Clinic-ID: <clinic-id>
X-Request-ID: <unique-request-id>Response Format
All API responses follow this format:
{
"success": true,
"data": { ... },
"message": "Operation successful",
"timestamp": "2025-01-08T10:00:00Z"
}Error Response Format
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": { ... }
},
"timestamp": "2025-01-08T10:00:00Z"
}API Categories
Patient Management
- Patient CRUD operations
- Medical history
- Appointments
- Prescriptions
Clinical Operations
- Queue management
- IPD management
- Follow-ups
- Encounters
Teleconsultation
- Video sessions
- Recording management
- Device testing
- Connection quality
Billing & Payments
- Subscription management
- Payment processing
- Invoice generation
- Regional gateways
User Management
- Authentication
- Role management
- Permissions
- Audit trail
Analytics & Reporting
- Commission tracking
- Revenue sharing
- Consolidated reports
- Performance metrics
Rate Limiting
Default rate limits per API category:
| Category | Limit | Window |
|---|---|---|
| Authentication | 5 requests | 1 minute |
| Read Operations | 100 requests | 1 minute |
| Write Operations | 30 requests | 1 minute |
| File Uploads | 10 requests | 5 minutes |
| Reports | 10 requests | 1 minute |
Pagination
Standard pagination parameters:
GET /api/resource?page=1&limit=20&sort=created_at&order=descResponse includes pagination metadata:
{
"data": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 100,
"totalPages": 5,
"hasNext": true,
"hasPrev": false
}
}Filtering
Standard filter format:
GET /api/resource?filter[status]=active&filter[date_from]=2025-01-01SDK Support
JavaScript/TypeScript
import { KulcareAPI } from '@kulcare/api-client'
const api = new KulcareAPI({
baseURL: process.env.VITE_API_URL,
token: authToken
})Error Handling
try {
const response = await api.patients.list()
} catch (error) {
if (error.code === 'UNAUTHORIZED') {
// Handle auth error
} else if (error.code === 'NETWORK_ERROR') {
// Handle network error
}
}WebSocket Support
Real-time updates via WebSocket:
const ws = new WebSocket('wss://api.kulcare.com/ws')
ws.on('connect', () => {
ws.send(JSON.stringify({
type: 'authenticate',
token: authToken
}))
})
ws.on('message', (data) => {
const event = JSON.parse(data)
// Handle real-time events
})HIPAA Compliance
All healthcare-related APIs follow HIPAA compliance:
- Encryption: All data encrypted in transit (TLS 1.2+)
- Audit Trail: All PHI access logged
- Access Control: Role-based permissions
- Data Retention: Configurable retention policies
- Patient Consent: Explicit consent tracking
Testing
Test Environment
Base URL: https://api-stg.kulcare.com
Test Credentials: Available in 1PasswordPostman Collection
Import the Postman collection for easy testing:
Support
For API support:
- Documentation Issues: Create GitHub issue
- Integration Support: api-support@kulcare.com
- Security Issues: security@kulcare.com
Contributing
To add new API documentation:
- Create a markdown file in this directory
- Follow the existing format
- Include request/response examples
- Document all error codes
- Update this index file
Last Updated: January 2025 API Version: 1.0.0