Request/Response Models

Detailed specification of all request and response data structures.

PatientData Model

Represents encrypted patient information.

{
    "patient_id": "PATIENT_ABC123",
    "encrypted_data": "gAAAAABlmZ...",
    "ipfs_cid": "QmV5koooi...",
    "data_hash": "a1b2c3d4e5f6..."
}

Fields

Field	Type	Max Length	Description
patient_id	String	50	De-identified patient code
encrypted_data	String (Base64)	100KB	Fernet-encrypted medical data
ipfs_cid	String	100	IPFS Content Identifier (v0 or v1)
data_hash	String (Hex)	64	SHA256 hash in hex format

Validation Rules

• patient_id: Alphanumeric, underscore, hyphen
• encrypted_data: Valid Base64
• ipfs_cid: Valid IPFS CID format
• data_hash: Exactly 64 hex characters

Example

{
    "patient_id": "PAT_000123",
    "encrypted_data": "gAAAAABlmZ8a3pY9X...",
    "ipfs_cid": "QmV5koooi6jKRBXDo",
    "data_hash": "e3b0c44298fc1c14..."
}

---

EligibilityCheckRequest

Request to verify insurance eligibility.

{
    "patient_data": {
        "patient_id": "PATIENT_ABC123",
        "encrypted_data": "gAAAAABlmZ...",
        "ipfs_cid": "QmV5koooi...",
        "data_hash": "a1b2c3d4..."
    },
    "procedure_code": "PROC001"
}

Fields

Field	Type	Required	Description
patient_data	PatientData	Yes	Encrypted patient information
procedure_code	String	Yes	Medical procedure code

Procedure Codes

• PROC001: MRI Scan
• PROC002: X-Ray
• PROC003: CT Scan
• PROC004: Blood Work
• PROC005: Surgery (General)

---

EligibilityCheckResponse

Response with eligibility verification result.

{
    "eligible": true,
    "coverage_pct": 80.0,
    "privacy_preserved": true,
    "procedure_code": "PROC001",
    "requires_authorization": true,
    "zk_proof_verified": true,
    "reason": null
}

Fields

Field	Type	Description
eligible	Boolean	Patient is covered for procedure
coverage_pct	Float	Coverage percentage (0-100)
privacy_preserved	Boolean	Encryption used (always true)
procedure_code	String	The procedure checked
requires_authorization	Boolean	Prior authorization needed
zk_proof_verified	Boolean	ZK proof verified on blockchain
reason	String/Null	Reason if not eligible

Coverage Percentages

• 0: Not covered
• 25-75: Partial coverage
• 100: Fully covered

Requires Authorization

• true: Prior auth required before procedure
• false: Can proceed without authorization

---

PrescriptionValidationRequest

Request to validate a prescription.

{
    "patient_data": {
        "patient_id": "PATIENT_ABC123",
        "encrypted_data": "gAAAAABlmZ...",
        "ipfs_cid": "QmV5koooi...",
        "data_hash": "a1b2c3d4..."
    },
    "drug_code": "DRUG001"
}

Fields

Field	Type	Required	Description
patient_data	PatientData	Yes	Encrypted patient information
drug_code	String	Yes	Drug code

Drug Codes

• DRUG001: Warfarin
• DRUG002: Metoprolol
• DRUG003: Lisinopril
• DRUG004: Amoxicillin
• DRUG005: Sertraline
• DRUG006: Metformin
• DRUG007: Ibuprofen
• DRUG008: Omeprazole

---

PrescriptionValidationResponse

Response with prescription validation result.

{
    "valid": true,
    "drug_code": "DRUG001",
    "interactions_checked": true,
    "zk_proof_verified": true,
    "cross_chain_oracle": "LayerZero confirmed: DRUG001 available on Ethereum bridge"
}

Fields

Field	Type	Description
valid	Boolean	Prescription is safe and approved
drug_code	String	The drug code validated
interactions_checked	Boolean	Drug interactions were checked
zk_proof_verified	Boolean	Eligibility verified cryptographically
cross_chain_oracle	String	Pharmacy availability confirmation

---

FederatedLearningRequest

Request to submit federated learning update.

{
    "patient_data_list": [
        {
            "patient_id": "PATIENT_001",
            "encrypted_data": "gAAAAABlmZ...",
            "ipfs_cid": "QmV5koooi...",
            "data_hash": "a1b2c3d4..."
        },
        {
            "patient_id": "PATIENT_002",
            "encrypted_data": "gAAAAABlnZ...",
            "ipfs_cid": "QmV5koooj...",
            "data_hash": "b2c3d4e5..."
        }
    ],
    "round_number": 5
}

Fields

Field	Type	Required	Description
patient_data_list	Array[PatientData]	Yes	List of patient data
round_number	Integer	Yes	Training round number

Constraints

• patient_data_list: 1-10000 items
• round_number: 0-1000

---

FederatedLearningResponse

Response from federated learning training.

{
    "round": 5,
    "participants": 3,
    "model_hash": "abc123def456..."
}

Fields

Field	Type	Description
round	Integer	Completed training round
participants	Integer	Number of hospitals participated
model_hash	String	SHA256 hash of updated model

Model Hash

• Format: 64-character hex string
• Computed from model weights
• Identical across all participants for same round
• Used for verification

---

HealthCheckResponse

Response from health check endpoint.

{
    "status": "healthy",
    "version": "0.1.0",
    "message": "Healthcare agents API operational"
}

Fields

Field	Type	Description
status	String	Enum: "healthy", "degraded", "unhealthy"
version	String	API version (semantic versioning)
message	String	Human-readable status message

---

Error Response

Standard error response format.

{
    "detail": "Error description"
}

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request (invalid input)
401	Unauthorized (invalid API key)
429	Rate Limit Exceeded
500	Internal Server Error
503	Service Unavailable

---

Data Type Specifications

String Types

• patient_id: [A-Za-z0-9_-]{1,50}
• procedure_code: PROC\d{3}
• drug_code: DRUG\d{3}
• ipfs_cid: Qm[A-Za-z0-9]{44} (v0) or baf[A-Za-z0-9]{55} (v1)
• data_hash: [a-f0-9]{64} (SHA256 hex)

Numeric Types

• coverage_pct: Float, range [0, 100]
• round_number: Integer, range [0, 1000]
• participants: Integer, range [0, 10000]

Boolean Types

• eligible: true/false
• valid: true/false
• privacy_preserved: true/false
• interactions_checked: true/false
• zk_proof_verified: true/false
• requires_authorization: true/false

---

Encoding

All request/response bodies use:

Content-Type: application/json; charset=utf-8

Encryption Data Encoding

Encrypted data fields use Base64 encoding:

import base64
from cryptography.fernet import Fernet

encryption_key = Fernet.generate_key()
cipher = Fernet(encryption_key)

plaintext = b"patient medical data"
encrypted_bytes = cipher.encrypt(plaintext)
encrypted_b64 = base64.b64encode(encrypted_bytes).decode('utf-8')

# Send in API request
payload = {
    "encrypted_data": encrypted_b64
}

Hash Encoding

Hash values use hexadecimal encoding:

import hashlib

data = b"patient medical data"
hash_bytes = hashlib.sha256(data).digest()
hash_hex = hash_bytes.hex()  # Lowercase hex string

# Send in API request
payload = {
    "data_hash": hash_hex
}

---

Next Steps

• Error Handling
• API Endpoints
• Integration Guide