Skip to main content
Input includes a local WebSocket API that lets your own scripts and apps talk to your Work Louder device while Input is running. With it you can:
  • 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 only accepts connections from your own computer, and every app has to be approved by you in Input before it can do anything.
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:
  1. Make sure Input is open and your device is connected.
  2. 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 websockets for Python or gorilla/websocket for 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 keyTriggered event with that Smart Action’s identifier.
  • setKeyLighting uses the same identifiers to choose which keys to light up.
There are two ways to get them onto your device:
  • 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.
    1. Open the Smart Actions panel and create a new Smart Action.
    2. Choose the API tab and give it an identifier, such as deploy, mute-mic or volume-up. Identifiers are case-sensitive and can be up to 128 characters, with no leading or trailing spaces.
    3. Save it and assign it to a key, like any other Smart Action.
Tip: a consistent naming scheme makes lighting easier. For example, with obs-scene-1, obs-scene-2 and so on, the regex obs-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 await calls freely without hitting the rate limit.
  • Timeouts: 10 seconds for most requests, 120 seconds for addLayer and 29 seconds for requestAuthorization. A timed-out request may still have succeeded, and InputKit never retries on its own.
  • Disconnects: listen for disconnected, then call connect() and authenticate() again and refresh your device list. Add a growing delay between attempts.
  • Events: on, once and off work as usual, but InputClient is not a Node.js EventEmitter. Use input.once(...) wrapped in a promise rather than events.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.
The complete InputKit reference is in the package’s 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:
  1. On first run, they ask Input for authorization and store the credentials.
  2. 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.
  3. They react to keyTriggered events and use setKeyLighting to 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:
  • id must be an integer or a string of at most 128 characters. Responses echo it.
  • params must be an object when present.
  • Batches (arrays) and notifications (requests without id) are not supported.
A response contains either result or error:
Events from Input are notifications without an id:

Authorization flow

Before authenticating, only requestAuthorization 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:
Input shows an approval dialog with your app’s name. For connections from a browser, it also shows the website’s origin and a warning. If the user approves:
The connection is now authenticated. Store both values securely; the token can’t be retrieved again. If the user declines, you get -32003. applicationName must be 1 to 80 printable characters after trimming, with no control or invisible formatting characters. Later runs:
The result is { "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 }. profileIndex starts at 0 and layerIndex starts at 1.
  • Result: { changed: true }
  • Errors: -32010 profile not found, -32015 layer not found, -32016 the device rejected the change.
The 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.* matches volume-up and volume-down, while vol matches only an identifier that is exactly vol.
  • If nothing matches, the request fails with -32009.
Success means the device accepted the change. You’ll only see it if the key is on the active layer.
(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 }. profileIndex starts at 0.
  • Result: { added: true }
The new layer becomes the profile’s last layer. The active layer doesn’t change; call 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 by deviceId 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 contains layer, 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

This installs a layer whose first two keys send 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 keys
  • encoders: 1 row of 3 entries for the knob, in the order counter-clockwise, clockwise and press
  • joystick: an object with a type and a list of sectors, where each sector is { "k": keycode, "a1": startAngle, "a2": endAngle }
Each key is { "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):
Each key input has a 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
So you can install the same definition on several profiles without filling the device with duplicates.

7. Managing app access

Open Settings in Input and choose Manage external app permissions to see every approved app, with its origin and when it was last used. Revoking an app removes its permission and immediately disconnects it. The next time it connects, it has to ask for approval again.

8. Troubleshooting