API Endpoints Reference

Complete reference for all Oneliac REST API endpoints.

Base URL

http://localhost:8000        (Development)
https://api.oneliac.io       (Production)

Authentication

All endpoints support optional API key authentication via header:

Authorization: Bearer YOUR_API_KEY

Endpoints Overview

Method	Endpoint	Purpose
`GET`	`/health`	Health check
`GET`	`/status`	System status
`POST`	`/verify-eligibility`	Check insurance coverage
`POST`	`/validate-prescription`	Validate medication
`POST`	`/submit-federated-update`	Submit FL training data

Health Check

`GET /health`

Check if the API is operational.

Response:

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

Status Codes:

200 - API is healthy
503 - API is unavailable

Example:

curl http://localhost:8000/health

System Status

`GET /status`

Get current system status and agent metrics.

Response:

{
    "status": "operational",
    "agents": {
        "eligibility": "active",
        "prescription": "active",
        "diagnosis_model": "trained"
    },
    "federated_learning": {
        "current_round": 5,
        "participants": 3
    },
    "blockchain": {
        "endpoint": "https://api.devnet.solana.com",
        "network": "devnet"
    }
}

Status Codes:

200 - Status retrieved successfully

Example:

curl http://localhost:8000/status

Verify Eligibility

`POST /verify-eligibility`

Verify patient insurance eligibility for a procedure using zero-knowledge proofs.

Request:

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

Request Fields:

Field	Type	Required	Description
`patient_data.patient_id`	String	Yes	De-identified patient code
`patient_data.encrypted_data`	String	Yes	Base64-encoded Fernet-encrypted medical data
`patient_data.ipfs_cid`	String	Yes	IPFS Content Identifier
`patient_data.data_hash`	String	Yes	SHA256 hash of medical data
`procedure_code`	String	Yes	Medical procedure code (e.g., PROC001)

Response (Success):

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

Response Fields:

Field	Type	Description
`eligible`	Boolean	Patient is eligible for procedure
`coverage_pct`	Float	Insurance covers 0-100% of cost
`privacy_preserved`	Boolean	Encryption was 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

Status Codes:

200 - Eligibility verified successfully
400 - Invalid request format
500 - Server error during verification

Example:

curl -X POST http://localhost:8000/verify-eligibility \
  -H "Content-Type: application/json" \
  -d '{
    "patient_data": {
        "patient_id": "PAT123",
        "encrypted_data": "gAAAAABlmZ...",
        "ipfs_cid": "QmV5koooi...",
        "data_hash": "abc123..."
    },
    "procedure_code": "PROC001"
  }'

Error Response (Invalid Procedure):

{
    "detail": "Procedure code PROC999 not found"
}

Validate Prescription

`POST /validate-prescription`

Validate a prescription against patient medical history and insurance coverage.

Request:

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

Request Fields:

Field	Type	Required	Description
`patient_data.patient_id`	String	Yes	De-identified patient code
`patient_data.encrypted_data`	String	Yes	Base64-encoded Fernet-encrypted medical data
`patient_data.ipfs_cid`	String	Yes	IPFS Content Identifier
`patient_data.data_hash`	String	Yes	SHA256 hash of medical data
`drug_code`	String	Yes	Drug code (e.g., DRUG001)

Response (Success):

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

Response Fields:

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

Status Codes:

200 - Prescription validated successfully
400 - Invalid request format
500 - Server error during validation

Example:

curl -X POST http://localhost:8000/validate-prescription \
  -H "Content-Type: application/json" \
  -d '{
    "patient_data": {
        "patient_id": "PAT123",
        "encrypted_data": "gAAAAABlmZ...",
        "ipfs_cid": "QmV5koooi...",
        "data_hash": "abc123..."
    },
    "drug_code": "DRUG001"
  }'

Error Response (Drug Interaction):

{
    "detail": "Prescription validation failed: Drug interaction detected with Warfarin"
}

Submit Federated Learning Update

`POST /submit-federated-update`

Submit encrypted patient data for federated learning training round.

Request:

{
    "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
}

Request Fields:

Field	Type	Required	Description
`patient_data_list`	Array	Yes	List of patient data objects
`patient_data_list[].patient_id`	String	Yes	De-identified patient code
`patient_data_list[].encrypted_data`	String	Yes	Fernet-encrypted medical data
`patient_data_list[].ipfs_cid`	String	Yes	IPFS Content Identifier
`patient_data_list[].data_hash`	String	Yes	SHA256 hash of medical data
`round_number`	Integer	Yes	Training round number (0-indexed)

