Creating Prescriptions

DELPHOS supports two prescription creation paths: manual creation by the physician and auto-creation from a completed consultation session. Both paths produce a prescription in draft status ready for item management, safety checking, and signing.

Prescription Lifecycle

draft → pending_review → validated → signed → submitted → dispensed
  │                                                            │
  └────────────────────────────────→ cancelled ───────────────┘

Status	Description
`draft`	Initial state — editable, items can be added or modified
`pending_review`	Submitted for review; requires at least one item
`validated`	Reviewed and approved; `valid_until` must be provided
`signed`	Signed by the prescribing doctor; `signed_by` UUID required
`submitted`	Sent to pharmacy or dispensing system
`dispensed`	Medication dispensed to the patient (terminal state)
`cancelled`	Voided — `reason` is required (terminal state)

Manual Prescription Creation

Creates a standalone prescription not linked to a consultation. Items are added in separate calls after creation.

Endpoint

POST /v1/prescriptions

Request body

Field	Type	Required	Default	Description
`patient_id`	UUID	Yes	—	FK to patients table
`doctor_id`	UUID	Yes	—	FK to doctors table
`consultation_id`	UUID	No	`null`	Optional link to a consultation session
`origin`	string	No	`"manual"`	`"manual"`, `"consultation"`, or `"imported"`
`prescription_type`	string	No	`"standard"`	`"standard"` or `"controlled"`
`notes`	string	No	`null`	Free-text notes

Response

Returns { prescription: PrescriptionDetail }. Manual prescriptions start with empty items and interactions arrays.

curl
Python

curl -X POST "https://your-instance.delphos.app/v1/prescriptions" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "doctor_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "prescription_type": "standard",
    "notes": "Patient reports difficulty swallowing tablets."
  }'

import httpx

response = httpx.post(
    "https://your-instance.delphos.app/v1/prescriptions",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "patient_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "doctor_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
        "prescription_type": "standard",
        "notes": "Patient reports difficulty swallowing tablets.",
    },
)
data = response.json()
prescription_id = data["prescription"]["id"]

Auto-Creation from a Consultation

The auto-create endpoint reads medication entities extracted from a completed consultation, matches them against the drug database, runs drug interaction safety checks, and assembles a draft prescription ready for physician review.

Endpoint

POST /v1/prescriptions/auto-create

Request body

Field	Type	Required	Description
`consultation_id`	UUID	Yes	FK to consultation_sessions
`patient_id`	UUID	Yes	FK to patients
`doctor_id`	UUID	Yes	FK to doctors (prescribing physician)

Status codes

Code	Meaning
`201`	Prescription created — full detail with items and interactions
`409`	Prescription already exists for this consultation
`422`	No medication entities found in the consultation
`500`	Internal error during creation

curl
Python

curl -X POST "https://your-instance.delphos.app/v1/prescriptions/auto-create" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consultation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "patient_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "doctor_id": "e5f6a7b8-c9d0-1234-efab-345678901234"
  }'

import httpx

response = httpx.post(
    "https://your-instance.delphos.app/v1/prescriptions/auto-create",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "consultation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "patient_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "doctor_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    },
)
data = response.json()
prescription = data["prescription"]
print(f"Created {prescription['id']} with {len(prescription['items'])} items")

Managing Prescription Items

Items represent individual medications. They can be added to draft or pending_review prescriptions.

Add an item

POST /v1/prescriptions/{prescription_id}/items

Field	Type	Required	Description
`medication_name`	string	Yes	Medication name as prescribed
`dosage`	string	Yes	Dosage string, e.g. `"500mg"`
`route`	string	Yes	Administration route, e.g. `"oral"`
`frequency`	string	Yes	Dosing frequency, e.g. `"8/8h"`
`active_ingredient`	string	No	Active ingredient (principio ativo)
`duration`	string	No	Treatment duration, e.g. `"7 dias"`
`quantity`	integer	No	Prescribed quantity (must be >= 1)
`unit`	string	No	Unit of measure, e.g. `"comprimidos"`
`instructions`	string	No	Patient-facing instructions
`clinical_notes`	string	No	Internal notes for the prescriber
`cmed_medication_id`	UUID	No	Optional link to the drug database

curl
Python

