REST API and Integration

REST API and Integration Guide

The bipluk.com platform exposes an asynchronous REST API engineered with FastAPI. This interface empowers third-party DAW plugins, hardware controllers, automated backup daemons, sound archive scrapers, and headless studio appliances to programmatically access the cloud patch vault and SysEx analysis engine.

For protocol transmission mechanics, consult the Web MIDI Protocol Engine. For checksum validation and bitfield packing formulas, refer to SysEx Specifications and Checksums.

---

1. Cloud Vault Ingestion Pipeline

flowchart TD
    Client["Client / External DAW / Script"] --> Auth{"Validate Bearer Token"}
    Auth -- "Valid" --> Ingest["POST /api/patches/upload"]
    Auth -- "Invalid" --> Err401["HTTP 401 Unauthorized"]

    Ingest --> Inspect["SysEx Inspector & Validator"]
    Inspect --> Detect{"Header Recognized?"}
    Detect -- "No" --> Err400["HTTP 400 Invalid SysEx"]
    Detect -- "Yes" --> ChecksumCalc["Recompute Hardware Checksum"]

    ChecksumCalc --> Match{"Checksum Valid?"}
    Match -- "Corrupt" --> AutoFix["Recalculate & Sanitize Header"]
    Match -- "Valid" --> Store["Store in Cloud Vault"]
    AutoFix --> Store

    Store --> DB[("SQLite Metadata / S3 Binary")]
    DB --> JSONResp["HTTP 200 OK (Patch ID, Tags, Metadata)"]

Loading

---

2. Authentication & Rate Limiting

Note

Public vs Authenticated Endpoints: Public inspection endpoints (/api/sysex/inspect and /api/sysex/split) require no API key or session token. Cloud patch vault management, sound uploads, and automated patch sync require an active Bearer API token.

Pass your bearer token within the standard HTTP Authorization header:

Authorization: Bearer <API_TOKEN>

Rate limiting uses a sliding-window token bucket algorithm:

• Anonymous / Free Tier: 60 requests per minute.
• Studio Pro Tier: 600 requests per minute with unthrottled Web MIDI stream concurrency.

---

3. Core API Endpoints

POST /api/sysex/inspect

Analyzes raw SysEx hex payloads without requiring authentication.

Request Body:

{
  "raw_hex": "F04300092000...F7"
}

Response (200 OK):

{
  "status": "success",
  "synth": "Yamaha DX7",
  "format": "32_voice_bulk",
  "bytes": 4104,
  "checksum_verified": true,
  "detected_patches": [
    "E.PIANO 1",
    "BASS 1",
    "TUB BELLS",
    "STRINGS 1"
  ]
}

---

POST /api/sysex/split

Upload a monolithic multi-voice bank dump and receive individual single-voice .syx files in a compressed .zip archive. Supported multi-voice banks include Yamaha DX7 (32 voices), Roland D-50 (64 voices), and Korg M1 (100 programs).

---

GET /api/patches

Query and filter saved presets across the public archive or your authenticated personal vault.

Query Parameters:

• synth (e.g. dx7, juno106, d50, cz101) - filter by hardware target.
• category (e.g. bass, pad, lead, percussion, keys, fx) - filter by tag.
• limit (integer, default 50, max 200) - pagination page size.
• offset (integer, default 0) - pagination record offset.

---

GET /api/patches/{patch_id}/download

Streams the binary .syx file directly to the client with valid Content-Disposition: attachment; filename="patch.syx" headers.

---

4. Production Integration Examples

Python: Automated Studio Patch Vault Backup

The following script iterates through a local directory of .syx files, verifies their checksums via /api/sysex/inspect, and uploads valid patches to your cloud vault:

import os
import requests

API_BASE = "https://bipluk.com/api"
API_TOKEN = os.getenv("BIPLUK_API_TOKEN", "your_token_here")
HEADERS = {"Authorization": f"Bearer {API_TOKEN}"}

def backup_patch(file_path: str):
    with open(file_path, "rb") as f:
        syx_bytes = f.read()
    
    hex_payload = syx_bytes.hex().upper()
    
    # Step 1: Pre-flight inspection
    inspect_resp = requests.post(
        f"{API_BASE}/sysex/inspect",
        json={"raw_hex": hex_payload},
        timeout=10
    )
    inspect_resp.raise_for_status()
    meta = inspect_resp.json()
    
    print(f"[INSPECT] {file_path}: Synth={meta.get('synth')}, Valid={meta.get('checksum_verified')}")
    
    # Step 2: Upload patch to cloud vault
    with open(file_path, "rb") as f:
        upload_resp = requests.post(
            f"{API_BASE}/patches/upload",
            headers=HEADERS,
            files={"file": (os.path.basename(file_path), f, "application/octet-stream")},
            data={"category": "archived", "notes": "Automated batch studio backup"},
            timeout=15
        )
    upload_resp.raise_for_status()
    print(f"[SUCCESS] Uploaded {file_path} -> Patch ID {upload_resp.json().get('id')}")

if __name__ == "__main__":
    patch_dir = "./studio_sysex_dumps"
    for fname in os.listdir(patch_dir):
        if fname.lower().endswith(".syx"):
            backup_patch(os.path.join(patch_dir, fname))

---

cURL: Terminal Inspection and Vault Queries

1. Inspect a local SysEx dump directly from bash:

# Convert binary .syx to uppercase hex and inspect
HEX_DATA=$(xxd -p -c 999999 my_dx7_dump.syx | tr -d '\n' | tr '[:lower:]' '[:upper:]')
curl -X POST "https://bipluk.com/api/sysex/inspect" \
     -H "Content-Type: application/json" \
     -d "{\"raw_hex\": \"$HEX_DATA\"}"

2. Query all Roland Juno-106 bass patches:

curl -X GET "https://bipluk.com/api/patches?synth=juno106&category=bass&limit=10" \
     -H "Authorization: Bearer $BIPLUK_API_TOKEN" \
     -H "Accept: application/json"

3. Download patch binary directly to physical hardware bridge:

curl -L -o "patch_482.syx" \
     "https://bipluk.com/api/patches/482/download" \
     -H "Authorization: Bearer $BIPLUK_API_TOKEN"

---

5. Webhook Notifications (Event Subscriptions)

Studio Pro users can register HTTP webhook endpoints to receive real-time JSON events when:

• A new patch matching monitored tags is uploaded to the community vault (event: patch.published).
• A hardware bulk dump completes processing (event: dump.completed).
• Checksum repair succeeds on a corrupt upload (event: patch.repaired).

For synth hardware compatibility requirements, visit the Hardware Compatibility Matrix.