auri.ee
keyboard stuff
1# QMK API
2
3This page describes using the QMK API. If you are an application developer you can use this API to compile firmware for any [QMK](https://qmk.fm) Keyboard.
4
5## Overview
6
7This 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.
8
9#### Example JSON Payload:
10
11```json
12{
13 "keyboard": "clueboard/66/rev2",
14 "keymap": "my_awesome_keymap",
15 "layout": "LAYOUT_all",
16 "layers": [
17 ["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"],
18 ["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"],
19 ["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"]
20 ]
21}
22```
23
24As 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.
25
26## Submitting a Compile Job
27
28To 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`.
29
30```
31$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" https://api.qmk.fm/v1/compile
32{
33 "enqueued": true,
34 "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"
35}
36```
37
38## Checking The Status
39
40After submitting your keymap you can check the status using a simple HTTP GET call:
41
42```
43$ curl https://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
44{
45 "created_at": "Sat, 19 Aug 2017 21:39:12 GMT",
46 "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",
47 "id": "f5f9b992-73b4-479b-8236-df1deb37c163",
48 "status": "running",
49 "result": null
50}
51```
52
53This shows us that the job has made it through the queue and is currently running. There are 5 possible statuses:
54
55* **failed**: Something about the compiling service has broken.
56* **finished**: The compilation is complete and you should check `result` to see the results.
57* **queued**: The keymap is waiting for a compilation server to become available.
58* **running**: The compilation is in progress and should be complete soon.
59* **unknown**: A serious error has occurred and you should [file a bug](https://github.com/qmk/qmk_compiler/issues).
60
61## Examining Finished Results
62
63Once 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:
64
65* `firmware_binary_url`: A list of URLs for the flashable firmware
66* `firmware_keymap_url`: A list of URLs for the `keymap.c`
67* `firmware_source_url`: A list of URLs for the full firmware source code
68* `output`: The stdout and stderr for this compile job. Errors will be found here.
69
70## Constants {#qmk-constants}
71
72If 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.
73
74The list of available constants can be retrieved by accessing one of the following endpoints:
75
76```
77$ curl https://keyboards.qmk.fm/v1/constants_metadata.json # For `master`
78{"last_updated": "2022-11-26 00:00:00 GMT", "constants": {"keycodes": ["0.0.1"]}}
79
80$ curl https://keyboards.develop.qmk.fm/v1/constants_metadata.json # For `develop`
81{"last_updated": "2022-11-26 12:00:00 GMT", "constants": {"keycodes": ["0.0.1", "0.0.2"]}}
82```
83
84::: warning
85Versions 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.
86:::
87
88::: tip
89Only keycodes are currently published, but over time all other "externally visible" IDs are expected to appear on these endpoints.
90:::
91
92To retrieve the constants associated with a subsystem, the endpoint format is as follows:
93```
94# https://keyboards.qmk.fm/v1/constants/{subsystem}_{version}.json
95```
96Which, for the metadata endpoint above results in a request of:
97```
98$ curl https://keyboards.qmk.fm/v1/constants/keycodes_0.0.1.json
99{
100 "ranges": {
101 "0x0000/0x00FF": {
102 "define": "QK_BASIC"
103 },
104 "0x0100/0x1EFF": {
105 "define": "QK_MODS"
106 },
107 "0x2000/0x1FFF": {
108 "define": "QK_MOD_TAP"
109<snip>
110```