curl -X POST "https://your-instance.delphos.app/v1/prescriptions/PRESCRIPTION_ID/items" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "medication_name": "Amoxicilina",
    "active_ingredient": "AMOXICILINA TRIIDRATADA",
    "dosage": "500mg",
    "route": "oral",
    "frequency": "8/8h",
    "duration": "7 dias",
    "quantity": 21,
    "unit": "capsulas",
    "instructions": "Tomar 1 capsula de 500mg via oral a cada 8 horas."
  }'

import httpx

response = httpx.post(
    f"https://your-instance.delphos.app/v1/prescriptions/{prescription_id}/items",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "medication_name": "Amoxicilina",
        "active_ingredient": "AMOXICILINA TRIIDRATADA",
        "dosage": "500mg",
        "route": "oral",
        "frequency": "8/8h",
        "duration": "7 dias",
        "quantity": 21,
        "unit": "capsulas",
        "instructions": "Tomar 1 capsula de 500mg via oral a cada 8 horas.",
    },
)
item = response.json()

Update an item

PATCH /v1/prescriptions/{prescription_id}/items/{item_id}

All fields are optional. Only provided fields are changed.

Remove an item

DELETE /v1/prescriptions/{prescription_id}/items/{item_id}

Update Prescription Metadata

Only prescriptions in draft or pending_review status can be updated.

PATCH /v1/prescriptions/{prescription_id}

Field	Type	Description
`notes`	string	Updated free-text notes
`valid_until`	datetime	Updated expiry datetime
`prescription_type`	string	`"standard"` or `"controlled"`

Status Transitions

Advance the prescription through its lifecycle with a single endpoint.

PATCH /v1/prescriptions/{prescription_id}/status

Field	Type	Required when	Description
`status`	string	Always	Target status value
`signed_by`	UUID	`status = "signed"`	UUID of the signing doctor
`valid_until`	datetime	`status = "validated"`	Prescription expiry timestamp
`reason`	string	`status = "cancelled"`	Cancellation reason text

curl
Python

curl -X PATCH "https://your-instance.delphos.app/v1/prescriptions/PRESCRIPTION_ID/status" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "signed", "signed_by": "e5f6a7b8-c9d0-1234-efab-345678901234"}'

import httpx

response = httpx.patch(
    f"https://your-instance.delphos.app/v1/prescriptions/{prescription_id}/status",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "status": "signed",
        "signed_by": "e5f6a7b8-c9d0-1234-efab-345678901234",
    },
)
updated = response.json()

List and Retrieve Prescriptions

List prescriptions

GET /v1/prescriptions

Optional query parameters: patient_id, doctor_id, status, origin, consultation_id, date_from, date_to, limit (1-100, default 20), offset (default 0).

Response shape: { items: [...], total: integer, limit: integer, offset: integer }.

Get a single prescription

GET /v1/prescriptions/{prescription_id}

Returns the full PrescriptionDetail including items, detected interactions, safety summary, and signing readiness fields:

Field	Description
`can_sign`	`false` when critical/contraindicated interactions are unacknowledged
`blocking_interactions_count`	Count of interactions blocking signing
`pending_acknowledgements_count`	Count of all unacknowledged interactions

Templates

Reuse common medication sets across prescriptions.

Save as a template

POST /v1/prescriptions/{prescription_id}/save-as-template

Field	Type	Required	Description
`name`	string	Yes	Unique template name within the tenant
`description`	string	No	Optional description

Returns 201. Returns 409 if the template name already exists.

Create from a template

POST /v1/prescriptions/from-template

Field	Type	Required	Description
`template_id`	UUID	Yes	Template to copy items from
`patient_id`	UUID	Yes	FK to patients
`doctor_id`	UUID	Yes	FK to doctors
`consultation_id`	UUID	No	Optional consultation link

Returns 201 with the created prescription containing all items from the template.

Complete Manual Workflow

Create prescription — POST /v1/prescriptions returns a draft prescription with an empty items list.
Add medications — POST /v1/prescriptions/{id}/items for each medication.
Run safety check — POST /v1/prescriptions/{id}/safety-check detects drug interactions.
Acknowledge interactions — Review any flagged interactions (see Drug Safety).
Submit for review — PATCH /v1/prescriptions/{id}/status with {"status": "pending_review"}.
Validate — PATCH /v1/prescriptions/{id}/status with {"status": "validated", "valid_until": "2026-05-14T23:59:00Z"}.
Sign — PATCH /v1/prescriptions/{id}/status with {"status": "signed", "signed_by": "doctor-uuid"}.