Architecture & Core Concepts
CLINSIFY SDK is purpose-built to empower healthcare providers and digital health applications with verified conversational medical intelligence. Unlike generic LLMs, Clinsify restricts inquiries strictly to the healthcare domain, validates outputs against medical ontologies (ICD-10, ATC pharmacology), and triggers deterministic red-flag emergency protocols.
Strict Medical Guardrails
Non-clinical inquiries (coding, finance, entertainment) are automatically intercepted.
Deterministic Red-Flag Triage
Life-threatening signs trigger instant emergency warnings and handoff to ER / 119 ambulance.
SOAP Notes & ICD-10 Mapping
Generates structured clinical summaries ready for EHR synchronization and physician review.
Pay-As-You-Go Rp 350 / Session
All back-and-forth messages in a consultation session are billed once at Rp 350 with zero retainer.
API Keys & Header Authentication
Every request to the Clinsify API requires an HTTP Bearer Token passed via the Authorization header. Never expose secret keys (`cs_live_...`) in client-side public bundles.
| Header Name | Example Value | Description |
|---|---|---|
| Authorization | Bearer cs_live_98a7c2f1... | Your secret production or sandbox API Key |
| Content-Type | application/json | Required JSON payload format |
| X-Clinsify-Faskes-ID | faskes_jkt_001 | (Optional) Healthcare facility identifier for compliance logs |
Use `cs_test_...` keys for staging and testing with simulated zero-cost responses. Switch to `cs_live_...` keys in production for real patients (Rp 350 / session).
Pay-As-You-Go Billing Structure
Clinsify applies a flat rate of Rp 350 per consultation session initiated via the API (`POST /v1/sessions`). All subsequent back-and-forth messages within the 24-hour consultation window are included with no additional fees.
Node.js & TypeScript SDK (@clinsify/sdk)
import { ClinsifyClient } from '@clinsify/sdk';
const clinsify = new ClinsifyClient({
apiKey: process.env.CLINSIFY_API_KEY!,
});
async function runMedicalTriage() {
// 1. Inisialisasi sesi konsultasi baru (Dikenakan tarif Rp 350)
const session = await clinsify.sessions.create({
patientId: 'patient_4401',
age: 38,
gender: 'female',
chiefComplaint: 'Demam 3 hari disertai batuk kering',
metadata: { faskesId: 'Klinik-Medika-01' }
});
console.log('Session Active:', session.id, 'Tarif:', session.costIdr); // Rp 350
// 2. Kirim pesan keluhan pasien
const response = await clinsify.messages.send({
sessionId: session.id,
content: 'Apakah aman minum Paracetamol 500mg jika ada riwayat maag?',
});
console.log('AI Reply:', response.text);
console.log('Is Red Flag:', response.isRedFlag); // false
console.log('Clinical Entities:', response.entities); // ['paracetamol', 'gastritis']
}Create Consultation Session
Initializes a new clinical consultation session and incurs the single Rp 350 charge. Active for 24 hours of multi-turn inquiries.
| Field | Type | Required | Description |
|---|---|---|---|
| patient_id | string | Yes | ID unik pasien di sistem faskes / aplikasi Anda |
| age | integer | Yes | Usia pasien dalam tahun (penting untuk dosis farmakologi & triase pediatrik/geriatrik) |
| gender | string | Optional | "male" | "female" | "other" |
| chief_complaint | string | Yes | Keluhan utama pertama yang disampaikan pasien |
{
"status": "success",
"data": {
"session_id": "cs_sess_90d2e81ba",
"patient_id": "patient_4401",
"status": "active",
"created_at": "2026-10-30T06:40:00Z",
"expires_at": "2026-10-31T06:40:00Z",
"cost_idr": 350,
"initial_triage": {
"level": "P3",
"category": "non_emergency",
"recommended_action": "clinical_inquiry"
}
}
}Send Message & Receive Clinical Analysis
Sends patient query to the clinical engine. Clinsify scans for emergency red flags, cross-references pharmacology ontologies, and returns a verified structured response.
{
"status": "success",
"data": {
"message_id": "msg_77192",
"session_id": "cs_sess_90d2e81ba",
"role": "assistant",
"content": "Amoxicillin aman dikonsumsi penderita maag asalkan diminum segera setelah makan...",
"is_red_flag": false,
"clinical_entities": [
{ "entity": "amoxicillin", "type": "medication", "atc_code": "J01CA04" },
{ "entity": "gastritis", "type": "condition", "icd10": "K29.7" }
],
"suggested_followups": [
"Berapa hari antibiotik ini dianjurkan diminum?",
"Apakah ada tanda alergi yang perlu diwaspadai?"
]
}
}SOAP Summary & ICD-10 Classification for EHR
Synthesizes conversation history into a structured clinical SOAP note for physicians or direct export to your hospital management system.
{
"session_id": "cs_sess_90d2e81ba",
"soap_note": {
"subjective": "Pasien wanita 38 tahun mengeluh demam sejak 3 hari disertai batuk kering...",
"objective": "Riwayat gastritis fungsional (+), alergi obat disangkal.",
"assessment": "Suspek Infeksi Saluran Pernapasan Akut (ISPA) dengan komorbiditas dispepsia.",
"plan": "Hidrasi adekuat, paracetamol 500mg prn p.c., anjurkan swab atau evaluasi fisik bila demam > 3 hari."
},
"icd10_candidates": [
{ "code": "J06.9", "name": "Acute upper respiratory infection, unspecified", "confidence": 0.88 },
{ "code": "K29.7", "name": "Gastritis, unspecified", "confidence": 0.72 }
]
}Doctor Queue Handoff
Transfers the consultation context, SOAP note, and patient history into your hospital teleconsultation doctor queue.
{
"status": "success",
"data": {
"session_id": "cs_sess_90d2e81ba",
"handoff_status": "transferred_to_doctor_queue",
"queue_ticket": "MED-TRIAGE-882",
"target_specialty": "general_practitioner",
"patient_urgency": "medium",
"handoff_timestamp": "2026-10-30T06:45:00Z"
}
}Deterministic Emergency Red-Flag Protocols
Patient safety is non-negotiable. When critical emergency symptoms are identified, the API sets `is_red_flag: true`, elevates triage to `P1_CRITICAL`, and returns immediate emergency hospital routing.
Nyeri dada menjalar ke lengan kiri / rahang, sensasi tertindih beban berat, sinkop mendadak.
Gejala FAST (Face drooping, Arm weakness, Speech difficulty, Time to call 119), kejang pertama kali.
Stridor, sesak napas berat dengan saturasi rendah, syok anafilaksis pasca konsumsi obat/makanan.
Healthcare Facility Webhooks
Subscribe to asynchronous real-time events to immediately alert hospital staff when emergencies arise or consultations conclude.
- • triage.red_flag_detected — Dipicu seketika ada tanda gawat darurat
- • session.completed — Sesi konsultasi ditutup oleh pasien atau sistem
- • handoff.physician_requested — Pasien menekan rujukan dokter manusia
HTTP Status Codes & Error Schemas
| Code | Status | Description |
|---|---|---|
| 200 OK | SUCCESS | Permintaan berhasil diproses |
| 400 Bad Request | INVALID_PAYLOAD | Parameter wajib tidak lengkap atau format usia/keluhan tidak valid |
| 401 Unauthorized | INVALID_API_KEY | API Key salah, kedaluwarsa, atau tidak disertakan di Header Authorization |
| 429 Rate Limited | QUOTA_EXCEEDED | Permintaan melebihi batas rate limit faskes (default: 60 req/min) |
| 500 Server Error | INTERNAL_AI_TIMEOUT | Layanan sedang dalam pemeliharaan otomatis |
Ready to Test Clinsify in Your App?
Get free sandbox keys and discuss technical integration with our clinical AI engineering team.