AI Scribe API Testing Guide with Postman

Prerequisites

Start the Rails server:

cd /Users/madhav/Documents/Kulcare/kulcare-api-backend/backend
bundle exec rails server

Get Authentication Token:
- You'll need a valid JWT token from logging in as a doctor or clinic user
- Use the existing login endpoint to get your token

Base URL

http://localhost:3000

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer YOUR_JWT_TOKEN_HERE

1. Deepgram Token Authentication

Issue Temporary Token for Audio Streaming

POST /ai_scribe/issue_token
Content-Type: application/json

{
  "session_id": "c3c18c00-0783-48ca-882f-802320e7bf11"
}

Purpose: Generate secure temporary tokens for client-side Deepgram WebSocket connections

2. Transcription Sessions

Create Transcription Session

POST /appointments/:appointment_id/transcription_sessions
Content-Type: application/json

{
  "appointment_id": 356
}

Expected Response:

{
  "success": true,
  "message": "Transcription session started successfully",
  "data": {
    "id": 7,
    "appointment_id": 332,
    "session_id": "ts_73f5a79a4156ef83f712ec5ed72b5e49",
    "status": "active",
    "language": "en-US",
    "sample_rate": 16000,
    "speaker_detection": true,
    "medical_terminology": true,
    "metadata": {
      "clinic_id": 10,
      "doctor_id": 8,
      "patient_id": 16,
      "websocket_url": "wss://mock.deepgram.com/ts_73f5a79a4156ef83f712ec5ed72b5e49",
      "options": {
        "language": "en-US",
        "model": "nova-2-medical",
        "punctuate": true,
        "diarize": true,
        "medical_vocabulary": true
      }
    },
    "started_at": "2025-09-08T07:56:14.277Z",
    "total_duration_ms": 0,
    "segments_count": 0
  }
}

Show Transcription Session

GET /appointments/:appointment_id/transcription_sessions/:session_id

Note: The session_id in the URL is the UUID (e.g., "ts_73f5a79a4156ef83f712ec5ed72b5e49"), not the database ID

Add Transcription Segments (Batch or Single)

POST /appointments/:appointment_id/transcription_sessions/:session_id/segments
Content-Type: application/json

[
  {
    "content": "Doctor: Good morning, Mr. Sharma. How are you feeling today?\nPatient: Good morning, doctor. I've been having headaches for the past few days.",
    "confidence_score": 0.94,
    "start_time_ms": 0,
    "end_time_ms": 8000,
    "speaker": "0",
    "source": "api",
    "broadcast": true
  },
  {
    "content": "Doctor: I see. Can you describe the headache? Is it sharp, dull, or throbbing?\nPatient: It's mostly a dull ache, but sometimes it feels like pressure on both sides of my head.",
    "confidence_score": 0.94,
    "start_time_ms": 8000,
    "end_time_ms": 15000,
    "speaker": "0",
    "source": "api",
    "broadcast": true
  }
]

Single Segment Format:

{
  "content": "Patient presents with severe headaches for 3 days, pain level 7/10",
  "confidence_score": 0.95,
  "start_time_ms": 0,
  "end_time_ms": 30000,
  "source": "api",
  "broadcast": true,
  "session_id": "ts_73f5a79a4156ef83f712ec5ed72b5e49"
}

Get Full Transcript

GET /appointments/:appointment_id/transcription_sessions/:session_id/transcript

Response:

{
  "success": true,
  "message": "Full transcript retrieved successfully",
  "data": {
    "session_id": "ts_73f5a79a4156ef83f712ec5ed72b5e49",
    "full_transcript": "Patient presents with severe headaches for 3 days...",
    "segments_count": 1,
    "total_duration_ms": 0,
    "segments": [...]
  }
}

Stop Transcription Session

PUT /appointments/:appointment_id/transcription_sessions/:session_id/stop

Response:

{
  "success": true,
  "message": "Transcription session stopped successfully",
  "data": {
    "id": 7,
    "status": "completed",
    "ended_at": "2025-09-08T09:21:51.464Z",
    "metadata": {
      "deepgram_response": {
        "duration_seconds": 91,
        "words_transcribed": 371
      }
    }
  }
}

3. AI Suggestions

