BondMCP Platform API - Quick Reference

October 3, 2025 · View on GitHub

Version: 2.1.0
Base URL: https://api.bondmcp.com or http://localhost:8000
Last Updated: September 30, 2025

Authentication

Most endpoints require authentication via JWT token:

# Get token
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'

# Use token
curl -X GET http://localhost:8000/api/v1/patients \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

🔐 Authentication Endpoints

MethodEndpointDescriptionAuth Required
POST/auth/registerRegister new userNo
POST/auth/loginLogin userNo
POST/auth/verifyVerify token validityYes
POST/auth/refreshRefresh access tokenYes
POST/auth/logoutLogout and blacklist tokenYes

Example:

# Register
curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "pass123", "name": "John Doe"}'

# Login
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "pass123"}'

🏥 Patient Management

MethodEndpointDescriptionAuth Required
GET/api/v1/patientsList all patientsYes
POST/api/v1/patientsCreate new patientYes
GET/api/v1/patients/{id}Get patient by IDYes
GET/api/v1/patients/{id}/historyGet patient medical historyYes

Example:

# Create patient
curl -X POST http://localhost:8000/api/v1/patients \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith", "dob": "1985-03-15", "email": "jane@example.com"}'

# Get patient
curl -X GET http://localhost:8000/api/v1/patients/patient_123 \
  -H "Authorization: Bearer TOKEN"

💊 Prescription Management

MethodEndpointDescriptionAuth Required
GET/api/v1/prescriptionsList prescriptionsYes
POST/api/v1/prescriptionsCreate prescriptionYes
PATCH/api/v1/prescriptions/{id}Update prescriptionYes
DELETE/api/v1/prescriptions/{id}Delete prescriptionYes
POST/api/v1/prescriptions/{id}/refillRequest refillYes

Example:

# Create prescription
curl -X POST http://localhost:8000/api/v1/prescriptions \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"medication": "Lisinopril", "dosage": "10mg", "frequency": "daily", "patient_id": "patient_123"}'

# Request refill
curl -X POST http://localhost:8000/api/v1/prescriptions/rx_123/refill \
  -H "Authorization: Bearer TOKEN"

📋 Medical Records

MethodEndpointDescriptionAuth Required
GET/api/v1/medical-recordsList medical recordsYes
POST/api/v1/medical-recordsCreate recordYes
GET/api/v1/medical-records/{id}Get record by IDYes
POST/api/v1/medical-records/{id}/shareShare recordYes
GET/api/v1/medical-records/sharedGet shared recordsYes

Example:

# Create medical record
curl -X POST http://localhost:8000/api/v1/medical-records \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "lab_result", "data": {"test": "cholesterol", "value": 185}, "patient_id": "patient_123"}'

📅 Appointment Management

MethodEndpointDescriptionAuth Required
GET/api/v1/appointmentsList appointmentsYes
POST/api/v1/appointmentsCreate appointmentYes
GET/api/v1/appointments/{id}Get appointmentYes
DELETE/api/v1/appointments/{id}Delete appointmentYes
POST/api/v1/appointments/{id}/cancelCancel appointmentYes
GET/api/v1/appointments/available-slotsGet available slotsYes

Example:

# Create appointment
curl -X POST http://localhost:8000/api/v1/appointments \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"date": "2025-10-15", "time": "10:00", "type": "consultation", "patient_id": "patient_123"}'

# Get available slots
curl -X GET http://localhost:8000/api/v1/appointments/available-slots \
  -H "Authorization: Bearer TOKEN"

💳 Billing & Subscriptions

MethodEndpointDescriptionAuth Required
POST/api/v1/billing/setupSetup billingYes
GET/api/v1/billing/subscriptionGet subscriptionYes
PUT/api/v1/billing/planUpdate planYes
GET/api/v1/billing/plansList available plansYes
GET/api/v1/billing/invoicesList invoicesYes
POST/api/v1/billing/payment-methodsAdd payment methodYes
GET/api/v1/billing/payment-methodsList payment methodsYes

Example:

# Setup billing
curl -X POST http://localhost:8000/api/v1/billing/setup \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan": "premium", "payment_method_id": "pm_123"}'

# Get subscription
curl -X GET http://localhost:8000/api/v1/billing/subscription \
  -H "Authorization: Bearer TOKEN"

🔑 API Key Management

MethodEndpointDescriptionAuth Required
POST/api-keys/generateGenerate API key (old)Yes
POST/api/v1/api-keys/createCreate API keyYes
GET/api/v1/api-keys/listList API keysYes
GET/api/v1/api-keys/usage/{id}Get key usageYes
DELETE/api/v1/api-keys/{id}Delete API keyYes
POST/api/v1/api-keys/{id}/regenerateRegenerate keyYes

Example:

# Create API key
curl -X POST http://localhost:8000/api/v1/api-keys/create \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Integration Key", "description": "For my mobile app"}'

