- react to key presses: run your own code when you press a key on the device
- change key lighting: set the color, brightness and effect of specific keys
- switch profiles and layers
- install new layers, including their Actions, Multiactions and Smart Actions
- read device information: model, firmware version, battery and the active profile and layer
The API currently works with Creator Micro V2 Base, Creator Micro V2 Pro and Codex Micro.
1. Build it with your AI agent
You don’t need to write the code yourself. Copy the prompt below into your AI coding agent (Claude Code, Cursor, ChatGPT, Codex, Copilot and so on), describe what you want under What I want to build, and let the agent write the integration for you. You don’t need to set anything up on the device. If your integration needs its own keys, the agent creates a new layer with them and installs it for you. Before you run what the agent builds:- Make sure Input is open and your device is connected.
- The first time the integration runs, Input asks you to approve it. Approve it within 30 seconds.
Prompt
2. Before you start
- Input must be running. The API starts with Input; there’s no setting to turn on.
- A supported device (Creator Micro V2 Base, Creator Micro V2 Pro or Codex Micro)
must be connected, and Input must have finished loading its configuration. Until
then the device doesn’t appear in
getDevices, and requests for it fail with-32008 Device not ready. - For InputKit: Node.js 22.4 or later, or another runtime with a standard global
WebSocket(Deno, Bun, browsers). - For any other language: a WebSocket client library, for example
websocketsfor Python orgorilla/websocketfor Go.
3. Key concepts
Devices
getDevices lists the devices that are ready to use. Each has a numeric id that is
only valid while it stays connected. After the device reconnects or Input restarts, it
can get a different ID. Look IDs up again after reconnecting, and keep your list in
sync with the devicesUpdated event.
Profiles and layers
A device has several profiles, and each profile has up to six layers.- Profile indexes start at 0: the first profile is
0. - Layer indexes start at 1: the first layer of a profile is
1.
getDeviceInfo reports the active selection in deviceStatus.selectedProfileIndex and
deviceStatus.selectedLayerIndex. When it changes, whether from your code or from the
device itself, every client receives deviceInfoChanged.
API Smart Actions
An API Smart Action is a Smart Action whose only job is to tell external apps that a key was used. It’s what connects a physical key to your code:- When you use a key bound to an API Smart Action, every connected app receives a
keyTriggeredevent with that Smart Action’s identifier. setKeyLightinguses the same identifiers to choose which keys to light up.
- From code (what the AI prompt does): the integration installs a new layer whose
keys are bound to API Smart Actions, using
addLayer(see section 6). Nothing to set up by hand, but the keys live on their own layer, and a profile holds at most six layers. - By hand in Input: use this to put an API key on a layer you already have, because
the API can add layers but can’t change existing ones.
- Open the Smart Actions panel and create a new Smart Action.
- Choose the API tab and give it an identifier, such as
deploy,mute-micorvolume-up. Identifiers are case-sensitive and can be up to 128 characters, with no leading or trailing spaces. - Save it and assign it to a key, like any other Smart Action.
Tip: a consistent naming scheme makes lighting easier. For example, withobs-scene-1,obs-scene-2and so on, the regexobs-scene-.*lights them all at once.
4. Using InputKit (JavaScript and TypeScript)
@worklouder/input-kit is the
official client library. It has no dependencies, ships ESM and CommonJS builds with
TypeScript types, and takes care of the protocol details for you: request IDs,
spacing requests to stay under the rate limit, size checks, timeouts and typed errors.
First run and later runs
requestAuthorization returns the token only once. Store it in the operating
system’s credential store (Keychain on macOS, Credential Manager on Windows), for
example with a package such as keytar. A plain JSON file is fine for experiments, but
not for something you share.
React to a key press and light it up
Switch profile and layer
Good to know
- Requests are queued. InputKit sends one request at a time, at least 400 ms apart,
so you can
awaitcalls freely without hitting the rate limit. - Timeouts: 10 seconds for most requests, 120 seconds for
addLayerand 29 seconds forrequestAuthorization. A timed-out request may still have succeeded, and InputKit never retries on its own. - Disconnects: listen for
disconnected, then callconnect()andauthenticate()again and refresh your device list. Add a growing delay between attempts. - Events:
on,onceandoffwork as usual, butInputClientis not a Node.jsEventEmitter. Useinput.once(...)wrapped in a promise rather thanevents.once(). - Browser apps send the page’s origin, and Input ties credentials to it. A browser app needs its own approval, and credentials from a Node.js script won’t work there.
docs/API.md, and
examples/cli.mjs is a runnable demo.
Example projects
Two open-source Work Louder integrations show a complete InputKit integration. They’re good starting points, and the prompt in section 1 points AI agents to them too.
Both follow the pattern recommended in this guide:
- On first run, they ask Input for authorization and store the credentials.
- They offer to add their own layer, whose keys are bound to API Smart Actions with
identifiers like
claude.agent.1, and install it once after the user confirms. - They react to
keyTriggeredevents and usesetKeyLightingto show status on those keys.
5. Protocol reference (any language)
Use this section if you’re not using JavaScript, or want to understand what InputKit does for you.Connecting
Input rejects the connection if the path or host is wrong, if the
Origin is not a
plain http:// or https:// origin, or if five clients are already connected.
Message format
Every request is a JSON-RPC 2.0 object:idmust be an integer or a string of at most 128 characters. Responses echo it.paramsmust be an object when present.- Batches (arrays) and notifications (requests without
id) are not supported.
result or error:
id:
Authorization flow
Before authenticating, onlyrequestAuthorization and authenticate are accepted.
Anything else returns -32001. A connection that hasn’t authenticated within 30
seconds is closed, and that includes the time the user spends on the approval dialog.
First run:
-32003.
applicationName must be 1 to 80 printable characters after trimming, with no control
or invisible formatting characters.
Later runs:
{ "authenticated": true }. Wrong or revoked credentials return
-32001, and Input closes the connection.
Credentials are tied to the connection origin. A native app (no Origin) and a website
each need their own approval.
Methods
getDevices
Lists ready devices.
- Params: none, or
{} - Result:
Array<{ id: number, deviceType: string }>
deviceType is creator_micro_v2_base, creator_micro_v2_pro or codex_micro.
getDeviceInfo
Returns Input’s latest information about a device without querying the device again.
- Params:
{ deviceId: number } - Result:
setActiveProfileLayer
Switches profile and layer in one step.
- Params:
{ deviceId: number, profileIndex: number, layerIndex: number }.profileIndexstarts at 0 andlayerIndexstarts at 1. - Result:
{ changed: true } - Errors:
-32010profile not found,-32015layer not found,-32016the device rejected the change.
deviceInfoChanged event that follows is the authoritative confirmation.
setKeyLighting
Changes the lighting of keys bound to API Smart Actions.
At least one of
color, brightness, effect or speed is required. The result is
{ applied: true }.
Matching rules:
- Matching is case-sensitive.
- Exact identifiers are at most 128 characters.
- Regex patterns are at most 256 characters, use RE2 syntax
(no backreferences or lookarounds) and must match the entire identifier. For
example,
vol.*matchesvolume-upandvolume-down, whilevolmatches only an identifier that is exactlyvol. - If nothing matches, the request fails with
-32009.
3355647 is 0x3333FF. JSON has no hexadecimal numbers.)
addLayer
Adds a new layer, together with the Actions, Multiactions and Smart Actions it uses, to
an existing profile.
- Params:
{ deviceId: number, profileIndex: number, definition: LayerDefinition }.profileIndexstarts at 0. - Result:
{ added: true }
setActiveProfileLayer to switch to it. Input saves the change to the device and checks
it, which can take a while, so allow up to about two minutes.
Common errors:
The definition format is described in section 6.
Events
Every authenticated connection receives every event; there’s nothing to subscribe to. Filter bydeviceId if you only care about one device.
Battery changes aren’t sent as events yet. Call
getDeviceInfo when you need the
current level.
Limits
Error codes
WebSocket close codes
6. Layer definitions for addLayer
A layer definition is a JSON object with the layer’s keys and everything those keys
refer to. It’s the same format Input uses for its built-in layer presets.
Start from an exported layer
The easiest way to get a valid layout and valid keycodes is to build the layer in Input first and export it: open the layer’s menu and choose Export layer. The exported file containslayer, actions, multiactions, smartActions and the group lists.
Add the top-level id, name, os, keyboardLayoutTypes and devices fields
described below, and you have a definition.
Structure
keyTriggered with the identifiers
deploy and rollback, and whose third key presses ⌘C.
Top-level fields
The layer
layer has id (any integer; Input assigns the real one), name, color (a CSS hex
color such as "#22AAFF"), optionally os (0 or 1, defaulting to macOS) and
layout.
The layout must have exactly the shape of the target device. Creator Micro V2 and
Codex Micro currently use:
base: 4 rows of 2, 4, 4 and 3 keysencoders: 1 row of 3 entries for the knob, in the order counter-clockwise, clockwise and pressjoystick: an object with atypeand a list ofsectors, where each sector is{ "k": keycode, "a1": startAngle, "a2": endAngle }
{ "keycode": "..." }.
Keycodes
Input rejects keycodes it doesn’t know for the layer’s operating system, and
KA_,
KM_ or SA_ references to IDs that the definition doesn’t include. You can’t refer
to Actions that already exist on the device; include everything the layer needs.
Actions, Multiactions and Smart Actions
Action (a macro):keycode, a delay in milliseconds and an actionType: 0
release, 1 press or 2 click (press and release).
Multiaction (a different result for tap, hold, double tap and tap-then-hold):
tappingTerms is the time window in milliseconds that separates a tap from a hold.
Smart Action:
Command Smart Actions (
CMD_STEP) are rejected for security reasons.
Groups
Groups control how the new entries appear in Input’s side panels:{ "id": 1, "name": "Deploy tools", "actionIds": [1, 2] }. A group can only list IDs
defined in the same definition.
How IDs are handled
IDs inside a definition only need to be unique within it. When the layer is added, Input:- gives new entries their own IDs and rewrites every reference to match
- reuses existing entries that are identical instead of adding duplicates