Generate AI Suggestions

POST /appointments/:appointment_id/ai_suggestions/generate
Content-Type: application/json

{
  "transcription_session_id": "ebfbb5b3-aa3f-4032-a697-edeb28df3937",
  "broadcast": true
}

Response:

{
  "success": true,
  "message": "Generated 4 AI suggestions successfully"
}

Get All AI Suggestions

GET /appointments/:appointment_id/ai_suggestions

Response: Paginated list with suggestion types:

vitals: Blood pressure, pulse, temperature, etc.
complaint: Chief complaints with symptoms
medication: Drug prescriptions with dosage/frequency
test: Diagnostic tests with urgency levels

Example Response:

{
  "success": true,
  "message": "AI suggestions retrieved successfully",
  "data": {
    "ai_suggestions": [
      {
        "id": 11,
        "suggestion_type": "test",
        "content": {
          "reason": "Rule out structural abnormalities",
          "urgency": "Routine",
          "test_name": "MRI Brain",
          "special_instructions": "With and without contrast"
        },
        "confidence_score": "0.72",
        "reasoning": "Suggested diagnostic tests to confirm diagnosis",
        "status": "pending",
        "ai_model_version": "mock-model-v1",
        "formatted_content": {
          "test_name": "MRI Brain",
          "urgency": "Routine"
        }
      },
      {
        "id": 10,
        "suggestion_type": "medication",
        "content": {
          "route": "Oral",
          "dosage": "50mg",
          "duration": "3 days",
          "drug_name": "Sumatriptan",
          "frequency": "As needed",
          "instructions": "Take at onset of migraine symptoms"
        },
        "confidence_score": "0.85",
        "status": "pending",
        "formatted_content": {
          "drug_name": "Sumatriptan",
          "dosage": "50mg",
          "frequency": "As needed"
        }
      }
    ]
  },
  "total_pages": 1,
  "total_records": 8,
  "current_page": 1
}

Show Specific AI Suggestion

GET /appointments/:appointment_id/ai_suggestions/:suggestion_id

Accept AI Suggestion

POST /appointments/:appointment_id/ai_suggestions/:suggestion_id/accept
Content-Type: application/json

{
  "apply_to_careplan": true,
  "broadcast": true
}

Response:

{
  "success": true,
  "message": "AI suggestion accepted successfully",
  "data": {
    "status": "accepted",
    "processed_at": "2025-09-08T09:59:41.093Z",
    "processed_by": {
      "id": 24,
      "name": "Madhav"
    }
  }
}

4. Clinic AI Scribe Settings

Get Clinic AI Scribe Settings

GET /clinics/:clinic_id/ai_scribe_settings

Complete Test Flow Example

POST /auth/login
Content-Type: application/json

{
  "phone_number": "YOUR_PHONE",
  "password": "YOUR_PASSWORD"
}

Save the auth_token from response.

Step 2: Find an Appointment

Get an existing appointment ID:

GET /appointments

Step 3: Get Deepgram Token (Optional - for WebSocket testing)

POST /ai_scribe/issue_token
Content-Type: application/json

{
  "session_id": "test-session-123"
}

Step 4: Start Transcription Session

POST /appointments/356/transcription_sessions
Content-Type: application/json

{
  "appointment_id": 356
}

Save the session_id from response (e.g., "ts_73f5a79a4156ef83f712ec5ed72b5e49").

Step 5: Add Transcript Segments (Batch)

POST /appointments/356/transcription_sessions/ts_73f5a79a4156ef83f712ec5ed72b5e49/segments
Content-Type: application/json

[
  {
    "content": "Doctor: Good morning. How are you feeling today?\nPatient: I've been having severe headaches for 3 days.",
    "confidence_score": 0.94,
    "start_time_ms": 0,
    "end_time_ms": 8000,
    "speaker": "0",
    "source": "api",
    "broadcast": true
  },
  {
    "content": "Doctor: Where is the pain located?\nPatient: Mostly in the frontal area, with nausea and photophobia.",
    "confidence_score": 0.95,
    "start_time_ms": 8000,
    "end_time_ms": 15000,
    "speaker": "0",
    "source": "api",
    "broadcast": true
  }
]