Note: Requires active subscription!

🧬 Health AI Analysis

MethodEndpointDescriptionAuth Required
POST/health/bloodworkAnalyze bloodwork with AIYes
POST/health/nutritionAnalyze nutritionYes
POST/health/fitnessAnalyze fitness activityYes
POST/health/dnaAnalyze DNA dataYes
POST/health/riskAssess health risksYes

Example:

# Analyze bloodwork
curl -X POST http://localhost:8000/health/bloodwork \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"glucose": 95, "cholesterol": 180, "hdl": 55, "ldl": 100}'

# Analyze nutrition
curl -X POST http://localhost:8000/health/nutrition \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"food_items": ["salmon", "broccoli", "brown rice"], "meal_type": "dinner"}'

🏃 Digital Health Programs

MethodEndpointDescriptionAuth Required
GET/api/v1/digital-programsList programsYes
GET/api/v1/digital-programs/{id}Get program detailsYes
POST/api/v1/digital-programs/{id}/enrollEnroll in programYes

Example:

# List programs
curl -X GET http://localhost:8000/api/v1/digital-programs \
  -H "Authorization: Bearer TOKEN"

# Enroll in program
curl -X POST http://localhost:8000/api/v1/digital-programs/program_1/enroll \
  -H "Authorization: Bearer TOKEN"

🔬 Lab Reference Data

MethodEndpointDescriptionAuth Required
GET/api/v1/reference/labsList lab reference valuesNo
GET/api/v1/reference/labs/{id}Get lab referenceNo

Example:

# Get lab references
curl -X GET http://localhost:8000/api/v1/reference/labs

# Get specific lab
curl -X GET http://localhost:8000/api/v1/reference/labs/lab_1

🏢 Vendor Integrations

MethodEndpointDescriptionAuth Required
GET/api/v1/vendorsList vendorsYes
GET/api/v1/vendors/{id}Get vendor detailsYes
POST/api/v1/vendors/{id}/connectConnect to vendorYes

Example:

# List vendors
curl -X GET http://localhost:8000/api/v1/vendors \
  -H "Authorization: Bearer TOKEN"

# Connect to vendor
curl -X POST http://localhost:8000/api/v1/vendors/vendor_1/connect \
  -H "Authorization: Bearer TOKEN"

👨‍💼 Admin Endpoints

MethodEndpointDescriptionAuth Required
GET/api/v1/admin/usersList all usersYes (Admin)
GET/api/v1/admin/analyticsGet analyticsYes (Admin)
GET/api/v1/admin/system-healthSystem healthYes (Admin)

Example:

# Get analytics
curl -X GET http://localhost:8000/api/v1/admin/analytics \
  -H "Authorization: Bearer ADMIN_TOKEN"

🔧 System & Health Checks

MethodEndpointDescriptionAuth Required
GET/healthBasic health checkNo
GET/api/v1/healthDetailed healthNo
GET/api/v1/statusSystem statusNo
GET/api/v1/versionAPI versionNo
GET/api/v1/readyReadiness probeNo
GET/v2/healthV2 health checkNo
GET/v2/health/liveLiveness probeNo
GET/v2/health/readyReadiness probeNo

Example:

# Basic health check
curl -X GET http://localhost:8000/health

# Detailed health
curl -X GET http://localhost:8000/api/v1/health

# System status
curl -X GET http://localhost:8000/api/v1/status

🪝 Webhooks

MethodEndpointDescriptionAuth Required
POST/webhooks/stripeStripe webhook handlerNo (Signed)

Note: Stripe webhooks are authenticated via signature verification.

🔌 MCP Protocol

MethodEndpointDescriptionAuth Required
GET/mcp/.well-known/mcp-configurationMCP configurationNo
GET/mcp/.well-known/mcp-manifest.jsonMCP manifestNo

Common Response Codes

CodeMeaningDescription
200OKRequest successful
201CreatedResource created successfully
400Bad RequestInvalid request data
401UnauthorizedAuthentication required or invalid
402Payment RequiredSubscription required
403ForbiddenInsufficient permissions
404Not FoundResource not found
500Internal Server ErrorServer error occurred
503Service UnavailableService temporarily unavailable

Rate Limiting

Default rate limits (development):

  • Public endpoints: 100 requests/minute
  • Authenticated endpoints: 500 requests/minute
  • Admin endpoints: 1000 requests/minute

Rate limit headers:

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

Error Response Format

{
  "detail": "Error message here",
  "error": "error_code",
  "timestamp": "2025-09-30T10:00:00Z"
}

Pagination

For list endpoints that support pagination:

curl -X GET "http://localhost:8000/api/v1/patients?skip=0&limit=10" \
  -H "Authorization: Bearer TOKEN"

Parameters:

  • skip: Number of records to skip (default: 0)
  • limit: Number of records to return (default: 100, max: 1000)

Support