Response (Success):

{
    "round": 5,
    "participants": 3,
    "model_hash": "abc123def456abc123def456abc123def456abc123def456abc123def456abc1"
}

Response Fields:

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

Status Codes:

200 - Federated update submitted successfully
400 - Invalid request format or data mismatch
500 - Server error during training

Example:

curl -X POST http://localhost:8000/submit-federated-update \
  -H "Content-Type: application/json" \
  -d '{
    "patient_data_list": [
        {
            "patient_id": "PAT001",
            "encrypted_data": "gAAAAABlmZ...",
            "ipfs_cid": "QmV5koooi...",
            "data_hash": "abc123..."
        }
    ],
    "round_number": 5
  }'

Error Response (Decryption Failure):

{
    "detail": "Federated learning submission failed: Decryption failed - check encryption key"
}

Error Responses

Error Format

All errors return JSON with detail field:

{
    "detail": "Error description"
}

Common Errors

400 - Bad Request

{
    "detail": "Invalid request format: missing field 'patient_data'"
}

Causes:

Missing required fields
Invalid field types
Malformed JSON

500 - Internal Server Error

{
    "detail": "Eligibility check failed: ZK proof generation timed out"
}

Causes:

Proof generation failure
Blockchain connection error
Encryption/decryption failure

503 - Service Unavailable

{
    "detail": "Service temporarily unavailable"
}

Causes:

API server down
Database unavailable
Blockchain node offline

Rate Limiting

Rate Limits

Endpoint	Limit
`/health`	1000 req/min
`/status`	500 req/min
`/verify-eligibility`	100 req/min
`/validate-prescription`	100 req/min
`/submit-federated-update`	10 req/min

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705330800

Rate Limit Exceeded (429)

{
    "detail": "Rate limit exceeded. Try again in 60 seconds."
}

Pagination

Endpoints that return lists support pagination:

?offset=0&limit=10

Parameters:

offset - Number of results to skip (default: 0)
limit - Maximum results to return (default: 10, max: 100)

Request/Response Timing

Typical Response Times

Endpoint	Min	Avg	Max
`/health`	1ms	5ms	10ms
`/status`	2ms	10ms	20ms
`/verify-eligibility`	200ms	400ms	1000ms
`/validate-prescription`	400ms	800ms	1300ms
`/submit-federated-update`	500ms	2000ms	5000ms

Timeouts

Client timeout: 30 seconds
Proof generation timeout: 5 seconds
Blockchain submission timeout: 10 seconds

API Documentation Tools

Interactive API Explorer

Access Swagger UI at: http://localhost:8000/docs

ReDoc Documentation

Access ReDoc at: http://localhost:8000/redoc

OpenAPI Specification

Get the full OpenAPI schema:

curl http://localhost:8000/openapi.json

Returns JSON schema compatible with:

Swagger UI
ReDoc
OpenAPI Generator
Postman

Base URL​

Authentication​

Endpoints Overview​

Health Check​

GET /health​

System Status​

GET /status​

Verify Eligibility​

POST /verify-eligibility​

Validate Prescription​

POST /validate-prescription​

Submit Federated Learning Update​

POST /submit-federated-update​

Error Responses​

Error Format​

Common Errors​

400 - Bad Request​

500 - Internal Server Error​

503 - Service Unavailable​

Rate Limiting​

Rate Limits​

Rate Limit Headers​

Rate Limit Exceeded (429)​

Pagination​

Request/Response Timing​

Typical Response Times​

Timeouts​

API Documentation Tools​

Interactive API Explorer​

ReDoc Documentation​

OpenAPI Specification​

Next Steps​

Base URL

Authentication

Endpoints Overview

Health Check

`GET /health`

System Status

`GET /status`

Verify Eligibility

`POST /verify-eligibility`

Validate Prescription

`POST /validate-prescription`

Submit Federated Learning Update

`POST /submit-federated-update`

Error Responses

Error Format

Common Errors

400 - Bad Request

500 - Internal Server Error

503 - Service Unavailable

Rate Limiting

Rate Limits

Rate Limit Headers

Rate Limit Exceeded (429)

Pagination

Request/Response Timing

Typical Response Times

Timeouts

API Documentation Tools

Interactive API Explorer

ReDoc Documentation

OpenAPI Specification

Next Steps