Step 6: Generate AI Suggestions

POST /appointments/356/ai_suggestions/generate
Content-Type: application/json

{
  "transcription_session_id": "ts_73f5a79a4156ef83f712ec5ed72b5e49",
  "broadcast": true
}

Step 7: Review AI Suggestions

GET /appointments/356/ai_suggestions

Step 8: Accept a Suggestion

POST /appointments/356/ai_suggestions/11/accept
Content-Type: application/json

{
  "apply_to_careplan": true,
  "broadcast": true
}

Step 9: Get Full Transcript

GET /appointments/356/transcription_sessions/ts_73f5a79a4156ef83f712ec5ed72b5e49/transcript

Step 10: Stop Transcription Session

PUT /appointments/356/transcription_sessions/ts_73f5a79a4156ef83f712ec5ed72b5e49/stop

Testing with Mock Data

The system currently uses mock services for testing:

Mock Deepgram Integration

Returns mock WebSocket URL: wss://mock.deepgram.com/{session_id}
Simulates transcription processing
Tracks word count and duration

Mock AI Suggestions

Will generate 4 types of suggestions:

Vitals (Confidence: ~0.73-0.74)

{
  "suggestion_type": "vitals",
  "content": {
    "blood_pressure": "120/80",
    "pulse": "72 bpm",
    "temperature": "98.6°F",
    "respiratory_rate": "16 breaths/min",
    "oxygen_saturation": "98%"
  }
}

Complaints (Confidence: ~0.86-0.87)

{
  "suggestion_type": "complaint",
  "content": {
    "chief_complaint": "Headache",
    "duration": "2 days",
    "severity": "7/10",
    "location": "Frontal",
    "associated_symptoms": ["Nausea", "Photophobia"]
  }
}

Medications (Confidence: ~0.75-0.85)

{
  "suggestion_type": "medication",
  "content": {
    "drug_name": "Sumatriptan",
    "dosage": "50mg",
    "frequency": "As needed",
    "route": "Oral",
    "duration": "3 days"
  }
}

Tests (Confidence: ~0.72-0.92)

{
  "suggestion_type": "test",
  "content": {
    "test_name": "MRI Brain",
    "urgency": "Routine",
    "reason": "Rule out structural abnormalities",
    "special_instructions": "With and without contrast"
  }
}

Common Error Responses

404 Not Found

{
  "success": false,
  "errors": [
    {
      "source": "appointment",
      "title": "not found"
    }
  ]
}

403 Forbidden

{
  "success": false,
  "errors": [
    {
      "source": "user",
      "title": "not authorized to access this appointment"
    }
  ]
}

422 Unprocessable Entity

{
  "success": false,
  "errors": [
    {
      "source": "transcription_session",
      "title": "already exists for this appointment"
    }
  ]
}

Postman Environment Variables

Create environment variables for easier testing:

{
  "url": "http://localhost:3000",
  "auth_token": "YOUR_JWT_TOKEN",
  "appointment_id": "356",
  "session_id": "ts_73f5a79a4156ef83f712ec5ed72b5e49",
  "suggestion_id": "11",
  "clinic_id": "10"
}

Then use them in requests:

{{url}}/appointments/{{appointment_id}}/transcription_sessions

Tips for Testing

Use the actual session ID: The session_id from response is the UUID (ts_*), not the database ID
Batch segments: You can send multiple segments in one API call for efficiency
Broadcast flag: Set broadcast: true to enable real-time updates via WebSocket
Check response times: AI suggestions may take 10-15 seconds to generate
Monitor Rails logs: Check server logs for detailed processing information

Sample cURL Commands

If you prefer cURL over Postman:

# Start session
curl -X POST http://localhost:3000/appointments/356/transcription_sessions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appointment_id": 356}'

# Add segment
curl -X POST http://localhost:3000/appointments/356/transcription_sessions/ts_73f5a79a4156ef83f712ec5ed72b5e49/segments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Patient complains of headache","confidence_score":0.95,"source":"api","broadcast":true}'

# Generate suggestions
curl -X POST http://localhost:3000/appointments/356/ai_suggestions/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transcription_session_id":"ts_73f5a79a4156ef83f712ec5ed72b5e49","broadcast":true}'

