Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
93 lines (73 sloc) 5.54 KB

QMK Keymap Compiler API

This page describes the API for interacting with QMK Compiler. 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.

Example JSON Payload:

  "keyboard": "clueboard/66/rev2",
  "keymap": "my_awesome_keymap",
  "layout": "KEYMAP",
  "layers": [

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 mulitple LAYOUT macros you can specify which macro to use.

Submitting a Compile Job

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)"
  "enqueued": true,
  "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"

Checking The Status

After submitting your keymap you can check the status using a simple HTTP GET call:

$ curl
  "created_at": "Sat, 19 Aug 2017 21:39:12 GMT",
  "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",
  "id": "f5f9b992-73b4-479b-8236-df1deb37c163",
  "status": "running",
  "result": null

This shows us that the job has made it through the queue and is currently running. There are 5 possible statuses:

  • failed: Something about the compiling service has broken.
  • finished: The compilation is complete and you should check result to see the results.
  • queued: The keymap is waiting for a compilation server to become available.
  • running: The compilation is in progress and should be complete soon.
  • unknown: A serious error has occurred and you should file a bug.

Downloading The Results

When your job has completed and the compilation was successful you can download your new firmware. To download only the .hex file for flashing append "hex" to your URL:

$ curl -i
HTTP/1.0 200 OK
Content-Disposition: attachment; filename=clueboard_rev2_my_awesome_keymap.hex
Content-Length: 63558
Content-Type: application/octet-stream
Last-Modified: Sat, 19 Aug 2017 22:46:54 GMT
Cache-Control: public, max-age=43200
Expires: Sun, 20 Aug 2017 10:47:19 GMT
ETag: "1503182814.0-63558-190654682"
Date: Sat, 19 Aug 2017 22:47:19 GMT


If you'd like to download the source code as well as the hex you can append "source" instead:

$ curl >
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 10.8M  100 10.8M    0     0  52.2M      0 --:--:-- --:--:-- --:--:-- 52.0M
$ file Zip archive data, at least v1.0 to extract
You can’t perform that action at this time.