Bridge Agent

The OpesCare Bridge Agent is an installable Python daemon you deploy on-premise next to your local facility system or Hospital Information System (HIS). It continuously syncs records to OpesCare — without requiring your system to be internet-accessible or to implement the full Connect API.

How it Works

Obtain your agent_id and agent_key from the OpesCare admin panel.
Install the Bridge Agent: pip install opescare-bridge-agent
Configure it with your credentials in bridge_config.json.
Point it at a folder where your system exports CSV files.
Run opescare-bridge --config bridge_config.json — it watches the folder, queues records locally, and syncs to OpesCare when connected.
Every 60 seconds the agent sends a heartbeat so OpesCare knows it is alive.

If your system goes offline, records are queued in a local SQLite database and synced automatically when the connection is restored. Records are only removed from the queue after OpesCare confirms receipt.

Installation

pip install opescare-bridge-agent

# Verify installation
opescare-bridge --help

Configuration

Create a bridge_config.json file. Set OPESCARE_AGENT_KEY as an environment variable in production — do not put the key in the config file.

{
  "server_url":   "https://api.opescare.com",
  "agent_id":     "YOUR_AGENT_ID_FROM_OPESCARE_ADMIN",
  "agent_key":    "SET_VIA_OPESCARE_AGENT_KEY_ENV_VAR",
  "facility_id":  "YOUR_FACILITY_UUID",
  "environment":  "production",
  "heartbeat_interval_seconds": 60,
  "sync_interval_seconds": 300,
  "log_level": "INFO",
  "connector": {
    "type":         "csv_folder",
    "watch_folder": "./data/incoming",
    "file_pattern": "*.csv"
  }
}

Running the Agent

# Set your agent key as an environment variable
export OPESCARE_AGENT_KEY=your_agent_key_here

# Start the agent
opescare-bridge --config bridge_config.json

CSV File Naming Convention

The Bridge Agent detects the record type automatically from the CSV filename:

Filename Contains	Record Type	Key CSV Columns
`patients_`	Patient registration	first_name, last_name, dob, sex, phone
`encounters_`	Encounter / visit	health_id, notes, severity, date
`lab_results_`	Lab result	health_id, test, result, flagged, date
`prescriptions_`	Prescription	health_id, medicine, dose, frequency

Example: a file named lab_results_2026-06-01.csv will be detected as lab result records and pushed to /api/v1/bridge/sync automatically.

Sync Endpoint (Direct API)

If you are building a custom integration rather than using the daemon, call the sync endpoint directly with the X-Bridge-Agent-ID and X-Bridge-Agent-Key headers.

POST /api/v1/bridge/sync

curl -X POST https://opescare.test/api/v1/bridge/sync \
  -H "X-Bridge-Agent-ID: YOUR_AGENT_ID" \
  -H "X-Bridge-Agent-Key: YOUR_AGENT_KEY" \
  -H "X-Bridge-Timestamp: $(date +%s)" \
  -H "Idempotency-Key: sync-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "records": [
      {
        "record_type": "lab_result",
        "health_id": "CM-HID-7KQ9-MP42-X8D1",
        "test_name": "HbA1c",
        "result_value": "9.2%",
        "flagged": true,
        "occurred_at": "2026-06-01T08:00:00Z",
        "source_system": "bridge_agent_csv"
      }
    ]
  }'

Http::withHeaders([
    'X-Bridge-Agent-ID'  => env('BRIDGE_AGENT_ID'),
    'X-Bridge-Agent-Key' => env('BRIDGE_AGENT_KEY'),
    'X-Bridge-Timestamp' => time(),
    'Idempotency-Key'    => 'sync-' . \Str::uuid(),
])->post('https://opescare.test/api/v1/bridge/sync', [
    'agent_id' => env('BRIDGE_AGENT_ID'),
    'records'  => [
        [
            'record_type'  => 'lab_result',
            'health_id'    => 'CM-HID-7KQ9-MP42-X8D1',
            'test_name'    => 'HbA1c',
            'result_value' => '9.2%',
            'flagged'      => true,
        ],
    ],
]);

import requests, os, time, uuid

requests.post(
    'https://opescare.test/api/v1/bridge/sync',
    headers={
        'X-Bridge-Agent-ID':  os.environ['BRIDGE_AGENT_ID'],
        'X-Bridge-Agent-Key': os.environ['BRIDGE_AGENT_KEY'],
        'X-Bridge-Timestamp': str(int(time.time())),
        'Idempotency-Key':    f'sync-{uuid.uuid4().hex}',
    },
    json={
        'agent_id': os.environ['BRIDGE_AGENT_ID'],
        'records': [
            {
                'record_type':  'lab_result',
                'health_id':    'CM-HID-7KQ9-MP42-X8D1',
                'test_name':    'HbA1c',
                'result_value': '9.2%',
                'flagged':      True,
            },
        ],
    }
)

Response:

{
  "status": "ok",
  "accepted": 1,
  "rejected": 0,
  "sync_id": "sync_a8f3k12x"
}

Heartbeat

POST /api/v1/bridge/heartbeat

The daemon sends this automatically every 60 seconds. Agents silent for 15+ minutes are marked offline in the admin panel.

curl -X POST https://opescare.test/api/v1/bridge/heartbeat \
  -H "X-Bridge-Agent-ID: YOUR_AGENT_ID" \
  -H "X-Bridge-Agent-Key: YOUR_AGENT_KEY" \
  -H "X-Bridge-Timestamp: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"YOUR_AGENT_ID","facility_id":"YOUR_FACILITY_ID","version":"1.0.0","environment":"production"}'

import requests, os, time

requests.post('https://opescare.test/api/v1/bridge/heartbeat',
    headers={
        'X-Bridge-Agent-ID':  os.environ['BRIDGE_AGENT_ID'],
        'X-Bridge-Agent-Key': os.environ['BRIDGE_AGENT_KEY'],
        'X-Bridge-Timestamp': str(int(time.time())),
    },
    json={
        'agent_id':    os.environ['BRIDGE_AGENT_ID'],
        'facility_id': os.environ['BRIDGE_FACILITY_ID'],
        'version':     '1.0.0',
        'environment': 'production',
    }
)

Status

GET /api/v1/bridge/status

{
  "agent_id": "YOUR_AGENT_ID",
  "status": "online",
  "last_sync_at": "2026-06-01T09:30:00Z",
  "last_heartbeat_at": "2026-06-01T09:32:00Z",
  "records_synced_today": 127,
  "queue_depth": 0,
  "version": "1.0.0"
}

← SDK Widget →