> Documentation index: https://api.hlplanet.com/llms.txt. Every page is also available as Markdown by adding .md to its URL.

# HLPlanet Keyboard API

Free JSON API for keyboard size data: the standard layouts from full-size to 60%, the measured case size of 30 keyboards reviewed on [HLPlanet](https://www.hlplanet.com/), side-by-side comparisons, desk and mousepad fit, and which sizes have a given key. It returns the same numbers as the [HLPlanet keyboard size comparison](https://www.hlplanet.com/keyboard-layout/), which draws every layout to scale.

## Base URL

```text
https://api.hlplanet.com/v1
```

No API key or sign-up. Responses are JSON, served with `Access-Control-Allow-Origin: *` so you can call the API from a browser.

## Quick start

```bash
curl "https://api.hlplanet.com/v1/compare?items=tkl,75"
```

```javascript
const res = await fetch("https://api.hlplanet.com/v1/desk-fit?keyboard=tkl&desk_width_cm=120&mousepad=large");
const fit = await res.json();
console.log(fit.mouse_room_cm, fit.pad_fits);
```

## Endpoints

| Method and path | What it returns |
|---|---|
| `GET /v1/sizes` | Every standard size with key count, typical dimensions and missing keys. [Docs](https://api.hlplanet.com/docs/sizes) |
| `GET /v1/sizes/{id}` | One size: `full`, `1800`, `tkl`, `75`, `65` or `60`. [Docs](https://api.hlplanet.com/docs/sizes) |
| `GET /v1/keyboards` | The 30 measured keyboards, filterable by `size` and `q`. [Docs](https://api.hlplanet.com/docs/keyboards) |
| `GET /v1/keyboards/{id}` | One measured keyboard with its review link. [Docs](https://api.hlplanet.com/docs/keyboards) |
| `GET /v1/compare` | Two to six sizes or keyboards side by side. [Docs](https://api.hlplanet.com/docs/compare) |
| `GET /v1/desk-fit` | Whether a keyboard and mousepad fit on a desk. [Docs](https://api.hlplanet.com/docs/desk-fit) |
| `GET /v1/keys/{key}` | Which sizes have a key or key group. [Docs](https://api.hlplanet.com/docs/keys) |
| `GET /v1/tools` | Free HLPlanet keyboard and controller testers. [Docs](https://api.hlplanet.com/docs/tools) |

Errors use one JSON shape for every endpoint: see [Errors](https://api.hlplanet.com/docs/errors).

## MCP server for AI assistants

The same data is available as MCP tools at `https://api.hlplanet.com/mcp` (Streamable HTTP, no sign-in). Claude, Cursor, VS Code and Hermes Agent can connect to it directly: see [MCP server](https://api.hlplanet.com/docs/mcp).

## Machine-readable docs

- [OpenAPI 3.0 specification](https://api.hlplanet.com/openapi.json) for Postman, RapidAPI and code generators.
- [llms.txt](https://api.hlplanet.com/llms.txt) indexes these docs for AI agents. Every page is also available as Markdown: add `.md` to its URL, or send `Accept: text/markdown`.

## Attribution

The API is free to use. When you publish its numbers, please credit **HLPlanet** with a link to https://www.hlplanet.com/keyboard-layout/. Every response that comes from the size comparison includes a `compare_url` or `source` you can link to.

## Where the numbers come from

Standard sizes are built from their key layouts with 19.05 mm per key plus an estimated 10 mm case border. Measured keyboards use the case width and depth from each HLPlanet review. Once you have a keyboard, check every key, rollover and chatter with the free [HLPlanet keyboard tester](https://www.hlplanet.com/online-keyboard-tester-tool/).