This page describes using the QMK API. If you are an application developer you can use this API to compile firmware for any QMK Keyboard.
This service is an asynchronous API for compiling custom keymaps. You POST some JSON to the API, periodically check the status, and when your firmware has finished compiling you can download the resulting firmware and (if desired) source code for that firmware.
{\n "keyboard": "clueboard/66/rev2",\n "keymap": "my_awesome_keymap",\n "layout": "LAYOUT_all",\n "layers": [\n ["KC_GRV","KC_1","KC_2","KC_3","KC_4","KC_5","KC_6","KC_7","KC_8","KC_9","KC_0","KC_MINS","KC_EQL","KC_GRV","KC_BSPC","KC_PGUP","KC_TAB","KC_Q","KC_W","KC_E","KC_R","KC_T","KC_Y","KC_U","KC_I","KC_O","KC_P","KC_LBRC","KC_RBRC","KC_BSLS","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_INT1","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_INT5","KC_SPC","KC_SPC","KC_INT4","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],\n ["KC_ESC","KC_F1","KC_F2","KC_F3","KC_F4","KC_F5","KC_F6","KC_F7","KC_F8","KC_F9","KC_F10","KC_F11","KC_F12","KC_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SCRL","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"],\n ["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","QK_BOOT","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"]\n ]\n}As you can see the payload describes all aspects of a keyboard necessary to create and generate a firmware. Each layer is a single list of QMK keycodes the same length as the keyboard's LAYOUT macro. If a keyboard supports multiple LAYOUT macros you can specify which macro to use.
To compile your keymap into a firmware simply POST your JSON to the /v1/compile endpoint. In the following example we've placed the JSON payload into a file named json_data.
$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" https://api.qmk.fm/v1/compile\n{\n "enqueued": true,\n "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"\n}After submitting your keymap you can check the status using a simple HTTP GET call:
$ curl https://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6\n{\n "created_at": "Sat, 19 Aug 2017 21:39:12 GMT",\n "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",\n "id": "f5f9b992-73b4-479b-8236-df1deb37c163",\n "status": "running",\n "result": null\n}This shows us that the job has made it through the queue and is currently running. There are 5 possible statuses:
result to see the results.Once your compile job has finished you'll check the result key. The value of this key is a hash containing several key bits of information:
firmware_binary_url: A list of URLs for the flashable firmwarefirmware_keymap_url: A list of URLs for the keymap.cfirmware_source_url: A list of URLs for the full firmware source codeoutput: The stdout and stderr for this compile job. Errors will be found here.If you're writing a tool that leverages constants used within QMK, the API is used to publish "locked-in" versions of those constants in order to ensure that any third-party tooling has a canonical set of information to work with.
The list of available constants can be retrieved by accessing one of the following endpoints:
$ curl https://keyboards.qmk.fm/v1/constants_metadata.json # For `master`\n{"last_updated": "2022-11-26 00:00:00 GMT", "constants": {"keycodes": ["0.0.1"]}}\n\n$ curl https://keyboards.develop.qmk.fm/v1/constants_metadata.json # For `develop`\n{"last_updated": "2022-11-26 12:00:00 GMT", "constants": {"keycodes": ["0.0.1", "0.0.2"]}}WARNING
Versions exported by the master endpoint are locked-in. Any extra versions that exist on the develop endpoint which don't exist in master are subject to change.
TIP
Only keycodes are currently published, but over time all other "externally visible" IDs are expected to appear on these endpoints.
To retrieve the constants associated with a subsystem, the endpoint format is as follows:
# https://keyboards.qmk.fm/v1/constants/{subsystem}_{version}.jsonWhich, for the metadata endpoint above results in a request of:
$ curl https://keyboards.qmk.fm/v1/constants/keycodes_0.0.1.json\n{\n "ranges": {\n "0x0000/0x00FF": {\n "define": "QK_BASIC"\n },\n "0x0100/0x1EFF": {\n "define": "QK_MODS"\n },\n "0x2000/0x1FFF": {\n "define": "QK_MOD_TAP"\n<snip>