Skip to main content

​
Welcome to MediSync API

The MediSync REST API provides comprehensive access to our medical AI platform, enabling seamless integration of healthcare data management, AI-powered transcription, and clinical documentation into your applications.

​
API Overview

Base URL

https://app.medisync.me/api/
All API endpoints are relative to this base URL

Authentication

Authorization: Bearer YOUR_JWT_TOKEN
JWT token required for all protected endpoints

​
Quick Reference

​
Core Resources

Primary Resource: Medical appointments with full lifecycle managementKey Endpoints:
  • GET /appointments/doctors - List doctor’s appointments
  • POST /appointments/add - Create new appointment
  • GET /appointments/get/{appointment_id} - Get appointment details
Features: Status tracking, patient linking, AI processing workflow
Primary Resource: Audio recording management and processingKey Endpoints:
  • GET /recordings - List all recordings
  • GET /recordings/{appointment_id} - Get recordings by appointment
  • DELETE /recordings/{appointment_id} - Delete recording
Features: Multi-format support, automatic transcription triggering
Primary Resource: AI-generated clinical notes and insightsKey Endpoints:
  • POST /notes/add/{appointment_id} - Create/update notes
  • GET /notes/{appointment_id} - Get clinical notes
Features: SOAP notes, AI-powered clinical documentation

​
Request Format

​
Standard Headers

All requests should include these headers: 
Content-Type: application/json
Authorization: Bearer YOUR_JWT_TOKEN
User-Agent: YourApp/1.0

​
User Identification

User identification is automatically handled through the JWT token. The server extracts the user ID from the token’s payload to authenticate and authorize requests. No separate user ID parameter is required.

​
File Uploads

File upload endpoints use multipart/form-data: 
curl -X POST https://app.medisync.me/api/recordings/add/appointment_123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "audio=@recording.wav"

​
Response Format

​
Success Response

All successful responses follow this structure: 
{
  "success": true,
  "data": {
    // Response data here
  },
  "pagination": {  // For paginated responses
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

​
Error Response

Error responses provide detailed information: 
{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "validation_error_details"
  }
}

​
API Categories

​
Authentication Endpoints

User Authentication

Login, registration, and token management for healthcare professionals

​
Core Medical Data

Appointments

Complete appointment lifecycle management with AI processing

Patients

Patient records, medical history, and insurance management

​
AI-Powered Features

Recordings

Audio file management with automatic transcription

Transcriptions

Speech-to-text with speaker diarization

Clinical Notes

AI-generated SOAP notes and medical insights

​
Document Management

Documents

PDF document storage and management

Doctor Letters

AI-generated medical referral letters

​
Common Patterns

​
Resource Relationships

Understanding the relationships between MediSync resources:

​
Workflow Patterns

  1. Create Patient - Add patient to system
  2. Schedule Appointment - Create appointment with patient
  3. Upload Recording - Add audio file
  4. Get Transcription - Retrieve AI transcription
  5. Generate Notes - Create clinical documentation

​
Pagination

For endpoints that return multiple items: 
GET /api/appointments/doctors?page=2&limit=50

# Response includes pagination info
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 250,
    "pages": 5,
    "hasNext": true,
    "hasPrev": true
  }
}

​
Status Codes

​
Success Codes

CodeMeaningUsage
200OKSuccessful GET, PUT, DELETE
201CreatedSuccessful POST (resource created)
204No ContentSuccessful DELETE (no response body)

​
Error Codes

CodeMeaningCommon Causes
400Bad RequestInvalid request data, validation errors
401UnauthorizedMissing or invalid authentication
403ForbiddenInsufficient permissions, subscription required
404Not FoundResource doesn’t exist
409ConflictDuplicate data, resource already exists
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error

​
Testing Your Integration

​
Health Check

Verify API connectivity: 
curl -X GET https://app.medisync.me/api/health \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Authentication Test

Verify your token works: 
curl -X GET https://app.medisync.me/api/user/profile \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Complete Integration Test

Test the full workflow:
1

Authenticate

Login and obtain JWT token
2

Create Patient

Add a test patient to your account
3

Schedule Appointment

Create appointment with the patient
4

Upload Test Recording

Upload a small audio file for processing
5

Verify Processing

Check transcription and notes generation

​
Rate Limiting

All endpoints are subject to rate limiting. Monitor the X-RateLimit-* headers in responses and implement appropriate backoff strategies.
Default Limits:
  • Standard: 1000 requests/hour
  • Premium: 5000 requests/hour
  • File uploads: 50-200 uploads/hour (tier dependent)

​
Support & Resources

Support

Technical support and integration help

​
Next Steps

Authentication Guide

Learn how to authenticate and obtain API tokens

Quick Start

Complete walkthrough from setup to first API call