{"openapi": "3.1.0", "info": {"title": "MIDI Guide API", "version": "4.0.0", "description": "\nThe open, community-driven database of MIDI CC & NRPN implementations, and of\nnote-triggered sounds (drum maps), for hundreds of musical devices.\n\n## Quickstart\n\n```bash\ncurl https://api.midi.guide/v4/devices/elektron/digitakt-ii/\n```\n\nReturns the device's full MIDI implementation as JSON: a `metadata` block,\n`ccs` (CC/NRPN parameters, grouped by section), and `triggers` (note-triggered\nsounds/a drum map, grouped by section).\n\nDiscover what exists via the index:\n\n```bash\ncurl https://api.midi.guide/v4/devices/            # everything\ncurl https://api.midi.guide/v4/devices/elektron/   # one manufacturer\n```\n\nIndex entries include `has_ccs` / `has_triggers` flags and counts, so you know\nwhat a device offers before fetching it.\n\n## Authentication and rate limits\n\nThe MIDI Guide API is unauthenticated (it does not require an account or an API\nkey). It has no rate limit.\n\n## Formats\n\nData endpoints accept a `?format=` query parameter. `json` (the default) is\nthe canonical shape documented here; the rest are device/software-specific\nexport files:\n\n| Format | For | Content type |\n|---|---|---|\n| `json` | The canonical shape | `application/json` |\n| `oxi` | OXI One (`.oxiindef`) | `application/json` |\n| `hapax` | Squarp Hapax instrument definition | `text/plain` |\n| `pyramid` | Squarp Pyramid definition (`.def`) | `text/plain` |\n| `deluge` | Synthstrom Deluge MIDI follow XML | `text/plain` |\n| `dmmdm` | DMMDM DROID router config (`.ini`) | `text/plain` |\n| `csv` | The canonical CSV, as in the source repo | `text/csv` |\n| `triggers-csv` | The triggers (drum map) CSV, as in the source repo | `text/csv` |\n\nPer-device endpoints support all formats; `/v4/dump/` supports `json` and\n`oxi`. Requesting a format an endpoint doesn't support returns `400` with the\nsupported list. Add `?download=true` to receive the file as an attachment\nwith its conventional filename.\n\n## Freshness and caching\n\nData lives in the [pencilresearch/midi](https://github.com/pencilresearch/midi) GitHub repo and\nis synced to this API when contributions merge. Responses are served through\na CDN with long cache lifetimes and invalidated on every sync - poll as often\nas you like, but data only changes when the repo does. `last_updated` in\ndevice metadata tells you when a device's data last changed.\n\n## License and attribution\n\nThe dataset is community-contributed, provided under the\n[Creative Commons Attribution Share Alike 4.0 International](https://github.com/pencilresearch/midi/blob/main/LICENSE)\nlicense. If you build on this API, please credit **[MIDI Guide](https://midi.guide)** and link\nto it.\n\n## Contributing\n\nSpotted a wrong CC number, or want to add a device? Contributions happen as\npull requests to [pencilresearch/midi](https://github.com/pencilresearch/midi) - every device is\na plain CSV file.\n\n## Versioning and deprecation\n\nThis is v4, the first documented version.\n\n## Changelog\n\n- **2026-07-07** - v4 released: per-device and per-manufacturer endpoints,\n  `has_ccs`/`has_triggers` metadata, unified `?format=` parameter across data\n  endpoints, this documentation. v1\u2013v3 endpoints deprecated.\n"}, "paths": {"/v4/devices/": {"get": {"operationId": "list_devices", "summary": "Index of all manufacturers and devices", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DevicesIndex"}}}}}, "description": "Every manufacturer and device in the database, keyed by slug, with\nper-device metadata. Fetch a device's data from its `url`.", "tags": ["Index"]}}, "/v4/devices/{manufacturer_slug}/": {"get": {"operationId": "list_manufacturer_devices", "summary": "Index of one manufacturer's devices", "parameters": [{"in": "path", "name": "manufacturer_slug", "schema": {"title": "Manufacturer Slug", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ManufacturerIndex"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "The same shape as the full index, scoped to one manufacturer.", "tags": ["Index"]}}, "/v4/devices/{manufacturer_slug}/{device_slug}/": {"get": {"operationId": "get_device", "summary": "One device's MIDI implementation", "parameters": [{"in": "path", "name": "manufacturer_slug", "schema": {"title": "Manufacturer Slug", "type": "string"}, "required": true}, {"in": "path", "name": "device_slug", "schema": {"title": "Device Slug", "type": "string"}, "required": true}, {"in": "query", "name": "format", "schema": {"default": "json", "title": "Format", "type": "string"}, "required": false}, {"in": "query", "name": "download", "schema": {"default": false, "title": "Download", "type": "boolean"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Device"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/FormatError"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "The canonical JSON (`metadata` + `ccs` + `triggers`), or a\ndevice/software-specific export chosen with `?format=` - see the format\ntable in the API description. `?download=true` serves the export as an\nattachment with its conventional filename.", "tags": ["Data"]}}, "/v4/dump/": {"get": {"operationId": "get_dump", "summary": "The whole database", "parameters": [{"in": "query", "name": "format", "schema": {"default": "json", "title": "Format", "type": "string"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Dump"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/FormatError"}}}}}, "description": "Every device's data in one response. `?format=json` (default) is the\ncanonical shape; `?format=oxi` returns OXI device objects instead. This\nis a large response - prefer the per-device endpoints unless you really\nneed everything.", "tags": ["Data"]}}}, "components": {"schemas": {"DeviceSummary": {"properties": {"name": {"title": "Name", "type": "string"}, "slug": {"title": "Slug", "type": "string"}, "last_updated": {"anyOf": [{"format": "date-time", "type": "string"}, {"type": "null"}], "title": "Last Updated"}, "has_ccs": {"title": "Has Ccs", "type": "boolean"}, "has_triggers": {"title": "Has Triggers", "type": "boolean"}, "parameter_count": {"title": "Parameter Count", "type": "integer"}, "trigger_count": {"title": "Trigger Count", "type": "integer"}, "url": {"title": "Url", "type": "string"}}, "required": ["name", "slug", "has_ccs", "has_triggers", "parameter_count", "trigger_count", "url"], "title": "DeviceSummary", "type": "object"}, "DevicesIndex": {"properties": {"manufacturers": {"additionalProperties": {"$ref": "#/components/schemas/ManufacturerIndex"}, "title": "Manufacturers", "type": "object"}}, "required": ["manufacturers"], "title": "DevicesIndex", "type": "object"}, "ManufacturerIndex": {"properties": {"name": {"title": "Name", "type": "string"}, "slug": {"title": "Slug", "type": "string"}, "url": {"title": "Url", "type": "string"}, "devices": {"additionalProperties": {"$ref": "#/components/schemas/DeviceSummary"}, "title": "Devices", "type": "object"}}, "required": ["name", "slug", "url", "devices"], "title": "ManufacturerIndex", "type": "object"}, "Error": {"properties": {"error": {"title": "Error", "type": "string"}}, "required": ["error"], "title": "Error", "type": "object"}, "Device": {"properties": {"metadata": {"$ref": "#/components/schemas/DeviceMetadata"}, "ccs": {"additionalProperties": {"items": {"$ref": "#/components/schemas/Parameter"}, "type": "array"}, "title": "Ccs", "type": "object"}, "triggers": {"additionalProperties": {"items": {"$ref": "#/components/schemas/Trigger"}, "type": "array"}, "title": "Triggers", "type": "object"}}, "required": ["metadata", "ccs", "triggers"], "title": "Device", "type": "object"}, "DeviceMetadata": {"properties": {"manufacturer": {"title": "Manufacturer", "type": "string"}, "device": {"title": "Device", "type": "string"}, "manufacturer_slug": {"title": "Manufacturer Slug", "type": "string"}, "device_slug": {"title": "Device Slug", "type": "string"}, "last_updated": {"anyOf": [{"format": "date-time", "type": "string"}, {"type": "null"}], "title": "Last Updated"}, "repo_url": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Repo Url"}, "triggers_repo_url": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Triggers Repo Url"}, "license": {"default": "https://github.com/pencilresearch/midi/blob/main/LICENSE", "title": "License", "type": "string"}, "has_ccs": {"title": "Has Ccs", "type": "boolean"}, "has_triggers": {"title": "Has Triggers", "type": "boolean"}, "parameter_count": {"title": "Parameter Count", "type": "integer"}, "trigger_count": {"title": "Trigger Count", "type": "integer"}}, "required": ["manufacturer", "device", "manufacturer_slug", "device_slug", "has_ccs", "has_triggers", "parameter_count", "trigger_count"], "title": "DeviceMetadata", "type": "object"}, "Parameter": {"properties": {"parameter_name": {"title": "Parameter Name", "type": "string"}, "parameter_description": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Parameter Description"}, "cc_msb": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Cc Msb"}, "cc_lsb": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Cc Lsb"}, "cc_min_value": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Cc Min Value"}, "cc_max_value": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Cc Max Value"}, "cc_default_value": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Cc Default Value"}, "nrpn_msb": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Nrpn Msb"}, "nrpn_lsb": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Nrpn Lsb"}, "nrpn_min_value": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Nrpn Min Value"}, "nrpn_max_value": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Nrpn Max Value"}, "nrpn_default_value": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Nrpn Default Value"}, "orientation": {"title": "Orientation", "type": "string"}, "usage": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Usage"}, "notes": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Notes"}}, "required": ["parameter_name", "orientation"], "title": "Parameter", "type": "object"}, "Trigger": {"properties": {"sound_name": {"title": "Sound Name", "type": "string"}, "sound_description": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Sound Description"}, "midi_channel": {"title": "Midi Channel", "type": "string"}, "note_number_min_value": {"title": "Note Number Min Value", "type": "integer"}, "note_number_max_value": {"title": "Note Number Max Value", "type": "integer"}, "note_number_default_value": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Note Number Default Value"}, "comments": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Comments"}, "velocity_usage": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Velocity Usage"}}, "required": ["sound_name", "midi_channel", "note_number_min_value", "note_number_max_value"], "title": "Trigger", "type": "object"}, "FormatError": {"properties": {"error": {"title": "Error", "type": "string"}, "supported_formats": {"items": {"type": "string"}, "title": "Supported Formats", "type": "array"}}, "required": ["error", "supported_formats"], "title": "FormatError", "type": "object"}, "Dump": {"properties": {"manufacturers": {"additionalProperties": {"$ref": "#/components/schemas/DumpManufacturer"}, "title": "Manufacturers", "type": "object"}}, "required": ["manufacturers"], "title": "Dump", "type": "object"}, "DumpManufacturer": {"properties": {"name": {"title": "Name", "type": "string"}, "slug": {"title": "Slug", "type": "string"}, "devices": {"additionalProperties": {"$ref": "#/components/schemas/Device"}, "title": "Devices", "type": "object"}}, "required": ["name", "slug", "devices"], "title": "DumpManufacturer", "type": "object"}}}, "servers": [{"url": "https://api.midi.guide", "description": "Production"}]}