Response Time Expectations

Based on actual testing:

Create transcription session: 2-3 seconds
Add transcription segments: 5-45 seconds (depends on content length)
Generate AI suggestions: 10-15 seconds
Retrieve suggestions: 3-8 seconds
Accept/Reject suggestions: 1-2 seconds

Important Notes

Authentication: All endpoints require valid JWT token
Session ID Format: Always use the full UUID (ts_*) returned from session creation
Batch Processing: Multiple segments can be sent in one request for better performance
Real-time Updates: Set broadcast: true to trigger WebSocket updates
Mock Services: Current implementation uses mock Deepgram and AI services for testing

AI Scribe API Testing Guide with Postman

PrerequisitesCopy Anchor Link

Base URLCopy Anchor Link

AuthenticationCopy Anchor Link

1. Deepgram Token AuthenticationCopy Anchor Link

Issue Temporary Token for Audio StreamingCopy Anchor Link

2. Transcription SessionsCopy Anchor Link

Create Transcription SessionCopy Anchor Link

Show Transcription SessionCopy Anchor Link

Add Transcription Segments (Batch or Single)Copy Anchor Link

Get Full TranscriptCopy Anchor Link

Stop Transcription SessionCopy Anchor Link

3. AI SuggestionsCopy Anchor Link

Generate AI SuggestionsCopy Anchor Link

Get All AI SuggestionsCopy Anchor Link

Show Specific AI SuggestionCopy Anchor Link

Accept AI SuggestionCopy Anchor Link

4. Clinic AI Scribe SettingsCopy Anchor Link

Get Clinic AI Scribe SettingsCopy Anchor Link

Complete Test Flow ExampleCopy Anchor Link

Step 1: Login to Get TokenCopy Anchor Link

Step 2: Find an AppointmentCopy Anchor Link

Step 3: Get Deepgram Token (Optional - for WebSocket testing)Copy Anchor Link

Step 4: Start Transcription SessionCopy Anchor Link

Step 5: Add Transcript Segments (Batch)Copy Anchor Link

Step 6: Generate AI SuggestionsCopy Anchor Link

Step 7: Review AI SuggestionsCopy Anchor Link

Step 8: Accept a SuggestionCopy Anchor Link

Step 9: Get Full TranscriptCopy Anchor Link

Step 10: Stop Transcription SessionCopy Anchor Link

Testing with Mock DataCopy Anchor Link

Mock Deepgram IntegrationCopy Anchor Link

Mock AI SuggestionsCopy Anchor Link

Common Error ResponsesCopy Anchor Link

404 Not FoundCopy Anchor Link

403 ForbiddenCopy Anchor Link

422 Unprocessable EntityCopy Anchor Link

Postman Environment VariablesCopy Anchor Link

Tips for TestingCopy Anchor Link

Sample cURL CommandsCopy Anchor Link

Response Time ExpectationsCopy Anchor Link

Important NotesCopy Anchor Link

On this page

Prerequisites

Base URL

Authentication

1. Deepgram Token Authentication

Issue Temporary Token for Audio Streaming

2. Transcription Sessions

Create Transcription Session

Show Transcription Session

Add Transcription Segments (Batch or Single)

Get Full Transcript

Stop Transcription Session

3. AI Suggestions

Generate AI Suggestions

Get All AI Suggestions

Show Specific AI Suggestion

Accept AI Suggestion

4. Clinic AI Scribe Settings

Get Clinic AI Scribe Settings

Complete Test Flow Example

Step 1: Login to Get Token

Step 2: Find an Appointment

Step 3: Get Deepgram Token (Optional - for WebSocket testing)

Step 4: Start Transcription Session

Step 5: Add Transcript Segments (Batch)

Step 6: Generate AI Suggestions

Step 7: Review AI Suggestions

Step 8: Accept a Suggestion

Step 9: Get Full Transcript

Step 10: Stop Transcription Session

Testing with Mock Data

Mock Deepgram Integration

Mock AI Suggestions

Common Error Responses

404 Not Found

403 Forbidden

422 Unprocessable Entity

Postman Environment Variables

Tips for Testing

Sample cURL Commands

Response Time Expectations

Important Notes