midim-sdk 0.1.0

Official Python SDK for the MIDIM Verify API — MIDI provenance and rights verification

midim-sdk · Python

Official Python SDK for the MIDIM Verify API — MIDI provenance, rights verification, and POIM status in one call.

Installation

pip install midim-sdk

Requires Python 3.9+. No external runtime dependencies — uses the standard library urllib.

Quick start

from midim_sdk import MidimClient

client = MidimClient(api_key="midim_...")

# Verify by file hash
result = client.verify(asset_hash="<sha256-hex-of-midi>")

if result.flagged:
    print("Rights concern detected")
else:
    print(f"Rights confidence: {result.rights_confidence}/100")

Get your API key at midim.net/developer.

API Reference

All methods return typed dataclass instances and raise MidimApiError on non-2xx responses.

MidimClient(api_key, base_url?)

Parameter	Type	Default	Description
api_key	str	—	Required. API key starting with midim_
base_url	str	https://midim.net/api	Override for self-hosted or staging

---

verify(*, asset_hash?, poim_certificate_id?, midi_file?) → VerifyResponse

POST /api/verify

Verify MIDI provenance, POIM status, rights, and marketplace eligibility in a single call. Provide at least one identifier.

Parameter	Type	Description
asset_hash	str?	SHA-256 hex hash of the MIDI file
poim_certificate_id	str?	POIM certificate ID
midi_file	str?	Base64-encoded MIDI file

Returns VerifyResponse:

Field	Type	Description
verification_id	str	Unique ID for this verification
verification_timestamp	str	ISO 8601 timestamp
known_asset	bool	Whether the asset is in the MIDIM registry
poim_registered	bool	Whether a POIM certificate exists
poim_level	int | None	POIM level 1–4 (None if not registered)
rights_confidence	int | None	Rights confidence score 0–100
active_claims	int	Number of active rights claims
license_status	str | None	License status string
marketplace_eligible	bool	Whether the asset can be listed on a marketplace
flagged	bool	Whether the asset has unresolved rights concerns
asset_id	int | None	Internal MIDIM asset ID
midim_id	str | None	Public MIDIM asset identifier

---

get_provenance(asset_id) → ProvenanceRecord

GET /api/provenance/{assetId}

Full certificate chain and lineage for an asset.

Field	Type	Description
asset	dict?	Asset metadata
cert_chain	list[dict]	Ordered list of POIM certificates
lineage	dict?	Fork / derivation history

---

get_certificate(cert_id) → CertificateDetail

GET /api/certificate/{certId}

Single POIM certificate with evidence and active claims.

Field	Type	Description
cert_id	str?	Certificate ID
asset_id	int?	Asset ID
poim_level	int?	POIM level 1–4
status	str?	active | revoked | expired
rights	dict?	Rights breakdown
claims	list[dict]	Active claims against the certificate

---

get_claims(asset_id) → ClaimsList

GET /api/claims/{assetId}

Active and resolved rights claims for an asset.

Field	Type	Description
asset_id	int?	Asset ID
active_claims	list[dict]	Unresolved claims
resolved_claims	list[dict]	Resolved claims

---

get_license(asset_id) → LicenseStatus

GET /api/license/{assetId}

License status and composition/arrangement rights.

Field	Type	Description
asset_id	int?	Asset ID
license_status	str?	Overall license status
composition_status	str?	Composition rights status
arrangement_status	str?	Arrangement rights status
rights_confidence	int?	Confidence score 0–100
source_work	str?	Source work title if a derivative
composer	str?	Composer attribution

---

get_marketplace_eligibility(asset_id) → MarketplaceEligibility

GET /api/marketplace-eligibility/{assetId}

Check whether an asset can be listed on a marketplace.

Field	Type	Description
asset_id	int?	Asset ID
eligible	bool?	Eligible for marketplace listing
reasons	list[str]	Blocking reasons if not eligible
rights_confidence	int?	Confidence score 0–100

---

get_dataset_compliance(dataset_id) → DatasetCompliance

GET /api/dataset-compliance/{datasetId}

Aggregate compliance report for an AI training dataset or collection.

Field	Type	Description
dataset_id	str?	Dataset identifier
total_assets	int?	Total assets in the dataset
poim_registered	int?	Number with POIM certificates
poim_distribution	dict?	Breakdown by POIM level
license_summary	dict?	License type distribution
rights_coverage	dict?	Rights coverage statistics
generated_at	str?	ISO 8601 report timestamp

---

Error handling

from midim_sdk import MidimClient, MidimApiError

client = MidimClient(api_key="midim_...")

try:
    result = client.verify(asset_hash="abc123")
except MidimApiError as err:
    if err.status == 401:
        print("Invalid API key")
    elif err.status == 404:
        print("Asset not found")
    else:
        print(f"MIDIM API error {err.status}: {err.error}")

Links

• Developer Portal: midim.net/developer
• API Reference: midim.net/api/docs
• TypeScript SDK: midim-sdk on npm
• License: MIT