---
url: https://flat.io/developers/docs/api/instruments.md
description: >-
  The catalog of instrument IDs used across the Flat API, for creating scores
  and correcting OMR-detected parts. Browse the full list or install the
  @flat/instruments package.
---

# Instrument IDs

Across the Flat API, every instrument is referenced by a canonical **instrument ID** written as
`group.instrument`, for example `keyboards.piano`, `brass.trumpet`, or
`unpitched-percussion.drumset-rock`.

This page lists every valid ID. You can [browse the full catalog](#catalog) below, install the
[`@flat/instruments`](#the-flat-instruments-package) npm package, or fetch the
[raw JSON](#raw-json).

## Where instrument IDs are used

* **Creating scores**: when you create a score with
  [`POST /scores`](https://flat.io/developers/docs/api/reference#tag/Score/operation/createScore),
  each part references an instrument by its `group.instrument` ID.
* **Correcting OMR imports**: when [importing a PDF with OMR](omr/import), the task reports a
  detected `instrumentId` per part, and you can override it by submitting a corrected `instrumentId`.

In both cases the ID must be one of the values listed in the [catalog](#catalog) below.

> **Premium instruments.** Instruments flagged **Premium** require a paid Flat plan. Using one in a
> score created by a free account is rejected. The `premium` flag is included in the package.

## The `@flat/instruments` package

For programmatic access, install the typed, zero-dependency package from npm
([`@flat/instruments`](https://www.npmjs.com/package/@flat/instruments) on npm,
[FlatIO/instruments](https://github.com/FlatIO/instruments) on GitHub):

```bash
npm install @flat/instruments
```

```ts
import { instruments, groups, getInstrument, isValidInstrumentId } from '@flat/instruments'

getInstrument('keyboards.piano')
// => { id: 'keyboards.piano', group: 'keyboards', name: 'Piano',
//      shortname: 'Pno.', type: 'pitched', premium: false }

isValidInstrumentId('brass.trumpet') // => true
isValidInstrumentId('nope.nope')     // => false
```

Each instrument has the shape:

```ts
interface Instrument {
  id: string          // canonical "group.instrument" ID
  group: string       // family ID, e.g. "keyboards"
  name: string        // English display name
  shortname: string   // short staff label, e.g. "Pno."
  type: 'pitched' | 'unpitched'
  premium: boolean    // true means a paid plan is required
}
```

## Raw JSON

Not using JavaScript? The same data is available as plain JSON, bundled in the package at
`@flat/instruments/data/instruments.json` and viewable on GitHub at
[`data/instruments.json`](https://github.com/FlatIO/instruments/blob/master/data/instruments.json).

## Catalog

Some instruments share a display name because a standard version and a premium high-quality (`hq-`)
version exist for the same instrument, for example `brass.trumpet` and `brass.hq-trumpet`. They stay
distinct IDs.

The catalog is rendered in the browser and is not part of this Markdown. The same list, with the
`id`, `group`, `name`, `shortname`, `type` and `premium` of every instrument, is available as JSON at
<https://raw.githubusercontent.com/FlatIO/instruments/master/data/instruments.json>.