Medical records API endpoints

The medical records API stores the clinical content produced during each patient visit. Records support general vitals and diagnosis fields, and extend to specialty-specific modules: OB/GYN (gynoRecord), dental charting (dentalRecords), and prescriptions. All authenticated endpoints require a valid Authorization bearer token and x-clinic-id header. PDF generation requires an explicit manual fetch because the binary response is handled outside the standard JSON client.

GET /patients/:id/medical-records

Retrieve all medical records for a patient. Path parameters

string

required

UUID of the patient.

Response — MedicalRecord[]

string

UUID of the medical record.

clinic_id

string

UUID of the owning clinic.

patient_id

string

UUID of the patient.

doctor_id

string

UUID of the attending doctor.

appointment_id

string | null

UUID of the linked appointment, or null if the record was created independently.

vitals

object | null

Free-form object containing vital signs (e.g., blood pressure, heart rate, temperature, weight). Structure is not enforced by the API.

diagnosis

string | null

Free-text diagnosis.

treatment_plan

string | null

Free-text treatment plan.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

doctor

object

Show UserSummary properties

string

Doctor UUID.

first_name

string

Doctor first name.

last_name

string

Doctor last name.

patient

object

Show PatientSummary properties

string

Patient UUID.

first_name

string

Patient first name.

last_name

string

Patient last name.

gynoRecord

object | null

OB/GYN data, or null if not applicable.

Show GynoRecord properties

string

UUID of the gyno record.

medical_record_id

string

UUID of the parent medical record.

last_menstrual_period

string | null

Date of the last menstrual period (YYYY-MM-DD).

estimated_due_date

string | null

Estimated due date (YYYY-MM-DD).

gestational_weeks

number | null

Gestational age in weeks.

ultrasound_notes

string | null

Free-text ultrasound findings.

image_url

string | null

URL to an uploaded ultrasound image.

dentalRecords

DentalRecord[]

Array of dental chart entries. Empty array when not applicable.

Show DentalRecord properties

string

UUID of the dental record.

medical_record_id

string

UUID of the parent medical record.

tooth_number

number

FDI notation tooth number (e.g., 11, 36).

condition

string | null

Condition observed on the tooth (e.g., “Caries”, “Fractura”).

surface

string | null

Tooth surface affected (e.g., “Mesial”, “Oclusal”).

estimated_budget

number | null

Estimated treatment cost in cents.

prescriptions

Prescription[]

Array of prescriptions issued on this record. Empty array when none.

Show Prescription properties

string

UUID of the prescription.

medical_record_id

string

UUID of the parent medical record.

medications

object[]

List of medications.

Show PrescriptionMedication properties

name

string

Medication name.

dosage

string

Dosage (e.g., “500mg”).

frequency

string

Administration frequency (e.g., “Cada 8 horas”).

additional_notes

string | null

Additional prescription notes.

pdf_url

string | null

URL to the generated prescription PDF.

createdAt

string

ISO 8601 creation timestamp.

curl --request GET \
  --url http://localhost:3001/patients/p_abc123/medical-records \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>"

POST /medical-records

Create a new medical record for a patient. The record supports specialty-specific nested objects; include only the fields relevant to the clinic’s active specialty modules. Request body

patient_id

string

required

UUID of the patient.

doctor_id

string

required

UUID of the attending doctor.

appointment_id

string

UUID of the appointment this record is associated with.

vitals

object

Free-form object for vital signs (e.g., { "blood_pressure": "120/80", "temperature_c": 36.5 }).

diagnosis

string

Free-text clinical diagnosis.

treatment_plan

string

Free-text treatment plan.

gynoRecord

object

OB/GYN-specific data. Include when the clinic has the OB/GYN specialty module enabled.

Show gynoRecord fields

gynoRecord.last_menstrual_period

string

Date of last menstrual period in YYYY-MM-DD format.

gynoRecord.estimated_due_date

string

Estimated due date in YYYY-MM-DD format.

gynoRecord.gestational_weeks

number

Gestational age in weeks.

gynoRecord.ultrasound_notes

string

Free-text ultrasound notes.

gynoRecord.image_url

string

URL to an uploaded ultrasound image.

dentalRecords

object[]

Dental chart entries. Include when the clinic has the dental specialty module enabled.

Show dentalRecords item fields

dentalRecords[].tooth_number

number

required

FDI notation tooth number.

dentalRecords[].condition

string

Observed condition on the tooth.

dentalRecords[].surface

string

Affected tooth surface.

dentalRecords[].estimated_budget

number

Estimated treatment cost in cents.

prescription

object

Prescription to attach to this record.

Show prescription fields

prescription.medications

object[]

required

List of medications. Each item must have name, dosage, and frequency.

prescription.additional_notes

string

Additional notes for the pharmacist or patient.

Response — MedicalRecord The newly created medical record. See field definitions in the GET /patients/:id/medical-records section above.

curl --request POST \
  --url http://localhost:3001/medical-records \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>" \
  --header "Content-Type: application/json" \
  --data '{
    "patient_id": "p_abc123",
    "doctor_id": "d_def456",
    "appointment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "vitals": { "blood_pressure": "130/85", "temperature_c": 37.1 },
    "diagnosis": "Hipertensión arterial leve",
    "treatment_plan": "Cambios en dieta y ejercicio. Control en 1 mes.",
    "prescription": {
      "medications": [
        { "name": "Enalapril", "dosage": "10mg", "frequency": "Una vez al día" }
      ],
      "additional_notes": "Tomar en ayunas"
    }
  }'

GET /medical-records/:id/pdf

Download a medical record as a PDF file. This endpoint returns a binary blob and must be called with a manual fetch — it is not handled by the standard JSON API client.

The PDF endpoint requires the same Authorization: Bearer <token> and x-clinic-id headers as authenticated JSON endpoints, but you must call it with a raw fetch request and read the response as a Blob.

Path parameters

string

required

UUID of the medical record.

Response — Blob (application/pdf) A binary PDF file suitable for downloading or opening in the browser.

# Download and save the PDF
curl --request GET \
  --url http://localhost:3001/medical-records/mr_xyz789/pdf \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>" \
  --output expediente.pdf

// JavaScript example using fetch
const response = await fetch(
  'http://localhost:3001/medical-records/mr_xyz789/pdf',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer <token>',
      'x-clinic-id': '<clinic_id>',
    },
  }
);

if (!response.ok) {
  throw new Error('No se pudo generar el PDF del expediente');
}

const blob = await response.blob();
const url = URL.createObjectURL(blob);
window.open(url);

Overview

Endpoints

Medical records API endpoints

GET /patients/:id/medical-records

POST /medical-records

GET /medical-records/:id/pdf

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /patients/:id/medical-records

​POST /medical-records

​GET /medical-records/:id/pdf

Build docs developers (and LLMs) love

GET /patients/:id/medical-records

POST /medical-records

GET /medical-records/:id/pdf