midim-sdk · TypeScript / Node.js

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

Installation

npm install midim-sdk
# or
pnpm add midim-sdk
# or
yarn add midim-sdk

Requires Node.js 18+ (uses the built-in fetch). No external runtime dependencies.

Quick start

import { MidimClient } from "midim-sdk";

const midim = new MidimClient({ apiKey: "midim_..." });

// Verify by file hash
const result = await midim.verify({ asset_hash: "<sha256-hex-of-midi>" });

if (result.flagged) {
  console.log("Rights concern detected");
} else {
  console.log(`Rights confidence: ${result.rights_confidence}/100`);
}

Get your API key at midim.net/developer.

API Reference

All methods return a Promise and throw an enriched Error (with .status and .error fields) on non-2xx responses.

new MidimClient(options)

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | — | Required. API key starting with midim_ | | baseUrl | string | https://midim.net/api | Override for self-hosted or staging |

verify(input) → Promise<VerifyResponse>

POST /api/verify

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

| Input field | Type | Description | |---|---|---| | asset_hash | string? | SHA-256 hex hash of the MIDI file | | poim_certificate_id | string? | POIM certificate ID | | midi_file | string? | Base64-encoded MIDI file |

Returns VerifyResponse:

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

getProvenance(assetId) → Promise<ProvenanceRecord>

GET /api/provenance/{assetId}

Full certificate chain and lineage for an asset.

| Field | Type | Description | |---|---|---| | asset | object? | Asset metadata | | certChain | object[]? | Ordered list of POIM certificates | | lineage | object? | Fork / derivation history |

getCertificate(certId) → Promise<CertificateDetail>

GET /api/certificate/{certId}

Single POIM certificate with evidence and active claims.

| Field | Type | Description | |---|---|---| | certId | string? | Certificate ID | | assetId | number? | Asset ID | | poimLevel | number? | POIM level 1–4 | | status | string? | active | revoked | expired | | rights | object? | Rights breakdown | | claims | object[]? | Active claims against the certificate |

getClaims(assetId) → Promise<ClaimsList>

GET /api/claims/{assetId}

Active and resolved rights claims for an asset.

| Field | Type | Description | |---|---|---| | assetId | number? | Asset ID | | activeClaims | object[]? | Unresolved claims | | resolvedClaims | object[]? | Resolved claims |

getLicense(assetId) → Promise<LicenseStatus>

GET /api/license/{assetId}

License status and composition/arrangement rights.

| Field | Type | Description | |---|---|---| | assetId | number? | Asset ID | | licenseStatus | string? | Overall license status | | compositionStatus | string? | Composition rights status | | arrangementStatus | string? | Arrangement rights status | | rightsConfidence | number? | Confidence score 0–100 | | sourceWork | string \| null | Source work title if a derivative | | composer | string \| null | Composer attribution |

getMarketplaceEligibility(assetId) → Promise<MarketplaceEligibility>

GET /api/marketplace-eligibility/{assetId}

Check whether an asset can be listed on a marketplace.

| Field | Type | Description | |---|---|---| | assetId | number? | Asset ID | | eligible | boolean? | Eligible for marketplace listing | | reasons | string[]? | Blocking reasons if not eligible | | rightsConfidence | number? | Confidence score 0–100 |

getDatasetCompliance(datasetId) → Promise<DatasetCompliance>

GET /api/dataset-compliance/{datasetId}

Aggregate compliance report for an AI training dataset or collection.

| Field | Type | Description | |---|---|---| | datasetId | string? | Dataset identifier | | totalAssets | number? | Total assets in the dataset | | poimRegistered | number? | Number with POIM certificates | | poimDistribution | object? | Breakdown by POIM level | | licenseSummary | object? | License type distribution | | rightsCoverage | object? | Rights coverage statistics | | generatedAt | string? | ISO 8601 report timestamp |

Error handling

import { MidimClient } from "midim-sdk";

const midim = new MidimClient({ apiKey: "midim_..." });

try {
  const result = await midim.verify({ asset_hash: "abc123" });
} catch (err: any) {
  if (err.status === 401) {
    console.error("Invalid API key");
  } else if (err.status === 404) {
    console.error("Asset not found");
  } else {
    console.error(`MIDIM API error ${err.status}: ${err.error}`);
  }
}

Links

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