---
url: /developers/docs/api/rate-limits.md
description: Discover how the Rate Limits of the Flat Platform's API.
---

# API Rate Limits

The [Flat's REST API](index.html) includes a rate-limiting system that allows us to protect our quality of service. You can contact us if you need [extra quota](mailto:developers@flat.io).

Authenticated requests are limited to 7,200 requests per hour. Note that some accounts may have different quotas depending on their configuration.
Unauthenticated requests, which are tied to the originating IP address rather than a specific user or application, are limited to 1,800 requests per hour.
To maintain the quality and stability of our service, additional rate limits may apply to certain API endpoints or actions.

Some features also have their own concurrency limits, which are separate from these request-per-hour quotas. Optical Music Recognition, for example, processes up to 10 jobs in parallel per account. See the [OMR limits FAQ](/api/omr/faq/limits#what-are-the-limits).

You can check the returned HTTP headers of any API request to see your current rate limit status:

```bash
curl -i https://api.flat.io/v2/me
HTTP/1.1 200 OK
Date: Sat, 25 Mar 2017 17:06:20 GMT
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 7199
X-RateLimit-Reset: 1490465178
```

The headers tell you everything you need to know about your current rate limit status:

Header name | Description
\------------|------------
`X-RateLimit-Limit` | The maximum number of requests that the consumer is permitted to make per hour.
`X-RateLimit-Remaining` | The number of requests remaining in the current rate limit window. This value can be negative if you try to go over the allowed quota.
`X-RateLimit-Reset` | The time at which the current rate limit window resets in [UTC epoch seconds](http://en.wikipedia.org/wiki/Unix_time).

If you need the time in a different format, any modern programming language can get the job done. For example, if you open up the console on your web browser, you can easily get the reset time as a JavaScript Date object.

```javascript
new Date(1490465178 * 1000).toString()
'Sat Mar 25 2017 19:06:18 GMT+0100 (CET)'
```

Once you go over the rate limit you will receive an error response:

```bash
curl -i https://api.flat.io/v2/me
HTTP/1.1 403 Forbidden
X-RateLimit-Limit: 7200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1490465829

{
  "message": "API rate limit exceeded for xx.xxx.xxx.xx",
  "code": "API_RATE_LIMIT_EXCEEDED"
}
```

---

---
url: /developers/docs/embed/api.md
description: Complete reference for the Flat Embed JavaScript SDK
---

# API Reference

The Flat Embed SDK provides 66 methods to control and interact with embedded sheet music.

## Quick Navigation

Press `⌘ + K` (Mac) or `Ctrl + K` (Windows/Linux) to search for specific methods.

## Browse by Category

### [Core Methods](./core.md)

Essential methods for embed initialization and configuration (3 methods)

| Method | Description |
|--------|-------------|
| [`ready()`](./core.md#ready) | Wait for the embed to be ready |
| [`getEmbedConfig()`](./core.md#getembedconfig) | Get the embed configuration |
| [`setEditorConfig()`](./core.md#seteditorconfig) | Set the editor configuration |

### [Event System](./events.md)

Subscribe to and handle embed events (2 methods)

| Method | Description |
|--------|-------------|
| [`on()`](./events.md#on) | Subscribe to a specific event |
| [`off()`](./events.md#off) | Unsubscribe to a specific event |

### [Score Management](./score-management.md)

Methods for loading and exporting scores in various formats (14 methods)

| Method | Description |
|--------|-------------|
| [`loadFlatScore()`](./score-management.md#loadflatscore) | Load a score hosted on Flat |
| [`loadMusicXML()`](./score-management.md#loadmusicxml) | Load a MusicXML score |
| [`loadMIDI()`](./score-management.md#loadmidi) | Load a MIDI score |
| [`loadJSON()`](./score-management.md#loadjson) | Load a Flat JSON score |
| [`loadABC()`](./score-management.md#loadabc) | Load an ABC notation score |
| [`getJSON()`](./score-management.md#getjson) | Get the score in Flat JSON format |
| [`getMusicXML()`](./score-management.md#getmusicxml) | Convert the displayed score to MusicXML |
| [`getPNG()`](./score-management.md#getpng) | Convert the displayed score to PNG image |
| [`getMIDI()`](./score-management.md#getmidi) | Convert the displayed score to MIDI |
| [`getMP3()`](./score-management.md#getmp3) | Convert the displayed score to MP3 audio |
| [`getWAV()`](./score-management.md#getwav) | Convert the displayed score to WAV audio |
| [`getPDF()`](./score-management.md#getpdf) | Convert the displayed score to PDF |
| [`getSVG()`](./score-management.md#getsvg) | Convert the displayed score to SVG |
| [`getFlatScoreMetadata()`](./score-management.md#getflatscoremetadata) | Get the metadata of the score (for scores hosted on Flat) |

### [Display & View](./display.md)

Control the visual presentation of the score (6 methods)

| Method | Description |
|--------|-------------|
| [`fullscreen()`](./display.md#fullscreen) | Toggle fullscreen mode |
| [`print()`](./display.md#print) | Print the score |
| [`getZoom()`](./display.md#getzoom) | Get the current zoom ratio |
| [`setZoom()`](./display.md#setzoom) | Set the zoom ratio |
| [`getAutoZoom()`](./display.md#getautozoom) | Get the auto-zoom status |
| [`setAutoZoom()`](./display.md#setautozoom) | Enable or disable auto-zoom |

### [Playback Control](./playback.md)

Control playback, volume, speed, and metronome settings (10 methods)

| Method | Description |
|--------|-------------|
| [`play()`](./playback.md#play) | Start playback |
| [`pause()`](./playback.md#pause) | Pause playback |
| [`stop()`](./playback.md#stop) | Stop playback |
| [`mute()`](./playback.md#mute) | Mute playback |
| [`getMasterVolume()`](./playback.md#getmastervolume) | Get the current master volume |
| [`setMasterVolume()`](./playback.md#setmastervolume) | Set the master volume |
| [`getMetronomeMode()`](./playback.md#getmetronomemode) | Get the metronome mode |
| [`setMetronomeMode()`](./playback.md#setmetronomemode) | Set the metronome mode |
| [`getPlaybackSpeed()`](./playback.md#getplaybackspeed) | Get the playback speed |
| [`setPlaybackSpeed()`](./playback.md#setplaybackspeed) | Set the playback speed |

### [Parts & Instruments](./parts.md)

Manage individual parts, instruments, and their audio settings (12 methods)

| Method | Description |
|--------|-------------|
| [`getPartVolume()`](./parts.md#getpartvolume) | Get the volume of a specific part |
| [`setPartVolume()`](./parts.md#setpartvolume) | Set the volume of a specific part |
| [`mutePart()`](./parts.md#mutepart) | Mute a specific part |
| [`unmutePart()`](./parts.md#unmutepart) | Unmute a specific part |
| [`setPartSoloMode()`](./parts.md#setpartsolomode) | Enable solo mode for a part |
| [`unsetPartSoloMode()`](./parts.md#unsetpartsolomode) | Disable solo mode for a part |
| [`getPartSoloMode()`](./parts.md#getpartsolomode) | Get the solo mode status of a part |
| [`getPartReverb()`](./parts.md#getpartreverb) | Get the reverb level of a part |
| [`setPartReverb()`](./parts.md#setpartreverb) | Set the reverb level of a part |
| [`getParts()`](./parts.md#getparts) | Get information about all parts |
| [`getDisplayedParts()`](./parts.md#getdisplayedparts) | Get the currently displayed parts |
| [`setDisplayedParts()`](./parts.md#setdisplayedparts) | Set which parts to display |

### [Audio/Video Tracks](./tracks.md)

Synchronize external audio or video with the score (3 methods)

| Method | Description |
|--------|-------------|
| [`setTrack()`](./tracks.md#settrack) | Configure an audio or video track |
| [`useTrack()`](./tracks.md#usetrack) | Enable a previously configured track |
| [`seekTrackTo()`](./tracks.md#seektrackto) | Seek to a position in the audio track |

### [Navigation & Cursor](./navigation.md)

Navigate through the score and control cursor position (6 methods)

| Method | Description |
|--------|-------------|
| [`focusScore()`](./navigation.md#focusscore) | Set focus to the score |
| [`getCursorPosition()`](./navigation.md#getcursorposition) | Get the cursor position |
| [`setCursorPosition()`](./navigation.md#setcursorposition) | Set the cursor position |
| [`goLeft()`](./navigation.md#goleft) | Move cursor left |
| [`goRight()`](./navigation.md#goright) | Move cursor right |
| [`scrollToCursor()`](./navigation.md#scrolltocursor) | Scroll to cursor position |

### [Score Data & Structure](./data.md)

Access and query score structure, measures, notes, and metadata (10 methods)

| Method | Description |
|--------|-------------|
| [`getNbMeasures()`](./data.md#getnbmeasures) | Get the number of measures in the score |
| [`getMeasuresUuids()`](./data.md#getmeasuresuuids) | Get the measure UUIDs of the score |
| [`getMeasureDetails()`](./data.md#getmeasuredetails) | Get detailed measure information |
| [`getNbParts()`](./data.md#getnbparts) | Get the number of parts in the score |
| [`getPartsUuids()`](./data.md#getpartsuuids) | Get the part UUIDs of the score |
| [`getMeasureVoicesUuids()`](./data.md#getmeasurevoicesuuids) | Get voice UUIDs for a specific measure |
| [`getMeasureNbNotes()`](./data.md#getmeasurenbnotes) | Get the number of notes in a voice |
| [`getNoteData()`](./data.md#getnotedata) | Get information about a specific note |
| [`playbackPositionToNoteIdx()`](./data.md#playbackpositiontonoteidx) | Convert playback position to note index |
| [`getNoteDetails()`](./data.md#getnotedetails) | Get note details at cursor position |

## All Methods

| Method | Description |
|--------|-------------|
| [`focusScore()`](./navigation.md#focusscore) | Set focus to the score |
| [`fullscreen()`](./display.md#fullscreen) | Toggle fullscreen mode |
| [`getAutoZoom()`](./display.md#getautozoom) | Get the auto-zoom status |
| [`getCursorPosition()`](./navigation.md#getcursorposition) | Get the cursor position |
| [`getDisplayedParts()`](./parts.md#getdisplayedparts) | Get the currently displayed parts |
| [`getEmbedConfig()`](./core.md#getembedconfig) | Get the embed configuration |
| [`getFlatScoreMetadata()`](./score-management.md#getflatscoremetadata) | Get the metadata of the score (for scores hosted on Flat) |
| [`getJSON()`](./score-management.md#getjson) | Get the score in Flat JSON format |
| [`getMasterVolume()`](./playback.md#getmastervolume) | Get the current master volume |
| [`getMeasureDetails()`](./data.md#getmeasuredetails) | Get detailed measure information |
| [`getMeasureNbNotes()`](./data.md#getmeasurenbnotes) | Get the number of notes in a voice |
| [`getMeasuresUuids()`](./data.md#getmeasuresuuids) | Get the measure UUIDs of the score |
| [`getMeasureVoicesUuids()`](./data.md#getmeasurevoicesuuids) | Get voice UUIDs for a specific measure |
| [`getMetronomeMode()`](./playback.md#getmetronomemode) | Get the metronome mode |
| [`getMIDI()`](./score-management.md#getmidi) | Convert the displayed score to MIDI |
| [`getMP3()`](./score-management.md#getmp3) | Convert the displayed score to MP3 audio |
| [`getMusicXML()`](./score-management.md#getmusicxml) | Convert the displayed score to MusicXML |
| [`getNbMeasures()`](./data.md#getnbmeasures) | Get the number of measures in the score |
| [`getNbParts()`](./data.md#getnbparts) | Get the number of parts in the score |
| [`getNoteData()`](./data.md#getnotedata) | Get information about a specific note |
| [`getNoteDetails()`](./data.md#getnotedetails) | Get note details at cursor position |
| [`getPartReverb()`](./parts.md#getpartreverb) | Get the reverb level of a part |
| [`getParts()`](./parts.md#getparts) | Get information about all parts |
| [`getPartSoloMode()`](./parts.md#getpartsolomode) | Get the solo mode status of a part |
| [`getPartsUuids()`](./data.md#getpartsuuids) | Get the part UUIDs of the score |
| [`getPartVolume()`](./parts.md#getpartvolume) | Get the volume of a specific part |
| [`getPDF()`](./score-management.md#getpdf) | Convert the displayed score to PDF |
| [`getPlaybackSpeed()`](./playback.md#getplaybackspeed) | Get the playback speed |
| [`getPNG()`](./score-management.md#getpng) | Convert the displayed score to PNG image |
| [`getSVG()`](./score-management.md#getsvg) | Convert the displayed score to SVG |
| [`getWAV()`](./score-management.md#getwav) | Convert the displayed score to WAV audio |
| [`getZoom()`](./display.md#getzoom) | Get the current zoom ratio |
| [`goLeft()`](./navigation.md#goleft) | Move cursor left |
| [`goRight()`](./navigation.md#goright) | Move cursor right |
| [`loadABC()`](./score-management.md#loadabc) | Load an ABC notation score |
| [`loadFlatScore()`](./score-management.md#loadflatscore) | Load a score hosted on Flat |
| [`loadJSON()`](./score-management.md#loadjson) | Load a Flat JSON score |
| [`loadMIDI()`](./score-management.md#loadmidi) | Load a MIDI score |
| [`loadMusicXML()`](./score-management.md#loadmusicxml) | Load a MusicXML score |
| [`mute()`](./playback.md#mute) | Mute playback |
| [`mutePart()`](./parts.md#mutepart) | Mute a specific part |
| [`off()`](./events.md#off) | Unsubscribe to a specific event |
| [`on()`](./events.md#on) | Subscribe to a specific event |
| [`pause()`](./playback.md#pause) | Pause playback |
| [`play()`](./playback.md#play) | Start playback |
| [`playbackPositionToNoteIdx()`](./data.md#playbackpositiontonoteidx) | Convert playback position to note index |
| [`print()`](./display.md#print) | Print the score |
| [`ready()`](./core.md#ready) | Wait for the embed to be ready |
| [`scrollToCursor()`](./navigation.md#scrolltocursor) | Scroll to cursor position |
| [`seekTrackTo()`](./tracks.md#seektrackto) | Seek to a position in the audio track |
| [`setAutoZoom()`](./display.md#setautozoom) | Enable or disable auto-zoom |
| [`setCursorPosition()`](./navigation.md#setcursorposition) | Set the cursor position |
| [`setDisplayedParts()`](./parts.md#setdisplayedparts) | Set which parts to display |
| [`setEditorConfig()`](./core.md#seteditorconfig) | Set the editor configuration |
| [`setMasterVolume()`](./playback.md#setmastervolume) | Set the master volume |
| [`setMetronomeMode()`](./playback.md#setmetronomemode) | Set the metronome mode |
| [`setPartReverb()`](./parts.md#setpartreverb) | Set the reverb level of a part |
| [`setPartSoloMode()`](./parts.md#setpartsolomode) | Enable solo mode for a part |
| [`setPartVolume()`](./parts.md#setpartvolume) | Set the volume of a specific part |
| [`setPlaybackSpeed()`](./playback.md#setplaybackspeed) | Set the playback speed |
| [`setTrack()`](./tracks.md#settrack) | Configure an audio or video track |
| [`setZoom()`](./display.md#setzoom) | Set the zoom ratio |
| [`stop()`](./playback.md#stop) | Stop playback |
| [`unmutePart()`](./parts.md#unmutepart) | Unmute a specific part |
| [`unsetPartSoloMode()`](./parts.md#unsetpartsolomode) | Disable solo mode for a part |
| [`useTrack()`](./tracks.md#usetrack) | Enable a previously configured track |

---

---
url: /developers/docs/embed/api/tracks.md
description: Synchronize external audio or video with the score
---

# Audio/Video Tracks

Synchronize external audio or video with the score

## Methods

### setTrack() {#settrack}

Configure an audio or video track

Sets up a new audio or video track to synchronize with the score playback. This allows you to play backing tracks, reference recordings, or video alongside the score.

```typescript
setTrack(parameters: ScoreTrackConfiguration): Promise<void>
```

**Parameters:**

* `parameters` - `ScoreTrackConfiguration`

**ScoreTrackConfiguration**

Configuration for audio/video track synchronization with score

Properties:

* `id`: `string` - Unique identifier for this track configuration
* `type`: `ScoreTrackType` - The type of media track
* `url` *(optional)*: `string` - URL of the media file (required for 'soundcloud' and 'audio' types)
* `mediaId` *(optional)*: `string` - Video/media identifier (required for 'youtube' and 'vimeo' types)
* `totalTime` *(optional)*: `number` - Total duration in seconds (required for 'external' type)
* `synchronizationPoints`: `ScoreTrackSynchronizationPoint[]` - List of synchronization points between score and media

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the track configuration is invalid

**Example:**

```typescript
const embed = new Embed('container', config);
await embed.setTrack({
  id: 'backing-track',
  type: 'audio',
  url: 'https://example.com/track.mp3',
  synchronizationPoints: [
    { type: 'measure', measure: 0, time: 0 }
  ]
});
```

**See also:**

* [`useTrack()`](#usetrack) - Enable a configured track
* [`seekTrackTo()`](#seektrackto) - Seek to a position in the track

***

### useTrack() {#usetrack}

Enable a previously configured track

Activates a track that was previously configured with `setTrack()`. Only one track can be active at a time.

```typescript
useTrack(parameters: { id: string; }): Promise<void>
```

**Parameters:**

* `parameters.id` - `string`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the track ID is invalid or track cannot be enabled

**Examples:**

```typescript
// Enable a configured backing track
await embed.useTrack({ id: 'backing-track-1' });
```

**See also:**

* [`setTrack()`](#settrack) - Configure a new track

***

### seekTrackTo() {#seektrackto}

Seek to a position in the audio track

Moves the playback position of the currently active audio/video track to a specific time. This is useful for synchronizing with score playback or jumping to specific sections.

```typescript
seekTrackTo(parameters: { time: number; }): Promise<void>
```

**Parameters:**

* `parameters.time` - `number`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If no track is active or seeking fails

**Examples:**

```typescript
// Seek to 30 seconds
await embed.seekTrackTo({ time: 30 });
```

**See also:**

* [`setTrack()`](#settrack) - Configure a track
* [`useTrack()`](#usetrack) - Enable a track

***

---

---
url: /developers/docs/api/omr/import.md
description: >-
  Import a PDF of sheet music into Flat with Optical Music Recognition (OMR)
  through a single unified endpoint. Send the file to POST /scores, poll the
  task, and get an editable score.
---

# Auto simple PDF import

The simplest way to run OMR is the regular score import: send a PDF to
[`POST /scores`](https://flat.io/developers/docs/api/reference#tag/Score/operation/createScore) and
Flat imports it as an editable score. This is the **same endpoint** you use for MusicXML and MIDI, so
one code path handles every format. It is the right choice when you just want a score in the Library
and do not need progress updates or a review step.

Unlike MusicXML or MIDI (which import synchronously), OMR takes some time, so a PDF import is handled
as an **asynchronous task**:

1. You start the import with `POST /scores`. The API replies immediately with a **task**.
2. You **poll the task** until it is done.
3. Once done, you retrieve (and optionally export) the newly created score.

In this page:

* [Prerequisites](#prerequisites)
* [Step 1. Start the import](#step-1-start-the-import)
* [Step 2. Poll the task](#step-2-poll-the-task)
* [Step 3. Retrieve the imported score](#step-3-retrieve-the-imported-score)
* [Error handling](#error-handling)
* [Usage and billing](#usage-and-billing)
* [Related](#related)

> Need live progress, an instrument-correction review step, MusicXML-only output, or incremental
> (mobile) capture? Use the [Interactive Jobs API](/api/omr/jobs) instead. New to OMR? Start with the
> [OMR overview](/api/omr/).

## Prerequisites

* **Authentication.** A [Personal Access Token](/api/authentication#personal-access-tokens) works
  nicely to get started quickly. If you are building an OAuth2 app, request the `scores` scope (to
  create the score), the `omr` scope (to run OMR), and the `tasks.readonly` scope (to poll the task).
* **File format.** Only **PDF** (`application/pdf`) files go through OMR.
* **Encoding.** Binary PDF data must be Base64-encoded and sent in the `data` property, with
  `dataEncoding` set to `base64`.
* **Opt in to tasks.** You must set `supportsTasks: true` in the request. Without it, a PDF import is
  rejected.

## Step 1. Start the import

Create the score with
[`POST /scores`](https://flat.io/developers/docs/api/reference#tag/Score/operation/createScore),
providing the Base64-encoded PDF and `supportsTasks: true`:

::: code-group

```bash [curl]
curl -X POST 'https://api.flat.io/v2/scores' \
  -H 'Authorization: Bearer <my_api_personal_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "My imported score",
    "filename": "my-sheet-music.pdf",
    "data": "<base64-encoded-pdf>",
    "dataEncoding": "base64",
    "supportsTasks": true
  }'
```

```js [JavaScript]
import { readFileSync } from 'node:fs';

const res = await fetch('https://api.flat.io/v2/scores', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <my_api_personal_access_token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'My imported score',
    filename: 'my-sheet-music.pdf',
    data: readFileSync('my-sheet-music.pdf').toString('base64'),
    dataEncoding: 'base64',
    supportsTasks: true,
  }),
});

// A PDF import returns 202 with a task; MusicXML/MIDI return 200 with the score.
const task = await res.json();
```

```python [Python]
import base64, requests

with open("my-sheet-music.pdf", "rb") as f:
    data = base64.b64encode(f.read()).decode()

res = requests.post(
    "https://api.flat.io/v2/scores",
    headers={"Authorization": "Bearer <my_api_personal_access_token>"},
    json={
        "title": "My imported score",
        "filename": "my-sheet-music.pdf",
        "data": data,
        "dataEncoding": "base64",
        "supportsTasks": True,
    },
)

# A PDF import returns 202 with a task; MusicXML/MIDI return 200 with the score.
task = res.json()
```

:::

Because the PDF requires OMR, the API responds with **`202 Accepted`** and a task instead of the
score:

```json
{
  "id": "5e0a59c0f1e6b8000868e0c1",
  "type": "import-omr",
  "state": "created",
  "progress": {
    "percent": 0
  },
  "creationDate": "2026-06-16T09:24:00.000Z"
}
```

Keep the task `id`. You will use it to follow the import.

::: tip Branch on the HTTP status
MusicXML and MIDI imports are processed synchronously and still return **`200 OK`** with the full
score. A PDF import returns **`202 Accepted`** with a task. Have your client branch on the status
code: `200` means the score is ready, `202` means follow the task flow below.
:::

## Step 2. Poll the task

Fetch the task with
[`GET /tasks/{task}`](https://flat.io/developers/docs/api/reference#tag/Task/operation/getTask) until
it completes:

::: code-group

```bash [curl]
curl -H 'Authorization: Bearer <my_api_personal_access_token>' \
  https://api.flat.io/v2/tasks/5e0a59c0f1e6b8000868e0c1
```

```js [JavaScript]
async function waitForTask(taskId, token) {
  while (true) {
    const res = await fetch(`https://api.flat.io/v2/tasks/${taskId}`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const task = await res.json();
    if (['done', 'error', 'canceled'].includes(task.state)) return task;
    await new Promise((r) => setTimeout(r, 3000)); // poll every few seconds
  }
}
```

```python [Python]
import time, requests

def wait_for_task(task_id, token):
    while True:
        task = requests.get(
            f"https://api.flat.io/v2/tasks/{task_id}",
            headers={"Authorization": f"Bearer {token}"},
        ).json()
        if task["state"] in ("done", "error", "canceled"):
            return task
        time.sleep(3)  # poll every few seconds
```

:::

The task moves through the following states:

| `state`    | Meaning                                                        |
|:-----------|:---------------------------------------------------------------|
| `created`  | The task is queued and waiting to be processed.                |
| `blocked`  | The task is waiting on something else before it can run.       |
| `doing`    | OMR processing is in progress (see `progress.percent`).        |
| `done`     | The score has been imported. The `score` field is set.         |
| `canceled` | The task was canceled and will not complete.                   |
| `error`    | Processing failed. See `result.error`.                         |

`created`, `blocked`, and `doing` are transient; `done`, `canceled`, and `error` are terminal. Stop
polling on any of the three terminal states, not just `done` and `error`, or a canceled task will
loop forever.

The fields you care about while polling:

| Field             | Description                                                              |
|:------------------|:------------------------------------------------------------------------|
| `id`              | Unique identifier of the task.                                           |
| `type`            | `import-omr` for an OMR import.                                          |
| `state`           | Current state of the task (see table above).                            |
| `progress.percent`| Progression of the task, from `0` to `100`.                             |
| `score`           | The unique identifier of the imported score (set once `state` is `done`).|
| `result.error`    | A human-readable error message when `state` is `error`.                 |

A completed task looks like:

```json
{
  "id": "5e0a59c0f1e6b8000868e0c1",
  "type": "import-omr",
  "state": "done",
  "score": "5e0a5b2cf1e6b8000868e0d4",
  "revision": "5e0a5b2cf1e6b8000868e0d5",
  "progress": {
    "percent": 100
  },
  "creationDate": "2026-06-16T09:24:00.000Z",
  "doneDate": "2026-06-16T09:25:12.000Z"
}
```

Poll every few seconds rather than in a tight loop, and respect our [rate limits](/api/rate-limits).

## Step 3. Retrieve the imported score

Once the task is `done`, read the `score` field for the new score identifier, then fetch the full
score details with
[`GET /scores/{score}`](https://flat.io/developers/docs/api/reference#tag/Score/operation/getScore):

::: code-group

```bash [curl]
curl -H 'Authorization: Bearer <my_api_personal_access_token>' \
  https://api.flat.io/v2/scores/5e0a5b2cf1e6b8000868e0d4
```

```js [JavaScript]
const res = await fetch(`https://api.flat.io/v2/scores/${task.score}`, {
  headers: { Authorization: `Bearer ${token}` },
});
const score = await res.json();
```

```python [Python]
score = requests.get(
    f"https://api.flat.io/v2/scores/{task['score']}",
    headers={"Authorization": f"Bearer {token}"},
).json()
```

:::

From there, the score behaves like any other Flat score. You can also **export** it to other formats,
for example **MusicXML**, **MP3**, or **MIDI**, using the
[score export endpoints](https://flat.io/developers/docs/api/reference#tag/Score/operation/createScoreRevisionExport).
Exporting follows the **same asynchronous task pattern** as the import: create the export task, poll
[`GET /tasks/{task}`](https://flat.io/developers/docs/api/reference#tag/Task/operation/getTask), then
download the result from the task's `result.url` once it is `done`.

## Error handling

| Status | When it happens                                                                                       |
|:-------|:-----------------------------------------------------------------------------------------------------|
| `400`  | Bad request, for example a missing `supportsTasks: true`, or an invalid or password-protected PDF.    |
| `402`  | The account is over quota, the OMR feature is not included in the plan, or there are not enough credits. See [Usage and billing](#usage-and-billing).|
| `403`  | The OAuth2 token is missing the `omr` scope (`OMR_SCOPE_REQUIRED`), or the `scores` scope needed to create the score. |

In addition, a task may finish in the `error` state. When that happens, inspect `result.error` for a
description of what went wrong. See the [Errors](/api/errors) page for the general error format, and
the [OMR overview](/api/omr/#errors) for the full list of recognition failure codes.

## Usage and billing

OMR imports consume the **credits of the Flat account that owns the token**, charged per page:
**1 credit is 1 page**, drawn from the same pool as the Flat web, desktop, and mobile apps. With a
Personal Access Token that is your own account; with OAuth2, the account of the user who authorized
your app. Credits come from the account's Flat or Flat for Education subscription allowance first,
then from credit packs bought on
[flat.io/settings/ai-credits](https://flat.io/settings/ai-credits?ref=dev-docs-omr). Out of credits
means a `402`. See [Capabilities and credits](/api/omr/#capabilities-and-credits) for the full
picture, including how to read `remainingCredits` before you start an import, and the
[credits and billing FAQ](/api/omr/faq/credits) for refunds, packs, and volume pricing.

If you need higher volumes or have specific requirements, reach out to us at
<developers@flat.io>. We are happy to discuss the best setup for your use
case.

## Related

* [OMR overview](/api/omr/) - scopes, credits, capabilities, and error codes.
* [Interactive Jobs API](/api/omr/jobs) - progress, the instrument-review step, and MusicXML output.
* [FAQ](/api/omr/faq/) - credits and billing, limits, recognition quality, and commercial use.
* [API Reference: `createScore`](https://flat.io/developers/docs/api/reference#tag/Score/operation/createScore)
  and [`getTask`](https://flat.io/developers/docs/api/reference#tag/Task/operation/getTask).
* [Authentication](/api/authentication).

---

---
url: /developers/docs/lti/usage.md
description: >-
  Flat is an LTI Provider. If you are using an LTI consumer, check out our
  information on how you can use Flat with your product.
---

# Certified LTI Provider

[Flat for Education is a certified LTI Provider](https://site.imsglobal.org/certifications/tutteo-ltd/flat-for-education), ensuring seamless interaction with any LTI Consumer/Platform. If your institution uses an LTI-compatible platform, you can easily integrate it with [Flat for Education](https://flat.io/edu).

## [LTI 1.3 (Advantage)](./lti-1.3)

LTI 1.3 is our recommended integration method. We support the full [LTI Advantage](https://www.imsglobal.org/lti-advantage-overview) suite, including Deep Linking, Assignment & Grade Services, Names and Role Provisioning Services, and Submission Review.

[Read the LTI 1.3 documentation](./lti-1.3)

## [LTI 1.1 (Legacy)](./lti-1.1)

We continue to support LTI 1.0 and 1.1 for platforms that have not yet migrated to LTI 1.3. We recommend upgrading to LTI 1.3 for improved security and features.

[Read the LTI 1.1 documentation](./lti-1.1)

## Contact

For questions about our LTI integration or to discuss a custom integration, please contact us at <developers@flat.io>.

---

---
url: /developers/docs/embed/api/core.md
description: Essential methods for embed initialization and configuration
---

# Core Methods

Essential methods for embed initialization and configuration

## Methods

### ready() {#ready}

Wait for the embed to be ready

Returns a promise that resolves when the embed iframe has fully loaded and communication with the Flat embed has been established. This method is automatically called by all other embed methods, so you typically don't need to call it directly. However, it can be useful when you want to know exactly when the embed is ready without performing any other action.

```typescript
ready(): Promise<void>
```

**Returns:** `Promise<void>`

**Examples:**

```typescript
// Explicitly wait for embed to be ready
const embed = new Embed('container', {
  score: '56ae21579a127715a02901a6'
});
await embed.ready();
console.log('Embed is now ready!');
```

**Note:** All embed methods automatically call ready() internally, so explicit calls are optional

***

### getEmbedConfig() {#getembedconfig}

Get the embed configuration

Retrieves the complete configuration object for the embed, including display settings, permissions, editor configuration, and enabled features.

```typescript
getEmbedConfig(): Promise<Record<string, unknown>>
```

**Returns:** `Promise<Record<string, unknown>>`

**Throws:**

* `Error` - If the configuration cannot be retrieved

**Examples:**

```typescript
// Get current embed configuration
const config = await embed.getEmbedConfig();
console.log(`Mode: ${config.mode}`);
console.log(`Controls enabled: ${config.controlsPlay}`);
```

***

### setEditorConfig() {#seteditorconfig}

Set the editor configuration

Updates the editor configuration for the embed. These settings control various aspects of the editor interface and behavior. The configuration is applied when the next score is loaded.

```typescript
setEditorConfig(editor: Record<string, unknown>): Promise<void>
```

**Parameters:**

* `editor` - `Record<string, unknown>`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the configuration is invalid

**Example:**

```typescript
const embed = new Embed('container', config);
await embed.setEditorConfig('value');
```

**Note:** This configuration persists across score loads until changed

***

---

---
url: /developers/docs/embed/api/display.md
description: Control the visual presentation of the score
---

# Display & View

Control the visual presentation of the score

## Methods

### fullscreen() {#fullscreen}

Toggle fullscreen mode

Switches the embed in or out of fullscreen mode. When in fullscreen, the embed expands to fill the entire screen, providing an immersive view of the score.

```typescript
fullscreen(active: boolean): Promise<void>
```

**Parameters:**

* `active` - `boolean`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If fullscreen mode cannot be toggled (e.g., browser restrictions)

**Examples:**

```typescript
// Enter fullscreen mode
await embed.fullscreen(true);
```

```typescript
// Exit fullscreen mode
await embed.fullscreen(false);
```

**Note:** Fullscreen requests may require user interaction due to browser policies

***

### print() {#print}

Print the score

Opens the browser's print dialog to print the currently loaded score. The score is formatted for optimal printing with proper page breaks and sizing.

```typescript
print(): Promise<void>
```

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If no score is loaded or printing cannot be initiated

**Examples:**

```typescript
// Print the current score
await embed.print();
```

**Note:** The actual printing is controlled by the browser's print dialog

***

### getZoom() {#getzoom}

Get the current zoom ratio

Retrieves the current zoom level of the score display. The zoom level affects how large the notation appears on screen.

```typescript
getZoom(): Promise<number>
```

**Returns:** `Promise<number>`

**Throws:**

* `Error` - If the zoom level cannot be retrieved

**Example:**

```typescript
const embed = new Embed('container', config);
const zoom = await embed.getZoom();
console.log(zoom);
```

**See also:**

* [`setZoom()`](#setzoom) - Set the zoom level
* [`getAutoZoom()`](#getautozoom) - Check if auto-zoom is enabled

***

### setZoom() {#setzoom}

Set the zoom ratio

Sets a specific zoom level for the score display. Setting a manual zoom level automatically disables auto-zoom mode.

```typescript
setZoom(zoom: number): Promise<number>
```

**Parameters:**

* `zoom` - `number`

**Returns:** `Promise<number>`

**Throws:**

* `Error` - If the zoom value is outside the valid range

**Examples:**

```typescript
// Set zoom to 150%
await embed.setZoom(1.5);
```

**See also:**

* [`getZoom()`](#getzoom) - Get current zoom level
* [`setAutoZoom()`](#setautozoom) - Enable automatic zoom

***

### getAutoZoom() {#getautozoom}

Get the auto-zoom status

Checks whether auto-zoom mode is currently enabled. When auto-zoom is active, the score automatically adjusts its zoom level to fit the available space.

```typescript
getAutoZoom(): Promise<boolean>
```

**Returns:** `Promise<boolean>`

**Throws:**

* `Error` - If the status cannot be retrieved

**Example:**

```typescript
const embed = new Embed('container', config);
const autoZoom = await embed.getAutoZoom();
console.log(autoZoom);
```

**See also:**

* [`setAutoZoom()`](#setautozoom) - Enable or disable auto-zoom

***

### setAutoZoom() {#setautozoom}

Enable or disable auto-zoom

Controls the auto-zoom feature. When enabled, the score automatically adjusts its zoom level to fit the available container width. When disabled, the zoom level remains fixed at the last set value.

```typescript
setAutoZoom(state: boolean): Promise<boolean>
```

**Parameters:**

* `state` - `boolean`

**Returns:** `Promise<boolean>`

**Throws:**

* `Error` - If auto-zoom cannot be toggled

**Examples:**

```typescript
// Enable auto-zoom
await embed.setAutoZoom(true);
```

**See also:**

* [`getAutoZoom()`](#getautozoom) - Check current auto-zoom status
* [`setZoom()`](#setzoom) - Set a specific zoom level

***

---

---
url: /developers/docs/embed/changelog.md
description: Changelog for Flat's JavaScript/TypeScript Embed SDK (flat-embed)
---

# Embed SDK Changelog

## 2026-04-02: v2.12.1

* Fixed TypeScript declaration output path broken by TypeScript 6 upgrade

## 2026-04-02: v2.12.0

* Added method `getSVG` for SVG export

## 2026-03-19: v2.11.0

* Added method `loadABC` for ABC notation loading

## 2026-03-03: v2.10.0

* Added `editorInterface` parameter to `EmbedUrlParameters` type (`'desktop'` | `'mobile'`)

## 2026-02-16: v2.9.0

* Added methods `getMP3` and `getWAV` for audio export
* Added event `exportProgress`

## 2026-02-06: v2.8.0

* Added method `getPDF` for PDF export

## 2025-12-29: v2.7.0

* Added event `embedSize`

## 2025-10-22: v2.6.0

* Added support for new locales: Danish (`da`), Finnish (`fi`), Filipino (`fil`), French Canadian (`fr-CA`), Hindi (`hi`), Indonesian (`id`), Malay (`ms`), Norwegian Bokmål (`nb`), Traditional Chinese Hong Kong (`zh-HK`), and Traditional Chinese Taiwan (`zh-TW`)

## 2025-09-23: v2.5.1

* NPM Trusted publishing

## 2025-08-04: v2.5.0

* Enhanced TypeScript types and new documentation

## 2025-04-10: v2.4.1

* Added missing `mode` to `EmbedUrlParameters` TypeScript interface

## 2025-03-10: v2.4.0

* Added method `loadMIDI`

## 2024-01-03: v2.3.0

* Added `lazy` option to add a `loading="lazy"` attribute to the created iframe

## 2023-11-24: v2.2.0

* Added embed parameter `userId`

## 2023-10-02: v2.1.0

* Added methods:
  * `getNbParts`
  * `getPartsUuids`
  * `getMeasureVoicesUuids`
  * `getMeasureNbNotes`
  * `getNoteData`
  * `playbackPositionToNoteIdx`
* Added URL parameter:
  * `noAudio` to disable audio playback
* Fixed `setMasterVolume` not calling the correct underlying method

## 2023-09-27: v2.0.1

* Fixed package `exports` compatibility with Webpack 5

## 2023-09-27: v2.0.0

**Breaking changes**:

* Removed support for jQuery in constructor. Migration:

```js
var container = $('#embed-container');
var embed = new Flat.Embed(container[0], {
  // your options
});
```

**New features**:

* Added support for TypeScript in published NPM module
* Publishing separate ES & UMD builds

## 2023-04-04: v1.5.1

* Add `allow: autoplay` on created iframes.

## 2023-03-08: v1.5.0

* Add methods:
  * `getNbMeasures`
  * `getMeasuresUuids`
  * `goLeft`
  * `goRight`
  * `getMetronomeMode`
  * `setMetronomeMode`
  * `getPlaybackSpeed`
  * `setPlaybackSpeed`
  * `scrollToCursor`

## 2022-04-22: v1.4.1

* Fixed compatibility with Vue 3

## 2021-04-28: v1.4.0

* Update `loadFlatScore` to support `sharingKey`
* Add methods to dynamically set audio tracks: `setTrack`, `useTrack` and `seekTrackTo`

## 2020-05-06: Available with all previous SDKs since 0.4.0

* new options for `getPNG`
  * `layout` with `track` or `page` (default: `track`)
  * `dpi`

## 2020-02-24: v1.3.0

* Add methods:
  * `getMasterVolume`
  * `setMasterVolume`
  * `getPartVolume`
  * `setPartVolume`
  * `mutePart`
  * `unmutePart`
  * `setPartSoloMode`
  * `unsetPartSoloMode`
  * `getPartSoloMode`
  * `getPartReverb`
  * `setPartReverb`
  * `getMeasureDetails`
  * `getNoteDetails`
* Add events:
  * `noteDetails`
  * `measureDetails`
  * `cursorContext`

## 2020-01-07: v1.2.0

* Add methods: `getParts`, `getDisplayedParts` and `setDisplayedParts`

## 2019-05-13: v1.1.0

* Support for MIDI Output

## 2019-05-05: v1.0.0

* Host on our CDN (`https://prod.flat-cdn.com/embed-js/${VERSION}/embed.min.js`)

## 2018-11-29: v0.11.0

* Add `getMIDI` update
* Update `getMusicXML` to support new returned Uint8Array format (no more `.data`, response is at top level)
* Update cursor: `voiceIdx` is now `voiceIdxInStaff`

## 2018-11-23: v0.10.0

* Update for the embed release
* Use new CDN endpoint `flat-embed.com` by default
* Remove deprecated `edit` action & event
* Remove `setNoteColor` method

## 2017-11-10: v0.9.0

* Add method: `mute`

## 2017-10-19: v0.8.0

* Switch from babel-preset-es2015 to babel-preset-env
* Remove rollup-plugin-hypothetical and babel-plugin-transform-runtime

## 2017-08-08: v0.7.0

* Add method: `setNoteColor`

## 2017-08-03: v0.6.0

* Add methods: `getCursorPosition` and `setCursorPosition`

## 2017-07-07: v0.5.0

* Add method: `focusScore`
* New property `defaultMode` in editor config

## 2017-07-05: v0.4.0

* Add method: `getPNG`

## 2017-05-03: v0.3.0

* Add methods: `getEmbedConfig`, `setEditorConfig`, `edit`
* Add events: `edit`

## 2017-04-21: v0.2.0

* Add methods: `getAutoZoom`, `setAutoZoom`, `loadMusicXML`, `getMusicXML`
* Add events: `scoreLoaded`, `cursorPosition`, `rangeSelection`, `pause`, `stop`, `fullscreen`, `print`
* Add integration tests

## 2017-04-21: v0.1.0

* Initial release

---

---
url: /developers/docs/embed/javascript-editor.md
description: Allow your website visitor and users to edit any sheet music
---

# Embeddable music notation editor

You can use our [JavaScript SDK](javascript) to embed our editor anywhere. Load any MusicXML files or scores hosted on Flat, edit them directly on your webpage or app, then export them to MusicXML or MIDI directly in JavaScript. The embeddable editor requires an [Embed plan](https://flat.io/embed) that includes edit mode. Applications on the free plan can display scores but not edit them: they fall back to `view` mode.

::: warning The `appId` in these examples is ours, not yours
The examples on this page use a demo `appId` on a plan that includes edit mode, so they open the
editor. Replacing it with the `appId` of an application without edit mode makes the same code render
a read-only score: `mode: 'edit'` falls back to `view` and no error is raised. Check the plan of your
application in your [developer settings](https://flat.io/developers/apps) if the editor does not appear.
:::

You can also use our [code generator](https://flat.io/developers/embed/generator) to generate the JavaScript initializing our embeddable editor with the customizations options you want.

Here is a simple example using the same score [from our introduction](/embed/) as an editable template you can export once edited.

Here is how the example is done. [You can view and edit this complete example on Code Sandbox](https://codesandbox.io/s/github/FlatIO/embed-demo-editor-simple).

```html
<div id="embed-container"></div>
<button id="export-xml">Export to MusicXML</button>

<script src="https://prod.flat-cdn.com/embed-js/v1.5.1/embed.min.js"></script>
<script>
  var container = document.getElementById('embed-container');
  var embed = new Flat.Embed(container, {
    // The score hosted on Flat we use here as template.
    // You can also use `embed.loadMusicXML(file)` to load your files on the fly
    score: '56ae21579a127715a02901a6',
    embedParams: {
      mode: 'edit',
      appId: '59e7684b476cba39490801c2',
      // Simple customizations
      branding: false,
      controlsPosition: 'top',
    }
  });

  // Export the file when we click on the button
  document.getElementById('export-xml').addEventListener('click', function () {
    embed.getMusicXML({ compressed: true }).then(function (buffer) {
     // Exported MusicXML file in `buffer`
    });
  });
</script>
```

## Real-life example

Another good example of application using this SDK with the editor is [our Google Docs add-ons](https://gsuite.google.com/marketplace/app/flat_for_docs/324260072797). They load some MusicXML templates, then export the score to MusicXML and PNG once the creation is done.

---

---
url: /developers/docs/embed/api/events.md
description: Subscribe to and handle embed events
---

# Event System

Subscribe to and handle embed events. Events are broadcasted following actions made by the end-user or you with the JavaScript API.

## Event Methods

### on() {#on}

Subscribe to a specific event. When an event includes some data, this data will be available in the first parameter of the listener callback.

```typescript
on(event: EmbedEventName, callback: () => void): void
```

**Parameters:**

* `event` - `EmbedEventName` - The name of the event to subscribe to
* `callback` - `() => void` - The callback function to execute when the event is triggered

**Returns:** `void`

**Example:**

```typescript
const embed = new Embed('container', config);

// Subscribe to play event
embed.on('play', () => {
  console.log('Playback started');
});

// Subscribe to cursor position changes
embed.on('cursorPosition', (position) => {
  console.log('Cursor moved to:', position);
});
```

***

### off() {#off}

Unsubscribe from a specific event. If no callback is provided, all listeners for the event will be removed.

```typescript
off(event: EmbedEventName, callback?: () => void): void
```

**Parameters:**

* `event` - `EmbedEventName` - The name of the event to unsubscribe from
* `callback` *(optional)* - `() => void` - The specific callback to remove

**Returns:** `void`

**Example:**

```typescript
const embed = new Embed('container', config);

// Define a callback
const playHandler = () => console.log('Playback started');

// Subscribe
embed.on('play', playHandler);

// Unsubscribe specific callback
embed.off('play', playHandler);

// Remove all listeners for an event
embed.off('play');
```

***

## Available Events

### scoreLoaded

This event is triggered once a new score has been loaded. This event doesn't include any data.

```typescript
embed.on('scoreLoaded', () => {
  console.log('Score has been loaded');
});
```

### cursorPosition

This event is triggered when the position of the user's cursor changes.

```typescript
embed.on('cursorPosition', (position) => {
  console.log('Cursor position:', position);
  // {
  //   "partIdx": 0,
  //   "staffIdx": 1,
  //   "voiceIdx": 0,
  //   "measureIdx": 2,
  //   "noteIdx": 1
  // }
});
```

### cursorContext

This event is triggered when the position or context of the user's cursor changes.

```typescript
embed.on('cursorContext', (context) => {
  console.log('Cursor context:', context);
  // {
  //   "isRest": false,
  //   "isGrace": false,
  //   "isUnpitchedPart": false,
  //   "isPitchedPart": true,
  //   "isPitched": true,
  //   "isChord": true,
  //   "isTab": false,
  //   "hasTab": true,
  //   "hasTabFrame": false,
  //   "isEndOfScore": false,
  //   "isSameLineThanNextNote": false,
  //   "hasSlashInConnection": false,
  //   "canTieWithNextNote": false,
  //   "canSwitchEnharmonic": false,
  //   "isNextRest": false,
  //   "hasTie": false,
  //   "isHeadTied": false
  // }
});
```

### measureDetails

This event is triggered when the position or context of the user's cursor changes. The payload is the same as [`getMeasureDetails()`](./data.md#getmeasuredetails).

```typescript
embed.on('measureDetails', (details) => {
  console.log('Measure details:', details);
  // {
  //   "clef": { "sign": "G", "line": 2, "clef-octave-change": -1 },
  //   "key": { "fifths": 0 },
  //   "time": { "beats": 4, "beat-type": 4 },
  //   "displayedTime": { "beats": 4, "beat-type": 4 },
  //   "tempo": { "qpm": 80, "bpm": 80, "durationType": "quarter", "nbDots": 0 },
  //   "transpose": { "chromatic": "0" },
  //   "voicesData": { "voices": [0], "mainVoiceIdx": 0 }
  // }
});
```

### noteDetails

This event is triggered when the position or context of the user's cursor changes. The payload is the same as [`getNoteDetails()`](./data.md#getnotedetails).

```typescript
embed.on('noteDetails', (details) => {
  console.log('Note details:', details);
  // {
  //   "articulations": [],
  //   "classicHarmony": null,
  //   "dynamicStyle": null,
  //   "ghostNotes": [false],
  //   "hammerOnPullOffs": [false],
  //   "harmony": null,
  //   "hasArpeggio": false,
  //   "hasGlissando": false,
  //   "isChord": false,
  //   "isInSlur": false,
  //   "isRest": false,
  //   "isTied": false,
  //   "lines": [-2.5],
  //   "lyrics": [],
  //   "nbDots": 0,
  //   "nbGraces": 0,
  //   "ornaments": [],
  //   "pitches": [{"step": "E", "octave": 2, "alter": 0}],
  //   "technical": [],
  //   "tupletType": null,
  //   "wedgeType": null,
  //   "durationType": "eighth"
  // }
});
```

### rangeSelection

This event is triggered when a range of notes is selected or the selection changed. The `noteIdx` for the `right` location is inclusive.

```typescript
embed.on('rangeSelection', (selection) => {
  console.log('Range selection:', selection);
  // {
  //   "left": {
  //     "measureUuid": "ee882ed1-083a-3caa-34c4-cba4f0c28198",
  //     "staffUuid": "77ce0d0c-8c09-ae97-bc58-6e8f63dffaa7",
  //     "partUuid": "9a12babc-8397-f9d2-5da3-7688384a55cc",
  //     "voiceUuid": "8b19453c-f6fd-c9f3-41f0-e678b002d80e",
  //     "noteIdx": 1,
  //     "line": 3
  //   },
  //   "right": {
  //     "noteIdx": 2,
  //     "measureUuid": "49fda575-db0a-065d-98a9-8214388ee8f6",
  //     "partUuid": "1bace7c1-13e8-e513-4dbf-a28b0feaeaa3",
  //     "staffUuid": "f03b9986-4d12-5081-c934-a6e8d6b299e3",
  //     "voiceUuid": "862c3d23-974e-d648-6057-f8e27c585f16"
  //   }
  // }
});
```

### fullscreen

This event is triggered when the fullscreen state changes. The callback receives a boolean indicating whether fullscreen is enabled.

```typescript
embed.on('fullscreen', (isFullscreen) => {
  console.log('Fullscreen:', isFullscreen ? 'enabled' : 'disabled');
});
```

### embedSize

This event is triggered after the score is rendered (and whenever the container resizes) to report the embed's current dimensions in pixels.

```typescript
embed.on('embedSize', ({ width, height }) => {
  console.log(`Embed is ${width}px × ${height}px`);
  // Example: automatically match your container height to the score
  container.style.height = `${height}px`;
});
```

### exportProgress

This event is triggered during export operations ([`getMP3()`](./score-management.md#getmp3), [`getWAV()`](./score-management.md#getwav), [`getPDF()`](./score-management.md#getpdf), [`getPNG()`](./score-management.md#getpng)) to report rendering progress. The callback receives a progress object that can be used to display a progress indicator to the user.

```typescript
embed.on('exportProgress', (progress) => {
  console.log('Export progress:', progress);
});
```

#### Example: Show export progress to the user

```typescript
embed.on('exportProgress', (progress) => {
  progressBar.value = progress;
});

const mp3Data = await embed.getMP3();
```

### play

This event is triggered when playback starts. This event doesn't include any data.

```typescript
embed.on('play', () => {
  console.log('Playback started');
});
```

### pause

This event is triggered when playback is paused. This event doesn't include any data.

```typescript
embed.on('pause', () => {
  console.log('Playback paused');
});
```

### stop

This event is triggered when playback stops. This event doesn't include any data.

```typescript
embed.on('stop', () => {
  console.log('Playback stopped');
});
```

### playbackPosition

This event is triggered continuously during playback as the position changes. Useful for tracking playback progress.

```typescript
embed.on('playbackPosition', (position) => {
  console.log('Playback position:', position);
  // {
  //   currentMeasure: 3, // Index of the measure in the score
  //   quarterFromMeasureStart: 2.2341 // Position from the beginning of the measure
  // }
});
```

#### Example: Get the currently playing note

```typescript
const cursorPosition = await embed.getCursorPosition();
const { partUuid, voiceUuid } = cursorPosition;
const measuresUuids = await embed.getMeasuresUuids();

embed.on('playbackPosition', async (playbackPosition) => {
  const { currentMeasure } = playbackPosition;
  const measureUuid = measuresUuids[currentMeasure];
  const voicesUuids = await embed.getMeasureVoicesUuids({
    partUuid,
    measureUuid,
  });
  
  if (!voicesUuids.includes(voiceUuid)) {
    // The voice is not present in the current measure
    return;
  }

  const noteIdx = await embed.playbackPositionToNoteIdx({
    partUuid,
    voiceUuid,
    playbackPosition,
  });
  
  const noteData = await embed.getNoteData({
    partUuid,
    measureUuid,
    voiceUuid,
    noteIdx,
  });
  
  console.log('Currently playing note:', noteData);
});
```

## Event Categories

### Score Events

* `scoreLoaded` - Triggered when a score is loaded

### Cursor Events

* `cursorPosition` - Cursor position changes
* `cursorContext` - Cursor context changes
* `measureDetails` - Measure information updates
* `noteDetails` - Note information updates
* `rangeSelection` - Selection range changes

### Playback Events

* `play` - Playback starts
* `pause` - Playback pauses
* `stop` - Playback stops
* `playbackPosition` - Playback position updates

### Export Events

* `exportProgress` - Export rendering progress updates

### UI Events

* `fullscreen` - Fullscreen state changes
* `embedSize` - Embed layout dimensions change

---

---
url: /developers/docs/api/authentication.md
---

# Flat API Authentication

The Flat Platform API uses [OAuth 2.0](https://oauth.net/2/) for authentication and authorization. If you never used OAuth2 before, we advise you to read this [great introduction](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2). Our API supports the **Authorization Code** and **Implicit** grants. To simplify the usage of our API for your own account, you can quickly create access tokens in your Flat account (aka. "Personal Access Tokens").

## How to quickly getting started

1. [Create an app](https://flat.io/developers/apps) for your script or project.
2. **Try the API in 5 minutes** with [a Personal Access Token for your Flat account](#personal-access-tokens).
3. If you plan to make the app available for other people, [request some OAuth2 Credentials to our product team](https://docs.google.com/forms/d/e/1FAIpQLSeW4sZuUrcBXEtbecJ8xlWL9anbFCsrpHBgc6C48DOE4zuElQ/viewform).

## Personal Access Tokens

Personal Access Tokens function like OAuth access tokens for your own account. You can generate them from your account in a few seconds:

1. [Create an app](https://flat.io/developers/apps) for your script or project
2. On the left menu, click on "**Flat API > Personal Tokens**"
3. Choose a name and the authorization scopes for your first token.

That's all, you can directly use our API with this token by setting it in the `Authorization` headers of your requests:

```http
Authorization: Bearer my-api-personal-access-token
```

Here is an example with cURL:

```bash
curl -H 'Authorization: Bearer <my_api_personal_access_token>' https://api.flat.io/v2/me
```

## OAuth2

**Do you Need some OAuth2 credentials? Please [contact our product team](https://docs.google.com/forms/d/e/1FAIpQLSeW4sZuUrcBXEtbecJ8xlWL9anbFCsrpHBgc6C48DOE4zuElQ/viewform)**. Here is the main information for our OAuh2 API, you can learn more about the scopes and flows in the paragraphs below.

* Authorization URL: `https://flat.io/auth/oauth`
* Token URL: `https://api.flat.io/oauth/access_token`
* Invalidation URL: `https://api.flat.io/oauth/invalidate_token`
* [List of scopes](#scopes)

## Scopes

You will need to choose and include a list of requested scopes during the OAuth flow. At this time we support the following scopes:

| Scope | Description |
|:------|:------------|
| `account.public_profile` | Users' public profiles |
| `account.email` | Access to the person's email address. |
| `account.education_profile` | For education accounts, users' profiles and organization information. |
| `scores.readonly` | Read-only access to all a user's scores. |
| `scores.social` | Post comments and like scores |
| `scores` | Full, permissive scope to access all of a user's scores. |
| `collections.readonly`| Allow read-only access to a user's collections. |
| `collections.add_scores` | Allow to add scores to a user's collections. |
| `collections` | Full, permissive scope to access all of a user's collections. |
| `notifications.readonly` | Read-only access to a user's notifications. |
| `edu.resources` | Read-write access to the resource library. |
| `edu.resources.readonly` | Read-only access to the resource library. |
| `edu.classes` | Full, permissive scope to manage the classes. |
| `edu.classes.readonly` | Read-only access to the classes. |
| `edu.assignments` | Read-write access to the assignments and submissions. |
| `edu.assignments.readonly` | Read-only access to the assignments and submissions. |
| `edu.admin` | Full, permissive scope to manage all the admin of an organization. |
| `edu.admin.lti` | Access and manage the LTI Credentials for an organization. |
| `edu.admin.lti.readonly` | Read-only access to the LTI Credentials of an organization. |
| `edu.admin.users` | Access and manage the users and invitations of the organization. |
| `edu.admin.users.readonly` | Read-only access to the users and invitations of the organization. |
| `tasks.readonly` | Read-only access to export tasks created by this account. |
| `omr` | Run [Optical Music Recognition](/api/omr/) jobs and download their results. The `library` output additionally requires the `scores` scope. |

## Authorization Page

Both **Authorization Code** and **Implicit** OAuth2 grants start with our authorization page. Our Authorization page (`https://flat.io/auth/oauth`) supports all the standard parameters from the **Authorization Code** grant ([RFC6749/4.1](https://tools.ietf.org/html/rfc6749#section-4.1)) and the **Implicit** grant ([RFC6749/4.2](https://tools.ietf.org/html/rfc6749#section-4.2)).

The first step is to build an authorization link where you can redirect your user. Here is a simple example:

```text
https://flat.io/auth/oauth?client_id=<client_id>&response_type=(code|token)&state=<state>&scope=account.public_profile+scores&redirect_uri=<redirect_uri>
```

You can find below the different parameters available, including non-standard and optional parameters. All of them can be passed as query string when redirecting the end-user to the authorization page.

Property name  | Required | Values and Description
\---------------|----------|-----------------------
`client_id`    | Required | The client id (aka key) from the couple key/secret provided by Flat
`response_type`| Required | We support `code` (**Authorization Code** grant, [RFC6749/4.1.1](https://tools.ietf.org/html/rfc6749#section-4.1.1)) and `token` (**Implicit**, [RFC6749/4.2.1](https://tools.ietf.org/html/rfc6749#section-4.2.1)). It is strongly advised to use the Authorization Code grant for any server-side usage and the Implicit grant for any client-side (e.g. JavaScript) usage.
`scope`        | Required | You must provide a list of scopes listed above and granted for your app, separated with a space.
`redirect_uri` | Required | Determines where the response is sent. The value of this parameter must exactly match the value specified in your App Credentials settings.
`state`        | Optional | An opaque string that is round-tripped in the protocol; that is to say, it is returned as a URI parameter in the Authorization Code grant, and in the URI #fragment in the Implicit grant.
`access_type`  | Optional (available for the Authorization Code grant) | The acceptable values are `online` and `offline`. When specifying `offline`, the API will return a refresh token during the access token exchange.

When redirecting your users to this authorization page, they will see a page that looks like the one below, where they can grant your app to access and use their account:

![Flat OAuth2 Authorization Page](/img/api-authz-page.png)

## Authorization Code grant

Here is a typical flow of an **Authorization Code grant**. We advise you to use this grant for using our API in **server-side**.

1. You redirected a visitor/user to our [authorization page](#authorization-page) by specifying `response_type=code`, your `client_id` and a `redirect_uri`.
2. This user granted your app on our authorization Page.
3. Flat redirects your user back to your website at the `redirect_uri` you specified. You will receive a `code` query string with an Authorization Code that you can exchange for an access token. This URL will also include a previous `state` you specified in the authorization page URL. (e.g. `https://my-website.example.com/callback?code=<authz-code>&state=<state>`)
4. To exchange this Authorization Code, use our Token API Endpoint, `https://api.flat.io/oauth/access_token` ([RFC6749/4.1.3](https://tools.ietf.org/html/rfc6749#section-4.1.3)).

Here is an exchange request example (server-side):

```bash
curl -i -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
 -d grant_type=authorization_code \
 -d code=<authz-code> \
 -d client_id=<client_id> \
 -d client_secret=<client_secret> \
 -d redirect_uri=<redirect_uri> \
 https://api.flat.io/oauth/access_token
```

And a response for this request:

```json
{
  "type": "access",
  "token_type": "bearer",
  "access_token": "<access-token>",
  "issued_at": 1492542537,
  "expires_in": 86400,
  "app": "<app-id>",
  "appStatus": "trusted",
  "user": "<user-id>",
  "scope": "account.public_profile scores"
}
```

The access token is now ready to use, here is an example with cURL:

```bash
curl -H 'Authorization: Bearer <access-token>' https://api.flat.io/v2/me
```

## Implicit grant

Here is a typical flow of an **Implicit grant**. We advise you to use this grant for using our API in **client-side**. We main difference with the Authorization Code grant is that you don't need to exchange a code, you directly get the access token in the URI Hash.

1. You redirected a visitor/user to our [authorization page](#authorization-page) by specifying `response_type=token`, your `client_id`, and a `redirect_uri`.
2. This user granted your app on our authorization Page.
3. Flat redirects your user back to your website at the `redirect_uri` you specified. You will receive the access token in the URI Hash (see example below).

```text
https://my-website.example.com/callback#scope=account.public_profile&expires_in=86400&access_token=<access-token>
```

The access token is now ready to use, here is an example with the JavaScript Fetch API:

```javascript
fetch('https://api.flat.io/v2/me', {
  headers: {
    'Authorization': 'Bearer ' + ACCESS_TOKEN
  }
})
.then(function (response) {
  return response.json();
})
.then(function (me) {
  console.log(me);
});
```

## Tokens revocation

This OAuth2 API supports token revocation ([RFC 7009](http://tools.ietf.org/html/rfc7009)) at the following endpoint: `https://api.flat.io/oauth/invalidate_token`.

---

---
url: /developers/docs/api/introduction.md
description: >-
  Use our high-quality music and tabs notation engraving in your web sites and
  blogs with our customizable and interactive HTML Embed.
---

# Flat Platform's REST API

The Flat API allows you to easily extend the abilities of the [Flat Platform](https://flat.io), with a wide range of use cases including the following:

* Creating and importing new music scores using MusicXML or MIDI files.
* Browsing, updating, copying, exporting the user's scores (for example in MP3, WAV or MIDI).
* Managing educational resources with [Flat for Education](https://flat.io/edu): creating & updating the organization accounts, the classes, rosters and assignments.

The [schema](https://flat.io/developers/api/reference/swagger.json) of this API follows the [OpenAPI Initiative (OAI) specification](https://www.openapis.org/), you can use and work with [compatible Swagger tools](http://swagger.io/open-source-integrations/). You can also directly [browse the reference of the API online, including code samples](https://flat.io/developers/api/reference/).

The Flat API is built on HTTP. Our API is RESTful It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body.

You can use your favorite HTTP/REST library for your programming language to use Flat's API. This specification and reference is [available on Github](https://github.com/FlatIO/api-reference).

## How to quickly get started

1. [Create an app](https://flat.io/developers/apps) for your script or project.
2. **Try the API in 5 minutes** with [a Personal Access Token for your Flat account](authentication#personal-access-tokens).
3. If you plan to make the app available for other people:

* If your app will be available to all Flat consumer accounts or other Flat for Education schools, [request some OAuth2 Credentials to our product team](https://docs.google.com/forms/d/e/1FAIpQLSeW4sZuUrcBXEtbecJ8xlWL9anbFCsrpHBgc6C48DOE4zuElQ/viewform)
* If you want to use our API to interact with other accounts from your [Flat for Education](https://flat.io/edu) organizations, [check our dedicated documentation](/api/flat-for-education.html).

## About this API

Our whole platform and apps are based on this API, however not all the endpoints are made available publicly. Feel free to [contact us](mailto:developers@flat.io) if you have any questions, feedback or features requests.

By using this API, and especially on the behalf of a user account, you must accept, respect and enforce our [Terms of Service and Privacy Policy](https://flat.io/help/en/policies).

We don't offer any guarantees regading the future of this API. By using this API, you agree to update your app in a timely fashion in response to any changes that are rolled out.

---

---
url: /developers/docs/api/changelog.md
description: Discover the latest changes of Flat's REST API
---

# Flat REST API Changelog

We regularly update our API and services, you can discover all the changes to our public specification. Breaking changes are written below in bold if any.

## 2026-08-31

* Optical Music Recognition (OMR): New [FAQ section](omr/faq/) covering [credits and billing](omr/faq/credits), [limits and performance](omr/faq/limits), [recognition quality and languages](omr/faq/quality), and [commercial use, privacy, and data](omr/faq/legal). The [OMR guide](omr/) now also states that one credit is one page drawn from the same pool as the Flat apps, lists the current page, file, size, and concurrency limits alongside typical processing times, and documents commercial use of the output, our no-training-on-your-files policy, and what remains after a job is deleted.
* Optical Music Recognition (OMR): The `/omr` API is out of Beta. Endpoints, fields, and behavior are now stable, and any breaking change will follow our usual deprecation process. Keeping a generic fallback for open-ended values (statuses, step and error codes) is still recommended, as new values may be added. See the [OMR API guide](omr/).

## v2.25.0 (2026-08-04)

* Optical Music Recognition (OMR), **Beta API**: Take control of your jobs' data retention. `GET /omr/capabilities` now advertises `retentionDays` (30 by default), and jobs created with `output: musicxml` carry a `retention` object with their `expiryDate`. See [Retention and deletion](omr/jobs#retention-and-deletion).
  * `DELETE /omr/jobs/{job}` (`deleteOmrJob`): Erase a job's files and results as soon as you have collected them, instead of waiting for the deadline. The job stays listable with the `status` it finished with and records `retention.expiredDate`; downloads then return `409` (`OMR_JOB_EXPIRED`).
  * `GET /omr/jobs` (`listOmrJobs`): New `expired` filter, usable alongside `status`.
  * `GET /omr/capabilities` (`getOmrCapabilities`): Now available without authentication, so you can feature-detect before a user connects their account. Added `localesDetails`, the supported recognition languages with their English names. The fields the server always returns are now declared required, so a generated client can read them without null checks; `retentionDays` stays optional, and the account-scoped `costPerPage` and `remainingCredits` remain optional as before.
  * `OmrDetectedInstrument` and `OmrInstrumentOverride`: Clarified that `instrumentId` is the dotted `group.instrument` form, and documented the accepted `transposeKey` values.
* Scores:
  * `GET /scores/{score}/revisions/{revision}/{format}` (`getScoreRevisionData`): Added `abc` export, for [ABC notation](https://abcnotation.com/). Like MIDI, this format is lossy and does not carry the full engraving of the score.
  * `ScoreTrack`: The `score` property is now optional.
* Flat for Education:
  * `Assignment` and `AssignmentUpdate`: Added `freeRecord`, the configuration for Free Record assignments.
  * `GET /eduResources` (`listEduResources`): The `parent` documentation now points at [`listEduLibraries`](https://flat.io/developers/docs/api/reference#tag/EduResources/operation/listEduLibraries) for the library ids you can pass, rather than listing them. Which libraries an account can open depends on the account, so read them from that endpoint instead of hardcoding.
* Errors:
  * `FlatErrorResponse`: Added `providerMessage`, a localized message from an upstream provider (for example Google Classroom) when a request fails on their side.

## v2.24.0 (2026-07-08)

* Optical Music Recognition (OMR), **Beta API**: New resumable `/omr` API to import sheet music images and PDFs, with live progress and an optional interactive instrument-review step. The `/omr/jobs` endpoints cover the full job lifecycle (create, upload files, start, poll, review, export to MusicXML/MIDI, cancel), and `GET /omr/capabilities` advertises limits and credits for feature detection. Added the `omr` OAuth2 scope; importing the result into the Library (`output: library`) additionally requires `scores`. See the [OMR API guide](omr/). This API is in Beta and may change before the stable release: keep a generic fallback for open-ended values (statuses, step and error codes) and expect breaking changes to be announced.
* Scores:
  * `POST /scores` (builder import): The instruments list now references the [Instrument IDs reference](https://flat.io/developers/docs/api/instruments) and the [`@flat/instruments`](https://www.npmjs.com/package/@flat/instruments) package for the possible `group` and `instrument` values.
* Flat for Education:
  * `POST /organizations/{organization}/users` (`createOrganizationUser`): Added the `accountAdmin` role option (`UserCreation`).

## v2.23.0 (2026-06-16)

* Asynchronous PDF import with OMR (Optical Music Recognition) — see the [Importing PDFs with OMR guide](omr/import):
  * `POST /scores`: Added `supportsTasks` on file imports. When set to `true` and the imported file requires OMR (e.g. a PDF), the API responds with `202 Accepted` and a `Task` reference instead of the score. Clients then poll [`GET /tasks/{task}`](https://flat.io/developers/api/reference/#operation/getTask) until the import completes.
  * `Task`: Added the `import-omr` task type (processes a PDF through OMR and imports it as a score). The created score identifier is available in the task's `score` property once its `state` is `done`.
  * `POST /scores`: The `200` response now returns the `x-flat-score-revision` and `x-flat-score-revision-date` headers.
* Flat for Education:
  * Added the `accountAdmin` organization role (`OrganizationRole`, organization invitation creation, and the role search parameter).

## v2.22.0 (2026-04-07)

* Score Import & Export - 15+ import formats documented, new `.flat` export:
  * `POST /scores`: Expanded the list of supported import formats with detailed documentation. **MusicXML** and **MIDI** are the preferred formats; also supported via conversion: Guitar Pro, MuseScore, ABC notation, PowerTab, Capella, MEI, Overture, TablEdit, Band-in-a-Box, Karaoke MIDI, MuseData, Score Writer, Bagpipe Music Writer, and Encore.
  * `GET /scores/{score}/revisions/{revision}/{format}`: Added `flat` export format for native Flat compressed files (`.flat`).
  * `ScoreDetails`: Added `me` property with information about the authenticated user's relationship to the score.

* Collections - Simplified library navigation with virtual collections replacing the legacy folder hierarchy ([blog: Library Design Revamp](https://blog.flat.io/library-design-revamp-elevating-your-music-composition-experience/)):
  * New virtual collections: `allScores`, `collaborations`, and `likes` replace the deprecated `root` and `sharedWithMe` collection types.
  * `GET /collections` (`listCollections`): New default `parent=user` returns all user collections including virtual ones. Added `modificationDate` sort option.
  * `Collection`: Added `isPinned`, `labelKey`, and `modificationDate` properties.
  * `POST /collections/{collection}/untrash`: **Deprecated.** Collections untrashing is no longer supported.
  * Updated collection parameter descriptions across all endpoints to document the new virtual collections and deprecate `root`/`sharedWithMe`.

* Flat for Education:
  * Assignments & Rubrics - Rubric grading, video/audio performance recordings, and group submissions ([blog: Performance Assignments upgrade](https://blog.flat.io/performance-assignments-just-got-an-upgrade-more-tools-flexibility/), [Grading Composition Assignments](https://blog.flat.io/how-to-grade-music-composition-assignments-without-losing-your-weekends/)):
    * Performance assignments: Added `recordingType` (`audio`/`video`), `allowBackingTrack`, `allowMetronome`, and `allowSpeedChange` options.
    * Group submissions: Added `submissionStudentsMode` (`single`/`group`) for shared writing assignments, with `assignedGroups` on `ClassAssignment`. See [blog: Introducing Shared Writing](https://blog.flat.io/collaborative-composition-flat-for-education-music-education/).
    * Rich text: Added `descriptionHtml` and `teacherInstructionsHtml` on assignments, `sharingDescriptionHtml` on education resources.
    * `ClassAttachmentCreation`: Added `partUuid`, `revision`, and `teacherOnly` properties.
  * Student Groups - Manage student sub-groups for shared writing and group submissions ([blog: Back to School updates](https://blog.flat.io/back-to-school-flat-for-education-updates/)):
    * New CRUD endpoints for student sub-groups: `GET /groups` (`listGroups`), `POST /groups` (`createGroup`), `PUT /groups/{group}` (`renameGroup`), `DELETE /groups/{group}` (`deleteGroup`).
    * New membership endpoints: `POST /groups/{group}/users` (`addGroupUser`), `DELETE /groups/{group}/users/{user}` (`removeGroupUser`).
    * Groups can be filtered by classroom or assignment, and support test student tagging (`edu:testing-students`).
    * New group types: `classStudentsSubGroup` and `assignmentStudentsSubGroup`.
  * LTI Configuration - Unified LTI 1.1 and 1.3 configuration management, replacing the previous credentials-only API ([blog: LTI 1.3 Integration](https://blog.flat.io/flat-for-education-upgrades-to-lti-1-3-for-canvas-schoology-moodle-and-blackboard/)):
    * New CRUD endpoints under `/organizations/lti/configurations`.
    * Supports LTI 1.1 manual, LTI 1.3 manual, LTI 1.3 dynamic registration, and LTI 1.3 deployment-based configurations.
    * Added `enableEmailMatching` option to control email-based user matching during LTI authentication.
    * Previous LTI 1.1 credentials endpoints (`/organizations/lti/credentials`) are now **deprecated**. LTI 1.1 configurations can now be managed through the new unified endpoints.
  * Score Tracks:
    * `GET /scores/{score}/tracks` (`listScoreTracks`): Added documentation for access control on performance submission tracks (student vs. teacher visibility).
  * Organization & Users - Test account management, email verification, and improved class metadata:
    * `GET /organizations/users` and `GET /organizations/users/count`: Added `testAccounts` filter to include/exclude test student accounts.
    * `UserDetailsAdmin`: Added `isEduTestingStudent` property.
    * `UserDetails`: Added `isEmailVerified` property.
    * `OrganizationInvitation`: Added `htmlUrl` with a direct join URL.
    * `ClassDetails`: Added `modificationDate`, and now requires `creationDate`, `name`, `state`. Updated `lti` property to cover LTI 1.1 and 1.3 context with `hasNrpsService`.
  * Resource Library - Rich text descriptions and assignment type selection on resource creation:
    * `EduResource` and `EduResourceCreation`: Added `sharingDescriptionHtml` for rich text sharing descriptions.
    * `EduResourceCreation`: Added `resource` property for assignment-specific creation options (e.g., assignment type).
    * `EduLibrary`: Renamed library type from `flatEduSamples` to `flatEduContent`.
  * Microsoft Teams Integration - Scheduled assignments and individual student targeting:
    * `MicrosoftGraphAssignment`: Added `assignDateTime` for scheduled assignments, `assignToType` (`class`/`individual`) and `assignedStudentsMsIds` for individual assignment targeting. Expanded `state` enum with `scheduled` and `inactive` statuses.

* Accounts & Profiles:
  * `UserPublic`: Added `allPublicScoresCount` property. Removed deprecated `instruments` property.
  * `UserCreation`: Locale is now a free-form string (auto-normalized) instead of a strict enum.
  * Improved `TutteoProduct` descriptions with links to each product.

* Statistics:
  * Added `yearly` counts to `ScoreCommentsCounts`, `ScoreLikesCounts`, `ScorePlaysCounts`, and `ScoreViewsCounts`.

* Deprecations & Removals:
  * **Removed** `FlatLocales` enum schema, replaced by `FlatLocalesString` with auto-normalization.
  * **Removed** unused `billing` role from `OrganizationRoles`.
  * **Deprecated** `POST /collections/{collection}/untrash` (`untrashCollection`).
  * **Deprecated** LTI credentials endpoints in favor of the new unified configuration API.
  * **Deprecated** `root` and `sharedWithMe` collection parent aliases (use `user` instead).
  * **Deprecated** `staffIdx` on `ScoreCommentContext`.

## v2.21.0 (2024-10-18)

* Scores & Library:
  * `GET /users/{user}/scores`: As planned in 2020, this endpoint has been updated to only return public scores for user community profiles. The endpoint has also a new pagination system and sorting options.
  * `ScoreDetails`: Added `editHtmlUrl`, `instrumentsNames` and `scheduledDeletionDate` properties.
  * `Collection`: Added `contents.scoresCount` property.

* Flat Community profiles:
  * `UserPublic` now includes `likesCount` and `playsCount` properties.

* Flat for Education:
  * `GET /eduResources`:
    * Added options `withoutSubfoldersResources`, `assignmentTypes`, `subjects`, and `grades` to filter content.
    * Added new response headers `X-Total-Assignments-Count` and `X-Total-Folders-Count`.
  * `EduResource`: Added `sharingDescription`, `subjects`, `grades` and `capabilities.canChangePrivacy` properties.
  * `EduResourceFolder`: Added `assignmentsTypes` and `resourcesCount` properties.
  * `Assignment`: Added `restrictPlayNote` and `restrictToAudioTracks` properties.
  * `AssignmentSubmission`: Updated LTI to support LTI 1.1 and 1.3 (`lti.gradeService` property).
  * `ScoreTrack`: Added `purpose` property.

## v2.20.1 (2024-03-11)

* Keep `rights` property optional on `ScoreDetails`

## v2.20.0 (2024-03-08)

* Accounts:
  * feat(account): Added pagination to `GET /users/{user}/likes` and fixed typo in operationId.
  * feat(account): Added `product` on `UserDetails` to know the product the user is using.
* Score Library:
  * feat(library): Added `collaboratorType` to `ResourceRights` to know if the user accessing a resource is the owner, user or group collaborator. Adjusted non-optional properties on `ResourceRights`.
  * feat(library): Added `date` to `ResourceCollaborator` with the date the collaborator was added.
  * feat(score): Added new `mainKeySignature`, `highlightedDate` and `organization` properties to `ScoreDetails`. Adjusted non-optional properties on `ScoreDetails`.
  * feat(score): Added new `purpose` property to `ScoreTrack`. Adjusted non-optional properties on `ScoreTrack`.
  * feat(score): Added new `googleDriveDisabled` option when copying score (`POST /scores/{score}/fork`).
* Flat for Education:
  * feat(edu): Some Flat for Education invitatons can be re-used multiple times.
  * fix(edu): Flat for Education invitatons can only be used to create `admin` or `teacher` accounts, fixed `organizationRole` enum.
  * feat(edu): Added new `verifyIfNotAlreadyInResourceLibrary` option to `POST /classes/{class}/assignments/{assignment}/copy` to avoid copying to the Resource Library if the assignment is already in it.
  * fix(edu): Fixed `ClassAttachmentCreation` enum values to reflect the current state of our product.
  * feat(edu): Added `playback` and `lti` properties to `AssignmentSubmission`.
  * fix(edu): `comments` object has never been available in `AssignmentSubmissionUpdate`, only in `AssignmentSubmission`.
  * feat(edu): Added `graded` state for submissions.
  * feat(edu): Added `organizationResources` library type to `GET /eduResources/libraries`, and added `organizationPublic` enum value to `EduResourcePrivacy`.
  * feat(edu): Added new `privacy` property to `PUT /eduResources/{resource}`
  * fix(edu): Removed unused property `alternateLink` from `MicrosoftGraphSubmission`.
* fix(schema): missing `required: true` on some POST/PUT bodies.

## v2.19.0 (2023-08-25)

* feat(edu): added new `POST /eduResources/{resource}/createLtiLink` endpoint to create LTI links from Flat for Education resources.
* feat(edu): maximum graded has been increased from 100 to 10000.
* feat(score): new nullable properties in `PUT /scores/{score}` to unset properties (`subtitle`, `composer`, `lyricist`, `arranger`, `description`, `creationType`, `license`, `licenseText`).
* fix(score): wrong user object in `ScoreSummary`, returned object has more properties than the specification (`UserPublic`).
* fix(spec): various properties marked as required as they will always be returned.

## v2.18.0 (2023-05-05)

* feat(edu): Released Resource Library API in beta (`/eduResources`) with new OAuth 2 scopes `edu.resources` and `edu.resources.readonly`.
* feat(edu): Updated `POST /classes/{class}/assignments/{assignment}/copy` to allow to copy to Resource Library.
* feat(edu): Updated `DELETE /classes/{class}/assignments/{assignment}/submissions/{submission}` behavior, now only resets the submission instead of deleting it.
* feat(edu): Added `POST /classes/{class}/testStudent` to create testing student accounts.
* feat(edu): Operation `POST /classes/{class}/assignments` has been renamed from `createAssignment` -> `createClassAssignment` in schema.
* feat(edu): `Assignment` models now include a new `capabilities` property returning which actions are possible with a specific resource (`canEdit`, `canPublishInClass`, `canPublishInClassError`, `canArchive`, `canUnarchive`).
* feat(edu): `Assignment` models now include a new `useDedicatedAttachments` property to know if the underlying resources are dedicated and stored inside the assignment (new behavior with the resource library).
* feat(edu): `ClassAssignment` now includes a new `issue` property to return any issues encountered with the assignment.
* feat(edu): `toolset` id provided when creating or updated assignments will now make a copy of the toolset to have a dedicated object for the assignment.
* feat(edu): `AssignmentSubmissionHistory` now includes the `source` of the change, when this one comes from a third party (Google Classroom, Microsoft Teams, LTI). It also includes the following new properties: `dueDate`, `comment` and `attachment.title`.
* feat(edu): `UserDetails` now contains Microsoft Sign in details (`azureDetails`) and list of groups the user is part of (`groups`).
* feat(edu): Added optional metadata on class objects (`level`, `skillsFocused`, `size`).
* fix(edu): Fixed `ClassAttachmentCreation` enum values to reflect the current state of our product.
* feat(scores): Updated `GET /scores/{score}/revisions/{revision}` now returns the `startDate` and `endDate` for the score revisions.
* feat(scores): Updated `POST /scores` to add `hasQuarterTone` on score builders to enable quarter tones on score parts.
* feat(scores): Updated `POST /scores/{score}/fork` to add option to keep original title during a file copy (`keepOriginalTitle`).
* fix(schema): Added missing required properties on models `ScoreSummary`, `MediaAttachment` and `FlatErrorResponse`.

## v2.17.0 (2022-03-23)

* feat(collections): Add new dedicated App Collections. When creating new scores, by default Flat will add the scores to a dedicated collection for the 3rd party app. This collection is automatically created in the user account and has a new alias `app` that can be used in the URLs paths.

## v2.16.0 (2021-12-11)

* feat(scores): added `POST /scores/{score}/revisions/{revision}/{format}/task` to create a new export task for a score and `GET /tasks/{task}` to fetch the progress of an export task.

## v2.15.0 (2021-11-10)

* feat(edu): added `POST /organizations/users/{user}/signinLink` to allow admins to create sign in links for their organization's users.
* feat(edu): added `POST /organizations/users/{user}/accessToken` to allow admins to create delegated access tokens for their organization's users.
* feat(locale): added `ja-HIRA`
* feat(comments): added `moderation` object on public comments
* feat(scores): added `defaultTrack` option to `GET /scores/{score}/revisions/{revision}/{format}` to return mp3 tracks when a mp3 is set as default track.
* **DEPRECATED**: removed `onlyCached` option from `GET /scores/{score}/revisions/{revision}/{format}` since only cached files are now returned for audio exports.

## v2.14.0 (2021-10-04)

* feat(scores): `POST /v2/scores` has a new score builder to easily create blank scores without the need of importing a MusicXML file. Provide a list of instruments to use, and optionally customize the time signature, key signature, enable TABs, Chord grids as well as the page layout.
* feat(edu): `POST /v2/organizations/users` has support for roles.
* feat(edu): added new `shuffleExercises` option for worksheets.
* feat(edu): added new `exercisesIds` in students submissions.

## v2.13.0 (2021-07-19)

* feat(scores): `GET /v2/scores/{score}/tracks` has new query strings:
  * `listAutoTrack` to fetch tracks automatically generated & synced (playback available as a MP3 file).
  * `assignment` to filter tracks related to a Flat for Education assignment.
* feat(scores): added `GET /v2/scores/{score}/revisions/{revision}/synchronizationPoints` to fetch synchronization points automatically generated from latest MP3 playback file.
* feat(scores): `GET /v2/scores/{score}/revisions/{revision}/{format}` has a new query string `url` to fetch the CDN URL of the exported file in the JSON body.
* feat(edu): added `DELETE /v2/classes/{class}/assignments/{assignment}/submissions/{submission}` to let teachers reset students' submissions.
* feat(edu): added detected `issues` on classes with the list fo accounts that couldn't be added to the classes during synchronizations.
* feat(edu): added `microsoftGraph` property on assignments with the Microsoft Teams assignments `state`, URLs (`alternateLink`) and `categories`.
* feat(edu): added `microsoftGraph` property on submissions with the Microsoft Teams submissions `state` and URLs (`alternateLink`).
* feat(edu): `POST /v2/classes/{class}/assignments/{assignment}/copy` has a new property `scheduledDate` to schedule assignments copies.
* feat(edu): added `track` property to submissions for performance assigments saved audio tracks.
* feat(account): added a `coverPicture` property with the URL of the profile cover picture, and `pictureFile` and `coverPictureFile` containing the ID of the corresponding files.
* feat(account): `GET /v2/me` has a new `onlyId` query string to quickly fetch current user id.

## v2.12.0 (2021-02-18)

* update(scores): `ResourceCollaborator` now includes a `invited` boolean property to know if the collaborator is still a pending invite.
* feat(assignments): Export grades as CSV and Excel files (`GET /classes/{class}/assignments/{assignment}/submissions/csv` and `/classes/{class}/assignments/{assignment}/submissions/excel`)
* update(assignments): Assignment creation (`POST /classes/{class}/assignments`) and assignments objects now include a `type` (`AssignmentType`).
* update(assignments): Assignments objects (`Assignment`) now include a cover URL (`cover`) and the corresponding file identifier (\`coverFile).
* update(assignments): Assignment copy (`POST /classes/{class}/assignments/{assignment}/copy`) now accepts an optional `assigment` identifier. This can be used to override a draft assignment with the content from another assignment.
* style: Lint OpenAPI v3 specification

## v2.11.0 (2020-10-26)

* feat(edu): `PUT /organizations/users/{user}` has new parameters to edit accounts: `username`, `firstname`, `lastname`, `email`.
* feat(edu): `POST /classes/{class}/assignments` has new parameters:
  * `toolset` id to enable [a toolset](https://flat.io/help/en/education/toolset.html) for the assignment.
  * `nbPlaybackAuthorized` to limit the number of time the playback can be used
  * `maxPoints` for grading purpose
  * `googleClassroom.topicId` to add the assignment under a specific Google Classroom course topic
  * `assigneeMode` and `assignedStudents` to assign specific students
  * `lockScoreTemplate` to lock assigned templates
  * `dueDate` and `scheduledDate` are nullable to unset properties
  * returns new information about LTI assigments, Canvas assignments and MusicFirst assignments
* feat(edu): `PUT /classes/{class}/assignments/{assignment}/submissions` has:
  * New parameters for grading (`draftGrade`, `grade`)
  * A new parameter for teacher to return a submission (`return`) and
  * Computed comments counters (`comments`)
  * Returned object `AssignmentSubmission` now includes `maxPoints` for the maximum number of points when the grade was set.
* feat(edu): New endpoints under `/classes/{class}/assignments/{assignment}/submissions/{submission}/comments` to create, list, update and delete comments for the submission.
* update(scores): `GET /scores/{score}/revisions/{revision}/{format}` query string `parts` now only accepts parts UUIDs.
* update(edu): `GET /organizations/users` query string `licenseExpirationDate` now also accepts `active` and `notActive` values, and has a new query option `onlyIds`
* **DEPRECATED**: `PUT /classes/{class}/assignments/{assignment}/submissions` parameters `studentComment` and `returnFeedback` have been removed. `returnFeedback` has been replace by a boolean `return` to return a submission as a teacher.

## v2.10.0 (2020-06-03)

* feat(edu): `POST /v2/organizations/users` now accepts optional `firstname` and `lastname`
* update(edu): `GET /v2/organizations/users` now accepts sort options and filters
* feat(edu): added `GET /v2/organizations/users/count` to count users matching specified filters
* feat(edu): removed deprecated `role` property from `POST /organizations/invitations` (previously renamed to `organizationRole`)
* feat(assignments): added `POST/DELETE /v2/classes/{class}/assignments/{assignment}/archive` to archive/unarchive assignments
* feat(assignments): returned assignments object from `GET /v2/classes/{class}/assignments/{assignment}` now includes the main type of the assignment: `newScore`, `scoreTemplare` or `sharedWriting`.
* feat(edu): users returned by `GET /v2/groups/{group}/users` can now be filtered by the sync source: `googleClassroom`, `microsoftGraph` or `clever`.
* feat(scores): scores details returned by `GET /v2/scores/{score}` (and similar) now includes the audio samples list used by our playback. The `instruments` property now includes a normalized list of instruments that is not dependent from the samples used.

## v2.9.0 (2020-01-10)

* Schema is now using OpenAPI 3.0.2 (previous schemas were using OpenAPI 2)
* feat(scores): New metadata and update of `GET/PUT /v2/scores/{score}`:
  * `arranger` property has been added
  * `plays` statistics are now returned (`ScorePlaysCounts`)
* feat(scores): New `now` proprty on the `DELETE` method to schedule a deletion to be executed shortly (avoid keeping in trash)
* feat(edu): Attachments (`MediaAttachment` and `ClassAttachmentCreation`) have new type `googleDrive` for attached Drive file, and a new `googleDriveFileId` property. If the attachment is a `googleDrive` item, the `iconUrl` and `mimeType` properties are also returned
* feat(edu): Add `microsoftGraph` info to `ClassDetails` (e.g. `GET /v2/classes` and `GET /v2/classes/{class}`)
* feat(account): Add `firstname` and `lastname` properties for education accounts

## v2.8.0 (2019-04-27)

* feat(scores): New metadata and update of `PUT /v2/scores/{score}`:
  * `subtitle`, `composer`, `lyricist` and `licenseText` properties has been added
  * when updating `title`, `subtitle`, `composer`, `lyricist` and `licenseText` via the API, the modifications events will be pushed to our real-time engine, and a new version will be scheduled (asynchronous)
  * `description` can now be up to 2000 characters (was previously 1000)
* feat(submissions): Added education submissions states (`created`, `turnedIn`, `returned`)
* feat(revisions): Return the last modification `event` when fetching a revision metadata (UUID)
* feat(locale): added Turkish (`tr`)
* feat(licenses): added new license source `appStore`
* feat(user): added `isFlatTeam` property to public profiles
* chore(specs): Inline schemas `UserInstruments`, `ResourceSharingKey`, `ScoreData`, `ScoreDataEncoding`, `CollectionTitle`

## v2.7.0 (2018-09-11)

* update(spec): specify `produces` and `consumes` on endpoints instead of globally
* feat(scores): now support Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar and MuseScore files in POST /scores
* feat(scores): add support for `filename` when importing scores
* feat(collections): `parent` collection can now be a collection id when listing collections
* feat(collections): includes parent collections when listing scores
* feat(collections): add `creationDate` property in collection details
* feat(comments): add `staffUuid` for contextualized comments, which will completely replace `staffIdx` in the future
* feat(rights): now return a `isCollaborator` boolean property with the Score or Collection rights
* update(account): added new locales supported

## v2.6.0 (2018-04-23)

* feat(collections): Add new Collections API endpoints
  * `POST /collections`: Create new collection
  * `GET /collections`: List collections
  * `GET /collections/{collection}`: Get collection details
  * `PUT /collections/{collection}`: Update collection details
  * `DELETE /collections/{collection}`: Delete collection
  * `POST /collections/{collection}/untrash`: Untrash collection
  * `GET /collections/{collection}/scores`: List scores contained in a collection
  * `PUT /collections/{collection}/scores/{score}`: Add a score to a collection
  * `DELETE /collections/{collection}/scores/{score}`: Remove a score from a collection
* feat(collections): Add new OAuth2 scopes for new features:
  * `collections.readonly`: Allow read-only access to a user's collections.
  * `collections.add_scores`: Allow to add scores to a user's collections.
  * `collections`: Full, permissive scope to access all of a user's collections.
* feat(score): Added new method to untrash a score (`POST /v2/scores/{score}/untrash`)
* feat(score): `DELETE /v2/scores/{score}` can now be used without admin rights. This new behavior will unshare the score from the current account.
* feat(score): `POST /scores/{score}/fork` now accepts a collection identifier to copy a score to a specific collection.
* feat(comments): Comments can now be filtered by type with the new query string `type` (`document` or `inline`).
* update(openapi): Some schema definitions have been renamed, they are now used for Scores and Collections
  * `ScoreRights` -> `ResourceRights`
  * `ScoreCollaborator` -> `ResourceCollaborator`
  * `ScoreCollaboratorCreation` -> `ResourceCollaboratorCreation`
  * existing *score sharing key* -> `ResourceSharingKey`
* **DEPRECATED**: `GET /scores/{score}/revisions/{revision}/{format}` no longer support part indexes for single/set of parts exports, but our own part UUIDs.
* **DEPRECATED** on 2019-09-01: `GET /users/{user}/scores` will no longer list private and shared scores, but only public scores of a Flat account.

## v2.5.2 (2018-02-07)

* fix(score): missing ScoreRights.aclRead type

## v2.5.1 (2018-01-16)

* fix(user): Add missing escape in `pattern` (`UserCreation.username`).

## v2.5.0 (2017-10-22)

* feat(scores): Add video & audio tracks support for scores: `/v2/scores/{score}/tracks`.

## v2.4.0 (2017-10-02)

* feat(scores): New metadata and update of `PUT /v2/scores/{score}`:
  * Added metadata in API `subtitle`, `lyricist`, `composer`, `description`, `tags`, `creationType`, `license`, `licenseText`, `durationTime`, `numberMeasures`, `mainTempoQpm`, `publicationDate`.
  * `PUT /v2/scores/{score}`: Remove `title` property, this one can be updated by saving a new revision of the score data.
  * `PUT /v2/scores/{score}`: New settable properties: `description`, `tags`, `creationType`, `license`.

## v2.3.0 (2017-08-28)

* feat(user): Add profile theme and instruments played.
* feat(edu): Add new cursor-based pagination for `GET /v2/organizations/users` and `GET /v2/organizations/invitations`.
* feat(edu): Add new methods:
  * `PUT /v2/organizations/users/{user}`: Admin endpoint to update managed accounts.
  * `DELETE /v2/organizations/users/{user}`: Admin endpoint to delete or convert edu accounts to consumer accounts.
* feat(edu): Classes have a new state `inactive` that can be activated using the new method `POST /v2/classes/{class}/activate`.
* feat(edu): Assignments have a new state `draft` and can have a new attachment type `exercise`.
* feat(edu): Return Canvas LMS Instance domain in classes details
* feat(edu): Return Clever.com section information in classes details

## v2.2.0 (2017-07-02)

* feat(edu): Public release of the first education APIs:
  * `/v2/classes`: Classes management
  * `/v2/classes/{class}/assignments`: Flat Assignments and Submissions
  * `/v2/organizations/users`: Organization accounts management
  * `/v2/organizations/invitations`: Organization invitations for admins and teachers
  * `/v2/organizations/lti/credentials`: LTI credentials management
  * `/v2/groups/{group}` and `/groups/{group}/users`: List of groups and users part of groups
  * `/v2/scores/{score}/submissions`: Submissions linked to a score
* feat(edu): New OAuth2 scopes:
  * `edu.classes`: Full, permissive scope to manage the classes.
  * `edu.classes.readonly`: Read-only access to the classes.
  * `edu.assignments`: Read-write access to the assignments and submissions.
  * `edu.assignments.readonly`: Read-only access to the assignments and submissions.
  * `edu.admin`: Full, permissive scope to manage all the admin of an organization.
  * `edu.admin.lti`: Access and manage the LTI Credentials for an organization.
  * `edu.admin.lti.readonly`: Read-only access to the LTI Credentials of an organization.
  * `edu.admin.users`: Access and manage the users and invitations of the organization.
  * `edu.admin.users.readonly`: Read-only access to the users and invitations of the organization.
* fix(spec): Add missing scopes in specification for `GET /v2/scores/{score}/revisions/{revision}` and `GET /v2/scores/{score}/revisions/{revision}/{format}`

## v2.1.0 (2017-04-17)

* feat(scores): Add support of private links sharing with `sharingKey`.
* feat(comments): Make "revision" optional when creating comments and support of "last" keyword.
* fix(revisions): Missing `id` property in `ScoreRevision`.
* update(spec): Specify `binary` response type for `GET /v2/scores/{score}/revisions/{revision}/{format}`

## v2.0.0 (2017-04-10)

* chore(api): First API public release with `/v2/me`, `/v2/scores`, `/v2/users` and `/v2/groups`.

---

---
url: /developers/docs/api/errors.md
---

# Flat REST API Errors

In the event of an error, the response will include the relevant HTTP Status Code and a JSON object in the body with information about the error.

| Property | Value |
|:---------|:------|
| `code` | Error code returned by the API (e.g. `CLIENT_ERROR`) |
| `message` | Human readable message which describes the error |
| `id` | An unique identifier (UUID) for the error. This field will be present for internal and backend errors. |

## Detailed reference on errors

You can find more info about the specific errors returned for each endpoint in our [API reference](https://flat.io/developers/api/reference/).

If you're having trouble with API errors, please [contact us for help](mailto:developers@flat.io). In case of a internal or backend error if you have the corresponding error unique `id` corresponding to the error, please send it to us, that can make issue diagnosis and response significantly faster.

---

---
url: /developers/docs/api/sdks.md
---

# Flat REST API SDKs

Flat offers and maintain the following SDKs and to ease development. These SDKs are built using [Swagger Codegen](https://github.com/swagger-api/swagger-codegen), which you can also easily use to build API clients for other languages and frameworks using our [OpenAPI Specification](https://github.com/FlatIO/api-reference).

## 🐍 Python

* Check out the documentation and the source code [on GitHub](https://github.com/FlatIO/api-client-python).
* This SDK is available on [pypi (`flat-api`)](https://pypi.python.org/pypi/flat-api).

## 💛 Node.js and Browser

* Check out the documentation and the source code [on GitHub](https://github.com/FlatIO/api-client-js).
* This SDK is available on [NPM and Bower (`flat-api`)](https://www.npmjs.com/package/flat-api).

## 🐘 PHP

* Check out the documentation and the source code [on GitHub](https://github.com/FlatIO/api-client-php).
* This SDK is available on [Packagist (`flat/api`)](https://packagist.org/packages/flat/api).

## 💎 Ruby

* Check out the documentation and the source code [on GitHub](https://github.com/FlatIO/api-client-ruby).
* This SDK is available on [Rubygems (`flat_api`)](https://rubygems.org/gems/flat_api).

---

---
url: /developers/docs/embed/getting-started.md
description: Discover how to quickly get started with our Sheet music embed.
---

# Getting started with our Music engraving Embed

The easiest way to get started with our [Sheet Music embed](https://flat.io/embed) is to use our [code generator](https://flat.io/developers/embed/generator). This one will build the basic HTML code for your embed and let you custom the most common [url parameters](url-parameters).

You can quickly access to the generator from any sheet music hosted on Flat: click on the "Share" button on the top right of the editor, then click on "Embed". If the score is private, a private sharing link with a `sharingKey` will be generated for the document:

![Get started with our Sheet Music Embed Generator](/img/share-embed-generator.gif)

You will get a similar code that you can paste to your web page code or blog post code:

```html
<iframe src="https://flat-embed.com/[SCORE_ID]" height="450" width="100%" frameBorder="0" allowfullscreen></iframe>
```

The attribute `allowfullscreen` will allow your visitors to open the score in fullscreen. You can also add extra URL parameters to customize your music score or embed appearance, discover them in [the related documentation](url-parameters).

---

---
url: /developers/docs/import/assets.md
description: You can find here the assets you may need to integrate our APIs.
---

# Graphic assets

You can find below different graphic assets you can use to integrate Flat. Please [contact us](mailto:developers@flat.io) if you need more resources.

## Edit with Flat

| Preview | URLs |
|---------|------|
| ![Edit with Flat (White)](https://flat.io/img/assets/edit-with-flat-white.svg) | **SVG**: <https://flat.io/img/assets/edit-with-flat-white.svg>**PNG**: <https://flat.io/img/assets/edit-with-flat-white.png> |
| ![Edit with Flat (Blue)](https://flat.io/img/assets/edit-with-flat-blue.svg) | **SVG**: <https://flat.io/img/assets/edit-with-flat-blue.svg>**PNG**: <https://flat.io/img/assets/edit-with-flat-blue.png> |

## Add to Flat

| Preview | URLs |
|---------|------|
| ![Add to Flat (White)](https://flat.io/img/assets/add-to-flat-white.svg) | **SVG**: <https://flat.io/img/assets/add-to-flat-white.svg>**PNG**: <https://flat.io/img/assets/add-to-flat-white.png> |
| ![Add to Flat (Blue)](https://flat.io/img/assets/add-to-flat-blue.svg) | **SVG**: <https://flat.io/img/assets/add-to-flat-blue.svg>**PNG**: <https://flat.io/img/assets/add-to-flat-blue.png> |

---

---
url: /developers/docs/embed/usage-billing.md
---

# How your usage is billed in Flat Embed?

Our [Embed Pro plan](https://flat.io/embed) operates on a usage-based billing model. Charges are determined by the number of unique monthly users who access the Flat Embed on your website. For detailed information on our pricing structure, visit our [pricing page](https://flat.io/embed#pricing). If you're an existing Embed subscriber, you can monitor your usage on the [Embed billing page](https://flat.io/developers/apps/_/embed/billing).

**Legacy Plans**: For those subscribed to Legacy embed plans prior to 2024, billing is twofold. Viewer traffic is billed based on the total page views, while editor traffic is calculated according to the number of users.

In the following sections, we will explore how unique user interactions with your embed are counted, and provide guidance on configuring your embed to accurately track usage.

## Recommended Approach: Utilizing a Unique User Identifier

For precise billing based on your traffic, we recommend providing an opaque user identifier (`userId`) each time the embed is loaded.

Consider a practical example: Suppose "Pierre" is a user in your database with the unique identifier `42`. Each time Pierre accesses a page on your website that contains an embed, you should pass this `userId` within the [embed URLs](/embed/url-parameters).

When incorporating `<iframe>` codes directly into your web pages, you can dynamically insert the `userId` into the embed URL as a query string. For instance, if your application ID (`appId`) is `123` and you wish to load the score `abc`, the corresponding embed URL for Pierre (with the user identifier `42`) would be:

```text
https://flat-embed.com/abc?appId=123&userId=42
```

If you're using our [Embed SDK](https://github.com/FlatIO/embed-client), the `userId` can be specified as `embedParams.userId`. For example, with `appId` `123`, the score `abc`, and user identifier `42`, you would set it up as follows:

```javascript
import Embed from 'flat-embed';

const container = document.getElementById('embed-container');
const embed = new Embed(container, {
  score: 'abc',
  embedParams: {
    appId: '123',
    userId: '42',
  },
});
```

**Monthly Billing**: At the end of each subscription month, we tally all the unique `userId` values that have accessed your embeds and bill you accordingly.

**Privacy Note**: When assigning a `userId`, ensure it's an opaque identifier that does not contain personal data (such as email addresses). Ideally, it should be a non-descriptive ID from your database, like `42`. For additional security, we hash these user identifiers using SHA1 internally, further safeguarding any personal information.

Should you require assistance in setting up `userId` for your website or application, please do not hesitate to [contact us](mailto:embed@flat.io). We're here to help.

## Default Method: IP addresses

By default, we use the IP addresses of your end-users to calculate the usage of your embeds unless you opt for the `userId` method described earlier.

**Monthly Billing**: At the conclusion of each subscription month, we'll tally the distinct IP addresses that have accessed your embeds and base your charges on these figures.

## Frequently Asked Questions (FAQ)

### Which Method Should I Choose?

For more precise billing and enhanced analytics on your account, we recommend implementing opaque user identifiers (`userId`). It's important to note that individuals often access services from different networks within a single month, leading to the same user being counted multiple times if tracked solely by IP address.

### Why Don't Flat Embeds Rely on Cookies?

* Privacy Considerations: Most web browsers typically block cookies in iframes for privacy reasons.
* Device Variability: Users accessing services through multiple devices would be inaccurately counted as separate users, similar to the IP address method.

### How Can I Review My Past Embed Usage?

You can examine the analytics of your application [in your Flat Embed account](https://flat.io/developers/apps/_/embed/statistics) and view your upcoming invoice on the [billing page](https://flat.io/developers/apps/_/embed/billing). For any inquiries, please feel free to [reach out to our team](mailto:embed@flat.io).

---

---
url: /developers/docs/import/usage.md
description: Easy import any MusicXML or MIDI file available the Internet
---

# Import API

Use our Import API to quickly allow people to edit and import your web content (MusicXML and MIDI) with Flat. Simply add a link to Flat following to specification below.

Want to do it with a script or server-side, create multiple files, or export files? You can do it with our [REST API](../api/).

## Specification

Endpoint:

```text
GET https://flat.io/score/import-url
```

Parameters:

| Name | Description | Required / Default values |
|:-----|:------------|:--------|
| `url` | The full URL of the **MusicXML** or **MIDI** file to import. The file must be publicly accessible and served with [CORS](#cors) | Required |
| `title` | The title of the file you are importing | Optional, default: `New music score` |
| `app` | If you have an [app id](https://flat.io/developers/apps), you can provide it here. Your App name and logo will be displayed on the landing page, and a dedicated collection with your app name will be created in the user account. | Optional |

## Example

```html
<a href="https://flat.io/score/import-url?url=https%3A%2F%2Fflat.io%2Fexamples%2Fhello-world.xml&title=Hello%20World">
  <img src="https://flat.io/img/assets/edit-with-flat-white.svg" alt="Edit with Flat">
</a>
```

You can find more graphic assets on [our assets page](/import/assets), feel free to [contact us](mailto:developers@flat.io) if don't find the resources that you need.

## CORS

The file is downloaded by the user's browser, so you will need to add correct [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) when replying to the request:

```http
Access-Control-Allow-Origin: *
```

Or:

```http
Access-Control-Allow-Origin: $ORIGIN
```

Where `$ORIGIN` is the `Origin` header of the request, i.e. `flat.io` or `[domain].flat.io` for private websites).

---

---
url: /developers/docs/embed/javascript.md
description: Install and set up the Flat Embed JavaScript/TypeScript SDK
---

# JavaScript/TypeScript SDK - Installation & Setup

The Flat Embed SDK provides **first-class TypeScript support** with complete type definitions, IntelliSense, and compile-time safety. Use it with TypeScript for the best developer experience, or with plain JavaScript - the choice is yours!

## Need More Features?

While this documentation covers our public API, we have additional internal methods that can be made available for specific use cases. If you need functionality that's not currently exposed in our public API, [please contact our developers' support](mailto:developers@flat.io) to discuss your requirements. We're happy to work with you to enable the features you need!

## Installation

You can install our ES/TypeScript Embed Client using [npm](https://www.npmjs.com/package/flat-embed), pnpm, or [yarn](https://yarnpkg.com/en/package/flat-embed):

```bash
npm install flat-embed
pnpm add flat-embed
yarn add flat-embed
```

Or use the latest UMD version hosted on our CDN:

```html
<script src="https://prod.flat-cdn.com/embed-js/v2.12.1/embed.min.js"></script>
```

## Getting Started

The simplest way to get started is to pass a DOM element to our embed that will be used as container. By default, this one will completely fit its container:

```html
<div id="embed-container"></div>
<script src="https://prod.flat-cdn.com/embed-js/v2.12.1/embed.min.js"></script>
<script>
  var container = document.getElementById('embed-container');
  var embed = new Flat.Embed(container, {
    score: '<score-id-you-want-to-load>',
    embedParams: {
      appId: '<your-app-id>',
      controlsPosition: 'bottom',
    },
  });
</script>
```

Otherwise, if you are using our embed in an ES6 project:

```js
import Embed from 'flat-embed';

const container = document.getElementById('embed-container');
const embed = new Embed(container, {
  score: '<score-id-you-want-to-load>',
  embedParams: {
    appId: '<your-app-id>',
    controlsPosition: 'bottom',
  },
});
```

## TypeScript First! 🚀

Our SDK is built with TypeScript and includes complete type definitions out of the box. Enjoy:

✅ **Full IntelliSense** - Auto-completion for all methods and parameters\
✅ **Type Safety** - Catch errors at compile-time, not runtime\
✅ **Better Documentation** - Inline documentation in your IDE\
✅ **Zero Configuration** - Types included, no `@types` package needed

```typescript
import Embed from 'flat-embed';

const container = document.getElementById('embed-container') as HTMLElement;
const embed = new Embed(container, {
  score: '5ce6a27f052b2a74a91f4a6d',
  embedParams: {
    appId: '<your-app-id>',
    mode: 'edit',  // TypeScript knows: 'view' | 'edit'
    controlsPosition: 'bottom',  // TypeScript knows: 'top' | 'bottom' | 'float' | 'hidden'
  },
});

// Full type checking and autocompletion
embed.on('play', () => {  // TypeScript knows all available events
  console.log('Playback started');
});

// Type-safe method calls
const parts = await embed.getParts();  // TypeScript knows: Promise<PartConfiguration[]>
```

## Constructor Options

When instantiating `Flat.Embed`, you can pass the following options:

```javascript
const embed = new Flat.Embed(container, {
  // Score to load, you can also use `loadMusicXML()`, see example below
  score: '<score-id>',
  
  // Or use a score URL
  baseUrl: 'https://flat.io/embed/<score-id>',
  
  // Embed parameters
  embedParams: {
    // Your app ID (required)
    appId: '<your-app-id>',
    
    // Display mode: 'view' (default) or 'edit'
    mode: 'view',
    
    // Controls position: 'top', 'bottom' (default), 'float', or 'hidden'
    controlsPosition: 'bottom',
    
    // Many more customization options available...
  },
  
  // Container dimensions (optional)
  width: '100%',
  height: '100%',
});
```

The `embedParams` object supports many customization options including:

* **Display options**: zoom, page layout, print capabilities
* **Playback options**: audio context, instruments, video playback
* **Theme options**: colors, fonts, layout customization
* **Editor options**: toolbar configuration, notation options

**[View all available embed parameters →](./url-parameters.md)**

## Basic Usage Examples

### Loading a Flat score

The `score` is the identifier you have in our REST API or from our webapp URLs, for example `https://flat.io/score/[score-id]/edit`.

```javascript
const embed = new Flat.Embed(container, {
  score: '56ae21579a127715a02901a6',
  embedParams: {
    appId: '<your-app-id>',
  },
});

// Wait for the embed to be ready
embed.ready().then(() => {
  console.log('Embed is ready!');
});
```

* [Run this example](https://jsfiddle.net/gierschv/7kxudro6/)

### Loading a MusicXML score

```javascript
const embed = new Flat.Embed(container, {
  embedParams: {
    appId: '<your-app-id>',
  },
});

fetch('https://prod.flat-cdn.com/examples/hello-world.xml')
  .then(response => response.text())
  .then(xml => embed.loadMusicXML(xml))
  .then(() => {
    console.log('Embed is ready!');
  });
```

* [Run this example](https://jsfiddle.net/gierschv/7jv10phz/)
* [Learn more about `loadMusicXML()`](./api/score-management.md#loadmusicxml) to Load MusicXML documents

**Related methods:**

* [`ready()`](./api/core.md#ready) - Wait for embed initialization
* [`loadFlatScore()`](./api/score-management.md#loadflatscore) - Load a different score
* [`loadJSON()`](./api/score-management.md#loadjson) - Load Flat JSON format

### Controlling Playback

```javascript
// Start playback
await embed.play();

// Pause playback
await embed.pause();

// Stop playback
await embed.stop();

// Mute/unmute
await embed.mute();
```

**Related methods:**

* [`play()`](./api/playback.md#play) / [`pause()`](./api/playback.md#pause) / [`stop()`](./api/playback.md#stop) - Playback control
* [`mute()`](./api/playback.md#mute) - Mute all audio
* [`setMasterVolume()`](./api/playback.md#setmastervolume) - Adjust overall volume
* [`setPlaybackSpeed()`](./api/playback.md#setplaybackspeed) - Change tempo
* [`setMetronomeMode()`](./api/playback.md#setmetronomemode) - Configure metronome

### Listening to Events

```javascript
// Listen to playback events
embed.on('play', () => {
  console.log('Playback started');
});

embed.on('pause', () => {
  console.log('Playback paused');
});

// Listen to cursor position changes
embed.on('cursorPosition', (position) => {
  console.log('Cursor moved to:', position);
});

// Remove event listener
embed.off('play');
```

**Available events:**

* [`scoreLoaded`](./api/events.md#scoreloaded) - Score finished loading
* [`play`](./api/events.md#play) / [`pause`](./api/events.md#pause) / [`stop`](./api/events.md#stop) - Playback events
* [`cursorPosition`](./api/events.md#cursorposition) - Cursor movement
* [`noteDetails`](./api/events.md#notedetails) - Note information updates
* [View all events →](./api/events.md#available-events)

### Working with Parts

```javascript
// Get all parts in the score
const parts = await embed.getParts();
console.log('Available parts:', parts);

// Set volume for a specific part
await embed.setPartVolume({
  partUuid: parts[0].uuid,
  volume: 75
});

// Mute a part
await embed.mutePart({
  partUuid: parts[0].uuid
});
```

**Related methods:**

* [`getParts()`](./api/parts.md#getparts) - Get all parts information
* [`setPartVolume()`](./api/parts.md#setpartvolume) - Adjust part volume
* [`mutePart()`](./api/parts.md#mutepart) / [`unmutePart()`](./api/parts.md#unmutepart) - Mute controls
* [`setPartSoloMode()`](./api/parts.md#setpartsolomode) - Solo a specific part
* [`setDisplayedParts()`](./api/parts.md#setdisplayedparts) - Show/hide parts

## Editor Mode

You can enable the editor mode by setting the `mode` to `edit` when creating the embed:

```javascript
const embed = new Flat.Embed(container, {
  score: '<score-id>',
  embedParams: {
    appId: '<your-app-id>',
    mode: 'edit',
  },
});
```

[Learn more about the editor mode →](./javascript-editor.md)

## Error Handling

All methods that return promises can be handled with standard error handling:

```javascript
try {
  await embed.loadFlatScore('invalid-id');
} catch (error) {
  console.error('Failed to load score:', error);
}

// Or with promise chains
embed.loadFlatScore('invalid-id')
  .then(() => console.log('Score loaded'))
  .catch(error => console.error('Failed to load score:', error));
```

## Browser Support

The Flat Embed SDK supports all modern browsers:

* Chrome (latest)
* Firefox (latest)
* Safari (latest)
* Edge (latest)

## Need Help?

* Browse the [API Overview](./api/) to see all available methods
* Learn about [Editor Mode](./javascript-editor.md) for score editing
* Configure the embed with [URL Parameters](./url-parameters.md)
* Explore [Live Demos](./demos.md) for inspiration
* [Contact our Developer Support](mailto:developers@flat.io)

---

---
url: /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.

---

---
url: /developers/docs/embed/demos.md
description: Explore live examples and demos of Flat's Embed API in action
---

# Live Demos

Explore our collection of live examples showcasing the power and flexibility of Flat's Embed API. All demos are open-source and available in our [**FlatIO/embed-examples**](https://github.com/FlatIO/embed-examples) repository.

## 🎵 Viewer Demos

These examples demonstrate how to display and interact with sheet music using Flat's embed viewer.

### YouTube Synced Player

Synchronize sheet music playback with YouTube videos:

* Load MusicXML files alongside YouTube videos
* Sync notation display with video timeline
* Perfect for music education and analysis

[Live Demo](https://demos.flat-embed.com/youtube-client/) • [Source Code](https://github.com/FlatIO/embed-examples/blob/master/youtube-client/index.html)

### External Audio Player Integration

Use Flat's beautiful notation rendering with your own audio player:

* Load local MusicXML files
* Connect to custom audio playback systems
* Maintain full control over the audio experience

[Live Demo](https://demos.flat-embed.com/external-audio/) • [Source Code](https://github.com/FlatIO/embed-examples/blob/master/external-audio/index.html)

### Groove Pizza Sheet Music Generator

Transform rhythmic patterns into readable sheet music! This demo integrates with the [Groove Pizza](https://apps.musedlab.org/groovepizza/) app to:

* Generate MusicXML from circular rhythm patterns
* Display the notation instantly using Flat's Embed
* Allow users to print or import the generated music

[Live Demo](https://flatio.github.io/experiment-groovepizza/) • [Source Code](https://github.com/FlatIO/experiment-groovepizza)

## ✏️ Editor Demos

These examples show how to integrate Flat's music notation editor into your applications.

### Embed Editor Basics

Get started with our embeddable editor in just 25 lines of code! This minimal example demonstrates:

* Basic editor initialization
* Loading and saving scores
* Essential API methods

Perfect for developers who want to quickly understand the editor capabilities.

[View Documentation & Code](./javascript-editor)

### Music Snippet - Google Docs Add-on

Insert beautiful sheet music directly into your documents with Music Snippet:

* Create music notation within Google Docs
* Export and insert as high-quality PNG images
* Works with both Google Docs and Slides

This add-on demonstrates how to integrate Flat's editor into third-party platforms.

[Install Add-on](https://gsuite.google.com/marketplace/app/flat_for_docs/324260072797)

## 🚀 Getting Started

Want to build your own integration? Here's how to get started:

1. **Clone the examples repository:**
   ```bash
   git clone https://github.com/FlatIO/embed-examples.git
   cd embed-examples
   ```

2. **Choose an example to explore:**
   * Each demo includes its own README with setup instructions
   * Most examples can run locally with a simple web server

3. **Get your App ID:**
   * Sign up for a [Flat Embed account](https://flat.io/embed)
   * Create an app in your [developer settings](https://flat.io/developers/apps)
   * Use your App ID to authenticate the embed

## 💡 Build Your Own

These demos are just the beginning! The Flat Embed API enables countless possibilities:

* **Education**: Interactive music theory exercises
* **Publishing**: Embedded sheet music in blogs and articles
* **Analysis**: Music visualization and annotation tools
* **Games**: Musical puzzles and learning games
* **Media**: Synchronized playback with video content

Check out our [JavaScript/TypeScript SDK documentation](./javascript) to learn about all available features.

## 📚 Resources

* [JavaScript/TypeScript SDK Reference](./javascript)
* [API Documentation](./api/)
* [URL Parameters](./url-parameters)
* [Editor Mode Guide](./javascript-editor)

## 🤝 Contributing

Have you built something cool with Flat's Embed API? We'd love to feature it!

* Submit a PR to our [examples repository](https://github.com/FlatIO/embed-examples)
* Share your project with us at <developers@flat.io>
* Join our community and get help with your integration

## Need Help?

* 📧 [Contact Developer Support](mailto:developers@flat.io)
* 🐛 [Report issues](https://github.com/FlatIO/embed-examples/issues)

---

---
url: /developers/docs/lti/lti-1.1.md
description: Flat for Education LTI 1.0 and 1.1 legacy integration documentation.
---

# LTI 1.1 (Legacy)

::: warning
LTI 1.1 is a legacy standard. We recommend using [LTI 1.3 (Advantage)](./lti-1.3) for improved security and richer features. Flat for Education supports [seamless migration from LTI 1.1 to LTI 1.3](./lti-1.3#migration-from-lti-1-1-to-lti-1-3).
:::

## Supported Specifications

* **LTI 1.0**
* **LTI 1.1**
* [LTI Outcomes Management Service 1.0](https://www.imsglobal.org/specs/ltiomv1p0/specification)
* [LTI Content Item Message 1.0](https://www.imsglobal.org/specs/lticiv1p0/specification)
* [Light-weight Content Extension](https://www.edu-apps.org/extensions/content.html)
* [Canvas Navigation](https://www.eduappcenter.com/docs/extensions/canvas_navigation)
* [Canvas WYSIWYG](https://www.eduappcenter.com/docs/extensions/canvas_wysiwyg)
* [Canvas Link Selection](https://www.eduappcenter.com/docs/extensions/canvas_link_selection)
* [Canvas Homework](https://canvas.instructure.com/doc/api/file.homework_submission_tools.html)

## Configuration

LTI 1.1 credentials can be activated and managed by a Flat for Education admin in the Integration Hub (**Left navigation > Integrations**) or via our [REST API](/api/reference).

| Setting | Value |
|---|---|
| Cartridge URL | [`https://flat.io/lti/cartridge.xml`](https://flat.io/lti/cartridge.xml) |
| Launch URL | `https://flat.io/lti/launch` |

---

---
url: /developers/docs/lti/lti-1.3.md
description: >-
  Flat for Education LTI 1.3 Advantage integration documentation for platform
  developers and LMS administrators.
---

# LTI 1.3 (Advantage)

Flat for Education is a [certified LTI Advantage provider](https://site.imsglobal.org/certifications/tutteo-ltd/flat-for-education). LTI 1.3 is our recommended integration method, providing improved security and richer features compared to LTI 1.1.

## Supported Specifications

* [LTI 1.3 (Core)](https://www.imsglobal.org/spec/lti/v1p3)
* [LTI Deep Linking 2.0](https://www.imsglobal.org/spec/lti-dl/v2p0)
* [LTI Assignment & Grade Services 2.0](https://www.imsglobal.org/spec/lti-ags/v2p0)
* [LTI Names and Role Provisioning Services 2.0](https://www.imsglobal.org/spec/lti-nrps/v2p0)
* [LTI Submission Review Service 1.0](https://www.imsglobal.org/spec/lti-sr/v1p0)

We support both single-tenant and multi-tenant configurations.

## Tool Endpoints

When configuring Flat for Education as an LTI 1.3 tool in your platform, you will need the following endpoints:

| Setting | Value |
|---|---|
| Launch URL / Target Link URI | `https://flat.io/lti/launch` |
| Redirect URI | `https://flat.io/lti/launch` |
| OpenID Connect Initiation URL | Provided during setup |
| JWKS URL (Public Keyset URL) | Provided during setup |

The OIDC Login Initiation URL and JWKS URL are specific to each platform configuration and will be provided when your integration is set up.

## Setup for Flat for Education Customers

Flat for Education supports **LTI 1.3 dynamic registration** directly from the organization admin panel. Administrators can configure LTI 1.3 connections from the **Integration Hub** (Left navigation > Integrations).

For step-by-step setup instructions for your LMS, see our help center:

* [Canvas LMS](https://help.flat.io/en/education/canvas-lms/setup-1p3/)
* [Schoology](https://help.flat.io/en/education/schoology/lti-1-3-setup/)
* [Moodle](https://help.flat.io/en/education/moodle/)
* [Blackboard Learn](https://help.flat.io/en/education/blackboard/)

## Platform Partnerships & Custom Configuration

If you are a platform developer looking to integrate Flat for Education as an LTI tool, or if you need a custom LTI 1.3 configuration, please contact us at <developers@flat.io>.

We support both single-tenant deployments (one configuration per LMS instance) and multi-tenant deployments (a shared configuration across multiple organizations).

## LTI Advantage Services

### Deep Linking 2.0

Flat for Education supports [LTI Deep Linking 2.0](https://www.imsglobal.org/spec/lti-dl/v2p0), allowing teachers to link assignments and sheet music from Flat's resource library directly within their LMS. When a teacher selects a graded assignment, the maximum score is included in the deep link so the LMS can automatically configure its gradebook.

### Assignment & Grade Services 2.0

Flat for Education supports [LTI Assignment & Grade Services 2.0](https://www.imsglobal.org/spec/lti-ags/v2p0) for automatic grade synchronization with the LMS gradebook.

Grades are synced at every stage of the submission lifecycle:

| Flat for Education Submission State | LTI AGS Activity Progress | LTI AGS Grading Progress |
|---|---|---|
| Created | `Started` | `NotReady` |
| Turned in | `Submitted` | `PendingManual` |
| Returned | `Completed` | `FullyGraded` |
| Graded | `Completed` | `FullyGraded` |

In addition to grades, Flat for Education sends submission timestamps and, when applicable, the identity of the teacher who graded the submission.

### Names and Role Provisioning Services 2.0

Flat for Education supports [LTI Names and Role Provisioning Services 2.0](https://www.imsglobal.org/spec/lti-nrps/v2p0) for automatic class roster synchronization. When enabled, class rosters are imported from the LMS and kept in sync automatically, including support for incremental updates when available from the LMS.

### Submission Review Service

Flat for Education supports the [LTI Submission Review Service 1.0](https://www.imsglobal.org/spec/lti-sr/v1p0), enabling teachers to access detailed student submission reviews directly from their LMS gradebook.

## Migration from LTI 1.1 to LTI 1.3

Flat for Education supports the [LTI 1.1 migration claim](https://www.imsglobal.org/spec/lti/v1p3/migr), allowing a seamless transition from LTI 1.1 to LTI 1.3. User accounts are automatically matched when upgrading, ensuring that existing class memberships, assignments, and grades are preserved.

The LTI launch and deep link URLs are the same between LTI 1.1 and LTI 1.3, so existing links created with LTI 1.1 will continue to work after upgrading.

## REST API

LTI credentials can also be managed programmatically through our [REST API](/api/reference). See the [Flat for Education API documentation](/api/flat-for-education) for more information.

---

---
url: /developers/docs/embed/api/navigation.md
description: Navigate through the score and control cursor position
---

# Navigation & Cursor

Navigate through the score and control cursor position

## Methods

### focusScore() {#focusscore}

Set focus to the score

Gives keyboard focus to the score iframe, allowing keyboard shortcuts and navigation to work. This is useful when embedding multiple interactive elements on a page.

```typescript
focusScore(): Promise<void>
```

**Returns:** `Promise<void>`

**Examples:**

```typescript
// Focus score for keyboard interaction
await embed.focusScore();
```

```typescript
// Focus score when user clicks a button
document.getElementById('editBtn').addEventListener('click', () => {
  embed.focusScore();
});
```

***

### getCursorPosition() {#getcursorposition}

Get the cursor position

Retrieves the current position of the cursor in the score, including the part, measure, voice, and note location.

```typescript
getCursorPosition(): Promise<NoteCursorPosition>
```

**Returns:** `Promise<NoteCursorPosition>`

**NoteCursorPosition**

Complete cursor position information within a score

Properties:

* `partIdx`: `number` - Zero-based index of the part
* `partUuid`: `string` - Unique identifier of the part
* `staffIdx`: `number` - Zero-based index of the staff within the part
* `staffUuid`: `string` - Unique identifier of the staff
* `voiceIdxInStaff`: `number` - Zero-based index of the voice within the staff
* `voiceUuid`: `string` - Unique identifier of the voice
* `measureIdx`: `number` - Zero-based index of the measure
* `measureUuid`: `string` - Unique identifier of the measure
* `noteIdx`: `number` - Zero-based index of the note within the voice
* `line`: `number` - Staff line number (0 = bottom line)
* `dpq`: `number` - Divisions per quarter note (timing resolution)
* `timePos`: `number` - Absolute time position in seconds from the beginning

**Throws:**

* `Error` - If cursor position cannot be retrieved

**Example:**

```typescript
const embed = new Embed('container', config);

// Get the current cursor position
const position = await embed.getCursorPosition();
console.log('Current cursor position:', {
  part: position.partIdx,
  staff: position.staffIdx,
  measure: position.measureIdx,
  note: position.noteIdx,
});

// Use cursor position to get note details
if (position.noteIdx >= 0) {
  const parts = await embed.getPartsUuids();
  const measures = await embed.getMeasuresUuids();
  const voices = await embed.getMeasureVoicesUuids({
    partUuid: parts[position.partIdx],
    measureUuid: measures[position.measureIdx],
  });

  if (voices.length > 0) {
    const noteData = await embed.getNoteData({
      partUuid: parts[position.partIdx],
      measureUuid: measures[position.measureIdx],
      voiceUuid: voices[0],
      noteIdx: position.noteIdx,
    });
    console.log('Note at cursor:', noteData);
  }
}
```

**See also:**

* [`setCursorPosition()`](#setcursorposition) - Set cursor position
* [`goLeft()`](#goleft) - Move cursor left
* [`goRight()`](#goright) - Move cursor right

***

### setCursorPosition() {#setcursorposition}

Set the cursor position

Moves the cursor to a specific position in the score. You can specify any combination of part, measure, voice, staff, and note indices. Unspecified values remain at their current position.

```typescript
setCursorPosition(position: NoteCursorPositionOptional): Promise<void>
```

**Parameters:**

* `position` - `NoteCursorPositionOptional`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the position is invalid or cursor cannot be moved

**Examples:**

```typescript
// Move to beginning of measure 5
await embed.setCursorPosition({
  measureIdx: 4,  // 0-based index
  noteIdx: 0
});
```

**See also:**

* [`getCursorPosition()`](#getcursorposition) - Get current position

***

### goLeft() {#goleft}

Move cursor left

Moves the cursor to the previous item in the score (note, rest, or grace note). Navigation follows the reading order of the score.

```typescript
goLeft(mute?: boolean): Promise<void>
```

**Parameters:**

* `mute` *(optional)* - `boolean`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If cursor cannot move (e.g., at beginning of score)

**Examples:**

```typescript
// Move left silently
await embed.goLeft(true);
```

**See also:**

* [`goRight()`](#goright) - Move cursor right
* [`setCursorPosition()`](#setcursorposition) - Set specific position

***

### goRight() {#goright}

Move cursor right

Moves the cursor to the next item in the score (note, rest, or grace note). Navigation follows the reading order of the score.

```typescript
goRight(mute?: boolean): Promise<void>
```

**Parameters:**

* `mute` *(optional)* - `boolean`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If cursor cannot move (e.g., at end of score)

**Examples:**

```typescript
// Move right and play the note
await embed.goRight();
```

**See also:**

* [`goLeft()`](#goleft) - Move cursor left
* [`setCursorPosition()`](#setcursorposition) - Set specific position

***

### scrollToCursor() {#scrolltocursor}

Scroll to cursor position

Scrolls the score view to ensure the cursor is visible on screen. This is useful after programmatically moving the cursor or when the cursor moves out of view during navigation.

```typescript
scrollToCursor(): Promise<void>
```

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If scrolling fails

**Examples:**

```typescript
// Move cursor and scroll to it
await embed.setCursorPosition({ measureIdx: 20 });
await embed.scrollToCursor();
```

**Note:** Scrolling is performed asynchronously and may not complete before the promise resolves

**See also:**

* [`setCursorPosition()`](#setcursorposition) - Set cursor position

***

---

---
url: /developers/docs/notices.md
---

# Notices

The content of this documentation is copyright © Flat Developer Documentation authors, released under [CC-BY-SA-4.0](https://creativecommons.org/licenses/by-sa/4.0/), which gives you permission to use content for almost any purpose (but does not grant you any trademark permissions), so long as you note the license and give credit, such as follows:

> Content based on <https://flat.io/developers/docs> used under the CC-BY-SA-4.0 license.

Code samples if any included in this documentation content are released under [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/), which means you can use them in your own projects without any restrictions.

When you contribute to this repository you are doing so under the above licenses.

"Flat" is a trademark of Tutteo Limited, registered in Europe.
Logos and graphic resources are Copyright © Tutteo Limited.
More general legal notices [are available on our website](https://flat.io/legal/).

---

---
url: /developers/docs/api/omr/faq.md
description: >-
  Answers to the questions developers ask most about Flat's Optical Music
  Recognition API: access, credits and billing, limits and performance,
  recognition quality, and data privacy.
---

# OMR API FAQ

The questions developers ask us most about Flat's
[Optical Music Recognition API](/api/omr/), grouped by topic. If your question is not answered here,
email <developers@flat.io>.

## Browse by topic

| Topic | What it covers |
|:--|:--|
| **[Credits and billing](/api/omr/faq/credits)** | How credits are counted, what a job costs, refunds, `402` errors, packs, and volume pricing. |
| **[Limits, performance, and integration](/api/omr/faq/limits)** | Page, file, and size limits, concurrency, processing time, and serving many end users from one account. |
| **[Recognition quality and languages](/api/omr/faq/quality)** | What OMR reads well, lyric language support, what to do about a bad conversion, and ML model versions. |
| **[Commercial use, privacy, and data](/api/omr/faq/legal)** | Commercial rights to the output, model training, data retention, deletion, and the DPA. |

## Getting started

### How do I get access to the OMR API?

Create a [Flat account](https://flat.io), then generate a
[personal access token](/api/authentication#personal-access-tokens) from your developer settings.
There is no separate OMR signup, waitlist, or approval step, and the same token works for both
[OMR flows](/api/omr/#two-ways-to-import).

If you are building an OAuth2 app for other people's accounts instead, request the `omr` scope, plus
`scores` when the result goes into their Flat Library. See
[Authentication and scopes](/api/omr/#authentication-and-scopes).

### Is there a free trial or a sandbox?

There is no self-serve trial or sandbox environment, but **almost the entire integration can be
built and tested for free**. Only starting a job costs anything.

Free, no credits consumed:

* [`GET /omr/capabilities`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrCapabilities),
  which needs no authentication at all, so you can wire up feature detection, limits, and your
  language picker before a user ever connects an account.
* Creating a [draft job](/api/omr/jobs#step-1-create-a-draft-job) with `POST /omr/jobs`.
* Uploading files to it with `POST /omr/jobs/{job}/files`, including the multi-page and
  incremental-capture flow.
* Listing your jobs, and [canceling](/api/omr/jobs#cancel-a-job) a draft you never started.

**Only [`POST /omr/jobs/{job}/start`](/api/omr/jobs#step-3-start-the-job) runs the conversion and
charges credits**, along with `autoStart: true` on the one-shot form and the
[auto simple import](/api/omr/import). So you can exercise your upload path, your error handling,
and your whole draft state machine end to end before spending a single credit.

If you are evaluating OMR for a product and need to discuss it, email
<developers@flat.io> and tell us what you are building and roughly what
volume you expect.

### Which flow should I use, the Jobs API or the simple import?

Reach for the **[Interactive Jobs API](/api/omr/jobs)** when you want live progress, an optional step
for the user to correct detected instruments, MusicXML or MIDI output **without** creating a Flat
score, or the ability to add pages one at a time (which is how mobile capture works).

Reach for the **[auto simple import](/api/omr/import)** when you just want a score in the Flat
Library and you are already importing MusicXML or MIDI through
[`POST /scores`](https://flat.io/developers/docs/api/reference#tag/Score/operation/createScore). It
is two calls and one code path for every format.

The [comparison table](/api/omr/#two-ways-to-import) on the overview page lays the two side by side.

### Is the OMR API the same thing as Opuscan?

No. [Opuscan](https://www.opuscan.com/omr/) is our dedicated consumer scan-to-score product, sold
through the app stores. It runs on the same recognition engine, but it is a separate product with no
developer API, and **its credits are not shared with a Flat account or with this API**. See
[Do credits bought in the Opuscan apps work with the API?](/api/omr/faq/credits#do-credits-bought-in-the-opuscan-apps-work-with-the-api)

## Related

* [OMR overview](/api/omr/) for scopes, credits, capabilities, and error codes.
* [Interactive Jobs API](/api/omr/jobs) and [auto simple import](/api/omr/import).
* [API Reference: OMR](https://flat.io/developers/docs/api/reference#tag/OMR).

---

---
url: /developers/docs/api/omr/faq/legal.md
description: >-
  Whether you can use Flat's OMR API commercially and resell the output, whether
  uploads train our models, how long data is kept, what survives deletion, and
  where to find the DPA.
---

# Commercial use, privacy, and data

The answers evaluators and procurement teams ask for before building on Flat's
[Optical Music Recognition API](/api/omr/).

## Commercial use

### Can I use OMR commercially and resell the output?

**Yes.** You can use the OMR API to process sheet music uploaded by customers who own the content or
otherwise hold the necessary rights, and provide the resulting **MusicXML and MIDI files to those
customers outside of Flat**.

Specifically:

* **No attribution is required** for the generated files.
* **Nothing prevents you from building a commercial transcription product** on the API.
* **You are not required to keep the result in a Flat library.** Create the job with
  `output: "musicxml"` and the result never enters one. See
  [Do I have to create a Flat score?](/api/omr/faq/limits#do-i-have-to-create-a-flat-score)
* **One account can serve all your end users.** They do not need Flat accounts of their own. See
  [Can my backend use one account for all my end users?](/api/omr/faq/limits#can-my-backend-use-one-account-for-all-my-end-users)

As always, you and your users remain responsible for having the appropriate rights to the source
material and for complying with applicable law.

### Can I store and reuse the MusicXML?

Yes. The output is yours. Store it, reuse it, and serve it to as many of your users as you like.
Deduplicating conversions on your side is also the easiest way to reduce credit spend. See
[Can I cache and reuse the output?](/api/omr/faq/limits#can-i-cache-and-reuse-the-output-instead-of-converting-the-same-pages-again)

### Do I need a custom contract?

Not for standard API usage with [credit packs](/api/omr/faq/credits#do-credit-packs-expire-or-auto-renew).
For larger-volume deployments, custom pricing, or specific contractual requirements, email
<developers@flat.io> and we can put a business agreement in place.

## Privacy and model training

### Do you train your ML models on my files?

**No.** Flat's OMR machine-learning models are trained entirely on **synthetic data we generate
ourselves**
with our own engraving engine, and on **public-domain sheet music we source independently**.

Files you submit to the OMR API, and the outputs generated from them, are **not used to train or
improve our models**.

### Where is the data processed, and who are the subprocessors?

Our infrastructure providers, subprocessors, and hosting regions are documented publicly in the
[data and infrastructure article](https://help.flat.io/en/general/data-infrastructure/#infrastructure-providers).

## Retention and deletion

### How long is my data kept?

Jobs created with `output: "musicxml"` keep their uploaded files and recognition results for
**30 days by default**, then they are erased.

Read the exact window from `retentionDays` on
[`GET /omr/capabilities`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrCapabilities),
and each job's own deadline from `retention.expiryDate`. The deadline is fixed when the job is
created, so a later change to the retention window never moves it.

Jobs created with `output: "library"` have no `retention` object at all: their result is a score in
the user's library and follows the library's own lifecycle.

Full detail, including the API calls, is in
[Retention and deletion](/api/omr/jobs#retention-and-deletion).

### Can I delete a job before the deadline?

Yes, and you should as soon as you have collected what you need:

```bash
curl -X DELETE "https://api.flat.io/v2/omr/jobs/$JOB" -H "Authorization: Bearer $TOKEN"
```

The call is idempotent. Downloads for an erased job then return `409` (`OMR_JOB_EXPIRED`).

If you need a **shorter default retention period** for your account, email
<developers@flat.io>.

### What survives deletion?

The originals, recognition results, and processing logs are all stored under a **single dedicated
prefix in our object storage**. At expiry, or when you call `DELETE`, that prefix and everything in
it is permanently deleted. **We do not maintain backups or replicas of this data**, so once it is
gone it is gone.

What remains is a **stripped job record** kept for accounting and for listing your job history:

| Kept | Not kept |
|:--|:--|
| Job id, creation and expiry dates | The uploaded files |
| Status the job finished with | Recognition results and exports |
| Page and file counts | Filenames and checksums |
| File size and MIME type | Any document content |
| Billing information | Processing and debug logs |

The job stays listable with `retention.expiredDate` set, so you can still audit what you ran. Filter
on it with `GET /omr/jobs?status=done&expired=false`.

## Terms and agreements

### Which terms govern the OMR API?

The OMR API is covered by Flat's
[Terms of Service and Privacy Policy](https://help.flat.io/en/policies/).

### Is a DPA available?

Yes. You can rely on our published
[Data Processing Addendum](https://help.flat.io/en/education/policies/data-processing-addendum/).

For specific contractual requirements beyond it, email
<developers@flat.io>.

## Related

* [Retention and deletion](/api/omr/jobs#retention-and-deletion) in the Jobs API.
* [Credits and billing](/api/omr/faq/credits).
* [Limits, performance, and integration](/api/omr/faq/limits).

---

---
url: /developers/docs/api/omr/faq/credits.md
description: >-
  How Flat's OMR API is billed: 1 credit per page, the shared credit pool, what
  happens to credits on failed jobs, why you get a 402, credit packs, and volume
  pricing.
---

# Credits and billing

How Flat's [Optical Music Recognition API](/api/omr/) is paid for. See
[Capabilities and credits](/api/omr/#capabilities-and-credits) on the overview page for the
reference version.

## Counting and charging

### How are credits counted?

**1 credit is 1 page.** A 4 page PDF costs 4 credits, whichever
[flow](/api/omr/#two-ways-to-import) you use. Credits are charged when the job **starts**, based on
the total page count across every file in the job.

Everything before that point is free. Creating a draft job, uploading its files, listing your jobs,
and canceling a draft cost nothing: only
[`POST /omr/jobs/{job}/start`](/api/omr/jobs#step-3-start-the-job) (and `autoStart: true`, and the
[auto simple import](/api/omr/import)) runs the conversion and bills for it.

Do not hardcode the ratio. Read `costPerPage` from
[`GET /omr/capabilities`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrCapabilities),
which is the authoritative value for the authenticated account.

### Does the API use the same credits as the Flat apps?

Yes. **One pool per Flat account**, shared by the web, desktop, and mobile apps and the API.

For each job, credits are taken in this order:

1. The page allowance included in the account's Flat or Flat for Education **subscription**.
2. Any **credit packs** bought on the account.

This surprises people who expect the API to meter separately. If your subscription includes a
monthly page allowance, a handful of API conversions can use it up.

### Whose credits are spent?

The credits of the **Flat account that owns the token** you authenticate with. With a
[personal access token](/api/authentication#personal-access-tokens) that is your own account; with
OAuth2, it is the account of the user who authorized your app. See
[Whose credits are spent](/api/omr/#whose-credits-are-spent).

### Do failed, cancelled, or retried jobs consume credits?

**Only successful conversions ultimately consume credits.** Credits are charged at job start, then
reverted when:

* the job ends in `error`, whatever the [`errorCode`](/api/omr/#errors), or
* the job is [cancelled](/api/omr/jobs#cancel-a-job) before the worker finishes, including a draft
  you created and never started.

A job you retry after a failure is charged like any other job, and the failed attempt is refunded.

## Estimating and monitoring spend

### How do I estimate cost before running a batch?

Multiply your total page count by `costPerPage`. To avoid a `402` in the middle of a user flow,
preflight against `GET /omr/capabilities`, which returns both `costPerPage` and the account's
`remainingCredits`:

```js
const caps = await fetch('https://api.flat.io/v2/omr/capabilities', { headers: auth }).then((r) => r.json());

const cost = pageCount * caps.costPerPage;
if (cost > caps.remainingCredits) {
  // Send the user to https://flat.io/settings/ai-credits before starting the job.
}
```

`remainingCredits` is only returned on an **authenticated** request, since there is no account to
report a balance for otherwise. The rest of the response, `costPerPage` included, works
unauthenticated, so you can feature-detect before a user connects an account.

### Why did I get a `402`?

A `402` means the account behind your token cannot pay for the job. It is out of credits, over quota,
or on a plan that does not include OMR. Top up at
[flat.io/settings/ai-credits](https://flat.io/settings/ai-credits?ref=dev-docs-omr-faq).

The fix in your code is the preflight check above: read `remainingCredits` before you start a job and
surface a clear message, rather than letting the user discover the problem when the job fails.

### Where can I see my usage history?

There is **no credit-usage history endpoint** in the public API yet. To audit what you have spent,
list your finished jobs and count their pages:

```bash
curl -H "Authorization: Bearer $TOKEN" "https://api.flat.io/v2/omr/jobs?status=done"
```

[`GET /omr/jobs`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/listOmrJobs)
returns your jobs newest first with cursor pagination through the `Link` header. Your current balance
is always available as `remainingCredits` on `GET /omr/capabilities`.

## Buying credits

### Do credit packs expire or auto-renew?

Credit packs are **one-off purchases**. They are not a subscription, they do not auto-renew, and they
do not expire while the account is active. Buy them on
[your account's AI credits page](https://flat.io/settings/ai-credits?ref=dev-docs-omr-faq).

Packs currently on sale, generated from the live catalog:

| Pack | Price | Per page |
|:--|:--|:--|
| 30 pages | $9.99 | $0.333 |
| 70 pages | $18.99 | $0.271 |
| 300 pages | $49.99 | $0.167 |
| 1,000 pages | $149 | $0.149 |
| 3,000 pages | $300 | $0.10 |

List prices in USD, excluding any local tax. Your own currency and the tax that applies to
you are shown at checkout on [your account's AI credits page](https://flat.io/settings/ai-credits?ref=dev-docs-omr-faq).

The **1,000 and 3,000 page packs** are behind the **"Need 1000+ credits?"** link on that page, not in
the default grid. If you only see the smaller packs, that link is what you are looking for.

### Is there volume pricing?

Yes, and it is self-serve. The **price per page improves at every pack size**, not just the largest
ones, as the table above shows. Most integrations never need to talk to us about pricing: buy the
pack that matches your volume.

If you expect volumes well beyond the largest pack, or you have specific contractual requirements,
email <developers@flat.io> and we will work out something that fits.

### Do credits bought in the Opuscan apps work with the API?

**No.** [Opuscan](https://www.opuscan.com/omr/) is a separate consumer product sold through the app
stores. Purchases made inside Opuscan are tied to the store account that made them, and are **not
shared with a Flat account or with this API**.

Credits for the API must be on the Flat account behind your token, bought at
[flat.io/settings/ai-credits](https://flat.io/settings/ai-credits?ref=dev-docs-omr-faq). The same
applies in reverse: credits on your Flat account do not appear inside the Opuscan apps.

## Related

* [Capabilities and credits](/api/omr/#capabilities-and-credits) on the OMR overview.
* [Limits, performance, and integration](/api/omr/faq/limits).
* [Commercial use, privacy, and data](/api/omr/faq/legal).

---

---
url: /developers/docs/api/omr/jobs.md
description: >-
  Drive Flat's resumable Optical Music Recognition (OMR) pipeline. Create a job,
  upload pages, follow live progress, review detected instruments, and download
  MusicXML or import to the Library.
---

# OMR Interactive Jobs API

The Interactive Jobs API exposes Flat's **Optical Music Recognition (OMR)** pipeline directly through
the `/omr/jobs` endpoints. Use it when you need more than a one-shot import: **live progress**, an
optional **review step** to confirm the detected instruments, **incremental capture** (add pages one by
one, ideal on mobile), or **MusicXML output** without creating a Library score.

If you just want a score in the Library from a single PDF, the
[Auto simple import](/api/omr/import) is fewer calls. New to OMR? Start with the
[OMR overview](/api/omr/) for scopes, credits, and error codes.

## Job lifecycle

A job is a small state machine. You create it, start it, optionally answer interactive steps while it
runs, and read the result when it is `done`.

![OMR job lifecycle state machine: draft to processing to done, with an optional pause and submit loop through awaitingInput, and terminal transitions to canceled and error.](/img/omr/lifecycle.svg)

| `status` | Meaning |
|:--|:--|
| `draft` | Created; files can still be added. Not started or charged yet. |
| `processing` | The pipeline is running. See `progress`. |
| `awaitingInput` | Paused on `currentStep`, waiting for you to submit it. |
| `done` | Finished. See `result`. |
| `error` | Failed. See `errorCode` and `errorMessage`. |
| `canceled` | Canceled by the client. |

In this page:

* [Prerequisites](#prerequisites)
* [Draft vs one-shot](#draft-vs-one-shot)
* [Step 1. Create a draft job](#step-1-create-a-draft-job)
* [Step 2. Add files](#step-2-add-files)
* [Step 3. Start the job](#step-3-start-the-job)
* [Step 4. Follow progress](#step-4-follow-progress)
* [Step 5. Review detected instruments](#step-5-review-detected-instruments)
* [Step 6. Get the result](#step-6-get-the-result)
* [One-shot import](#one-shot-import)
* [Exports](#exports)
* [List and resume jobs](#list-and-resume-jobs)
* [Cancel a job](#cancel-a-job)
* [Errors](#errors)

## Prerequisites

Every request needs the `omr` scope (with a [Personal Access Token](/api/authentication#personal-access-tokens)
or an OAuth2 token). With the default `output: library`, the job creates a score, so an OAuth2 token
also needs the `scores` scope. `output: musicxml` only needs `omr`. See
[Authentication and scopes](/api/omr/#authentication-and-scopes).

The examples below use these variables:

::: code-group

```bash [curl]
export TOKEN='<my_api_personal_access_token>'
```

```js [JavaScript]
const TOKEN = '<my_api_personal_access_token>';
const auth = { Authorization: `Bearer ${TOKEN}` };
```

```python [Python]
import base64, time, requests

TOKEN = "<my_api_personal_access_token>"
auth = {"Authorization": f"Bearer {TOKEN}"}
```

:::

## Draft vs one-shot

There are two ways to create a job:

* **Draft** (this walkthrough): create an empty job, add files one at a time, then start it. Best for
  multiple images or incremental mobile capture, where pages arrive over time.
* **[One-shot](#one-shot-import)**: send the files inline with `autoStart: true` in a single request.
  Best for a single PDF or a straightforward third-party integration.

Both produce the same kind of job. Pick whichever fits how your client captures files.

## Step 1. Create a draft job

Create the job with
[`POST /omr/jobs`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/createOmrJob). Omit
`files` to get a draft. Declare the interactive steps your client can render in `interactiveSteps`
(here, `details`); the pipeline pauses only at the steps you list and auto-resolves the rest, so
future steps never break an older client.

::: code-group

```bash [curl]
curl -X POST "https://api.flat.io/v2/omr/jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "output": "musicxml",
    "interactiveSteps": ["details"],
    "locales": ["en"]
  }'
```

```js [JavaScript]
let res = await fetch('https://api.flat.io/v2/omr/jobs', {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    output: 'musicxml',
    interactiveSteps: ['details'],
    locales: ['en'],
  }),
});
let job = await res.json();
const jobId = job.id;
```

```python [Python]
job = requests.post(
    "https://api.flat.io/v2/omr/jobs",
    headers=auth,
    json={"output": "musicxml", "interactiveSteps": ["details"], "locales": ["en"]},
).json()
job_id = job["id"]
```

:::

`locales` tells the recognition pipeline which languages to read **lyrics and text** in. It does not
affect the notation. Build your picker from `localesDetails` on
[`GET /omr/capabilities`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrCapabilities)
rather than hardcoding a list, and note that an unsupported language yields garbled lyrics rather
than an error. See [Which languages are supported for lyrics?](/api/omr/faq/quality#which-languages-are-supported-for-lyrics)

The response is a job in `draft`:

```json
{
  "id": "665f3a1c9b2e4a0012ab34cd",
  "status": "draft",
  "output": "musicxml",
  "interactiveSteps": ["details"],
  "locales": ["en"],
  "creationDate": "2026-07-08T09:24:00.000Z"
}
```

This example uses `output: "musicxml"`, which only needs the `omr` scope and lets you download the
result directly. To import the result into the Flat Library instead, set `output: "library"` (the
default), add the `scores` scope, and use `collection` to target a specific collection. Pass
`idempotencyKey` to make retries safe (a repeated key returns the existing job).

## Step 2. Add files

Add one image or PDF per call with
[`POST /omr/jobs/{job}/files`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/addOmrJobFile).
Files keep their upload order. The file is Base64-encoded in `file`.

::: code-group

```bash [curl]
curl -X POST "https://api.flat.io/v2/omr/jobs/$JOB/files" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{ \"file\": \"$(base64 < page1.jpg | tr -d '\n')\", \"filename\": \"page1.jpg\" }"
```

```js [JavaScript]
import { readFileSync } from 'node:fs';

res = await fetch(`https://api.flat.io/v2/omr/jobs/${jobId}/files`, {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    file: readFileSync('page1.jpg').toString('base64'),
    filename: 'page1.jpg',
  }),
});
const { fileCount } = await res.json();
```

```python [Python]
with open("page1.jpg", "rb") as f:
    payload = {"file": base64.b64encode(f.read()).decode(), "filename": "page1.jpg"}

added = requests.post(f"https://api.flat.io/v2/omr/jobs/{job_id}/files", headers=auth, json=payload).json()
```

:::

The response reports the assigned index and running count: `{ "fileIndex": 0, "fileCount": 1 }`.
Provide either a `filename` with a recognizable extension or an explicit `mimeType`; if the type cannot
be determined from either, the call returns `400` (`OMR_MIME_REQUIRED`). Repeat for each page.

**Upload order is page order**, and there is no reorder parameter, so let the user settle the order
before you start uploading. On mobile, the platform's on-device document scanner gives you that pass
for free, along with cropping and perspective correction. See
[Capturing on mobile](/api/omr/faq/quality#capturing-on-mobile).

## Step 3. Start the job

Start processing with
[`POST /omr/jobs/{job}/start`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/startOmrJob).
This validates the files, runs the permission, quota, and credit checks, charges the page-based
credits, and queues the job.

::: code-group

```bash [curl]
curl -X POST "https://api.flat.io/v2/omr/jobs/$JOB/start" -H "Authorization: Bearer $TOKEN"
```

```js [JavaScript]
res = await fetch(`https://api.flat.io/v2/omr/jobs/${jobId}/start`, { method: 'POST', headers: auth });
job = await res.json(); // status: "processing", estimatedCredits: N
```

```python [Python]
job = requests.post(f"https://api.flat.io/v2/omr/jobs/{job_id}/start", headers=auth).json()
```

:::

The job returns as `processing` with `estimatedCredits` set to what was charged. A start with no
files returns `400`; insufficient credits or quota returns `402`, and the account needs
[more credits](/api/omr/#buying-credits).

## Step 4. Follow progress

Poll [`GET /omr/jobs/{job}`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrJob)
to track the job. Optionally pass `wait` (0 to 25 seconds) to **long-poll**: the call returns as soon
as the state changes (or live progress advances), then you call again. This keeps progress live without
a tight loop.

While `processing`, the job carries a `progress` object with a `percent`, a localized `text`, and a
stable `key` you can map to your own stepper UI. The pipeline runs roughly `OMR_QUEUED`,
`OMR_DETECTING_STAVES`, `OMR_READING_NOTES` (or `OMR_PROCESSING_PAGE`, both carrying `current` and
`total` page parameters), `OMR_ASSEMBLING`, then `OMR_CREATING_SCORE`. New keys may be added, so
match the ones you handle and keep a generic fallback.

::: code-group

```bash [curl]
# Returns as soon as the state changes, or after 25s.
curl -H "Authorization: Bearer $TOKEN" "https://api.flat.io/v2/omr/jobs/$JOB?wait=25"
```

```js [JavaScript]
async function pollUntilSettled(jobId) {
  while (true) {
    const res = await fetch(`https://api.flat.io/v2/omr/jobs/${jobId}?wait=25`, { headers: auth });
    const job = await res.json();
    if (job.status !== 'processing') return job; // awaitingInput, done, error, canceled
    console.log(job.progress?.percent, job.progress?.key);
  }
}
```

```python [Python]
def poll_until_settled(job_id):
    while True:
        job = requests.get(f"https://api.flat.io/v2/omr/jobs/{job_id}", params={"wait": 25}, headers=auth).json()
        if job["status"] != "processing":
            return job  # awaitingInput, done, error, canceled
        print(job.get("progress", {}).get("percent"), job.get("progress", {}).get("key"))
```

:::

The job settles into `awaitingInput` (if a detection needs your review), `done`, or `error`.

## Step 5. Review detected instruments

If you declared `details` in `interactiveSteps`, the job **may** pause at `awaitingInput` after
recognition, with `currentStep: "details"`, so you can review low-confidence detections. It may also
resolve automatically and continue straight to `done`, for example when every part is recognized with
high confidence. Always handle both outcomes: after processing, a job can be `awaitingInput` or already
`done`.

When it does pause, `pendingStep.data` holds the detected title and instruments for review (the "check
your score details" screen):

```json
{
  "id": "665f3a1c9b2e4a0012ab34cd",
  "status": "awaitingInput",
  "currentStep": "details",
  "estimatedCredits": 3,
  "pendingStep": {
    "step": "details",
    "data": {
      "step": "details",
      "title": "Sonata in C",
      "instruments": [
        { "index": 0, "partName": "Violin I", "instrumentId": "strings.violin", "instrumentName": "Violin", "midiProgram": 40, "resolvedConfidence": "high" },
        { "index": 1, "partName": "Alto", "instrumentId": "strings.violin", "instrumentName": "Violin", "midiProgram": 40, "resolvedConfidence": "low" }
      ]
    }
  }
}
```

![The "check your score details" review step: a work title field and a list of detected parts with instrument names, Flat instrument IDs, and high/low confidence chips, with a low-confidence part being corrected via an instrument picker.](/img/omr/review-step.svg)

To show the pages being reviewed, fetch each input image by index with
[`GET /omr/jobs/{job}/files/{index}`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrJobFile)
(0-based; returns the input page as an image).

Present these to the user, then resume the pipeline by submitting your corrections to
[`POST /omr/jobs/{job}/steps/details`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/submitOmrJobStep).
Send only what you change: omitted fields keep the detected values. Here we fix the second part and
tidy the title:

::: code-group

```bash [curl]
curl -X POST "https://api.flat.io/v2/omr/jobs/$JOB/steps/details" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "step": "details",
    "title": "Sonata in C major",
    "instruments": [
      { "index": 1, "instrumentId": "strings.viola" }
    ]
  }'
```

```js [JavaScript]
res = await fetch(`https://api.flat.io/v2/omr/jobs/${jobId}/steps/details`, {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    step: 'details',
    title: 'Sonata in C major',
    instruments: [{ index: 1, instrumentId: 'strings.viola' }],
  }),
});
job = await res.json(); // status back to "processing"
```

```python [Python]
job = requests.post(
    f"https://api.flat.io/v2/omr/jobs/{job_id}/steps/details",
    headers=auth,
    json={
        "step": "details",
        "title": "Sonata in C major",
        "instruments": [{"index": 1, "instrumentId": "strings.viola"}],
    },
).json()
```

:::

The job resumes and re-runs only the cheap assembly and finalize stages. Poll again (step 4) until it
is `done`.

### Correcting a part

Each override in `instruments[]` is matched to a detected part by its `index`. To set the instrument,
use **either** of these (you do not need both):

* `instrumentId`: a Flat instrument ID such as `brass.horn`. Browse the [Instrument IDs](/api/instruments)
  catalog, or resolve IDs programmatically with the
  [`@flat/instruments`](https://www.npmjs.com/package/@flat/instruments) package.
* `midiProgram`: a General MIDI program number (0 to 127), resolved server-side. Handy when you would
  rather not map Flat instrument IDs.

If both are sent, `instrumentId` wins. You can also set `partName` and `transposeKey` (a pitch class
like `F` or `Bb`, for transposing instruments) independently. At the submission level, `title` and
`mainLanguage` (BCP 47, overrides the job locale for lyric and text reading) apply to the whole
score. This is the natural place to let a user correct the language after seeing the detected title.
See [What do `locales` and `mainLanguage` actually do?](/api/omr/faq/quality#what-do-locales-and-mainlanguage-actually-do)

## Step 6. Get the result

When the job is `done`, `result` tells you what is available:

```json
{
  "status": "done",
  "result": {
    "exports": ["musicxml", "mxl", "midi"]
  }
}
```

* With `output: musicxml` (used above), the result stays out of the Flat Library. You download it
  directly as a file (MusicXML, MIDI, and more) from the [exports endpoint](#exports). Use this when
  your integration keeps files in its own system and does not need a Flat score.
* With `output: library` (the default), the result is imported into the user's Flat Library as a score.
  `result.score` holds the new score ID. Fetch it with
  [`GET /scores/{score}`](https://flat.io/developers/docs/api/reference#tag/Score/operation/getScore),
  and it behaves like any other Flat score. You can still download the raw files from the
  [exports endpoint](#exports).

## One-shot import

To skip the draft sequence, send the files inline with `autoStart: true`. The job is created,
started, and charged in one call, returning `202` with a `processing` job. This is the simplest path
for a single PDF when you do not need to add pages incrementally.

::: code-group

```bash [curl]
curl -X POST "https://api.flat.io/v2/omr/jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{
    \"output\": \"musicxml\",
    \"autoStart\": true,
    \"files\": [ { \"file\": \"$(base64 < score.pdf | tr -d '\n')\", \"filename\": \"score.pdf\" } ]
  }"
```

```js [JavaScript]
res = await fetch('https://api.flat.io/v2/omr/jobs', {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    output: 'musicxml',
    autoStart: true,
    files: [{ file: readFileSync('score.pdf').toString('base64'), filename: 'score.pdf' }],
  }),
});
job = await res.json();
```

```python [Python]
with open("score.pdf", "rb") as f:
    files = [{"file": base64.b64encode(f.read()).decode(), "filename": "score.pdf"}]

job = requests.post(
    "https://api.flat.io/v2/omr/jobs",
    headers=auth,
    json={"output": "musicxml", "autoStart": True, "files": files},
).json()
```

:::

From here, follow progress (step 4) as usual. If you also declared `interactiveSteps`, the one-shot
job still pauses for review.

## Exports

Once a job is `done`, download the result in any available format with
[`GET /omr/jobs/{job}/exports/{format}`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrJobExport).
The `Content-Disposition` header carries a filename derived from the resolved work title.

| `format` | File | Content type |
|:--|:--|:--|
| `musicxml` | Uncompressed MusicXML (`.xml`) | `application/vnd.recordare.musicxml+xml` |
| `mxl` | Compressed MusicXML (`.mxl`) | `application/vnd.recordare.musicxml` |
| `midi` | Standard MIDI (`.mid`) | `audio/midi` |
| `thumbnail.png` | PNG preview of the first page | `image/png` |

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.flat.io/v2/omr/jobs/$JOB/exports/musicxml" -o score.xml
```

New formats may be added over time, so request the format your client supports. `result.exports`
lists what is available for a given job.

## List and resume jobs

[`GET /omr/jobs`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/listOmrJobs) lists the
caller's jobs, newest first, with an optional `status` filter and cursor pagination via the `Link`
response header. Use it to resume an interrupted job or clean up abandoned drafts.

```bash
curl -H "Authorization: Bearer $TOKEN" "https://api.flat.io/v2/omr/jobs?status=draft"
```

## Cancel a job

[`POST /omr/jobs/{job}/cancel`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/cancelOmrJob)
cancels a job that is not being actively recognized: a `draft`, a queued job, or a job paused at an
interactive step (`awaitingInput`). Any credits charged at start are reversed.

```bash
curl -X POST "https://api.flat.io/v2/omr/jobs/$JOB/cancel" -H "Authorization: Bearer $TOKEN"
```

Only a job the worker is actively recognizing cannot be canceled; that returns `409`
(`OMR_JOB_NOT_CANCELLABLE`), so poll and retry if needed. Canceling a job that is already `done`,
`error`, or `canceled` is a harmless no-op.

## Retention and deletion

Flat does not keep your uploads forever. A job created with `output: musicxml` holds its files and
results for 30 days, then they are erased.

Read the exact window from `retentionDays` on
[`GET /omr/capabilities`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrCapabilities),
and each job's own deadline from `retention.expiryDate`. The deadline is fixed when the job is
created, so a later change to the retention window never moves it. Erasure runs as a periodic pass,
so data is removed shortly after `expiryDate` rather than exactly on it.

Jobs created with `output: library` have no `retention` object at all. Their result is a score in
your library, so it follows the library's lifecycle instead.

Collected what you need? Erase it right away with
[`DELETE /omr/jobs/{job}`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/deleteOmrJob):

```bash
curl -X DELETE "https://api.flat.io/v2/omr/jobs/$JOB" -H "Authorization: Bearer $TOKEN"
```

The job itself stays listable with the `status` it finished with, and records
`retention.expiredDate`. The call is idempotent, and returns `409` for a job that has not finished
(`OMR_JOB_IN_PROGRESS`) or one that imported into the library (`OMR_JOB_NOT_EXPIRABLE`).

The originals, recognition results, and processing logs all live under a single dedicated prefix in
our object storage, and that prefix is deleted outright at expiry. We keep **no backups or replicas**
of it. What remains is a stripped job record for accounting and history: id, dates, status, page and
file counts, file size, MIME type, and billing information. No filename, no checksum, no document
content. See the [privacy and data FAQ](/api/omr/faq/legal#what-survives-deletion).

Downloads and exports of an erased job return `409` (`OMR_JOB_EXPIRED`). Branch on the code rather
than the status: `OMR_JOB_NOT_DONE` is worth retrying, `OMR_JOB_EXPIRED` is permanent. To list by
retention state, filter on `expired`, alongside `status` if you like:

```bash
curl -H "Authorization: Bearer $TOKEN" "https://api.flat.io/v2/omr/jobs?status=done&expired=false"
```

## Errors

See the [OMR overview](/api/omr/#errors) for the shared `errorCode` list and the common HTTP statuses.
The job lifecycle adds these request errors:

| Situation | Status | Code |
|:--|:--|:--|
| Adding a file to a job that is no longer a `draft` | `400` | `OMR_JOB_NOT_DRAFT` |
| Adding a file whose type cannot be determined | `400` | `OMR_MIME_REQUIRED` |
| Submitting a step whose body and path disagree | `400` | `OMR_STEP_MISMATCH` |
| Submitting a step the job is not awaiting | `409` | `OMR_NOT_AWAITING_STEP` |
| Submitting a step for a job whose task can no longer resume (for example a concurrent cancel) | `409` | `OMR_JOB_NOT_RESUMABLE` |
| Downloading an export before the job is `done` | `409` | `OMR_JOB_NOT_DONE` |
| Canceling a job the worker is actively processing | `409` | `OMR_JOB_NOT_CANCELLABLE` |

## Related

* [OMR overview](/api/omr/) - scopes, credits, capabilities, and error codes.
* [Auto simple import](/api/omr/import) - the fewest-calls path to a Library score.
* [FAQ](/api/omr/faq/) - credits and billing, limits, recognition quality, and commercial use.
* [Instrument IDs](/api/instruments) - the catalog used to correct detected parts.
* [API Reference: OMR](https://flat.io/developers/docs/api/reference#tag/OMR).

---

---
url: /developers/docs/api/omr/faq/limits.md
description: >-
  Flat OMR API limits and performance: pages, files, and file size per job,
  parallel job concurrency, how long a conversion takes, and serving many end
  users from one account.
---

# Limits, performance, and integration

What Flat's [Optical Music Recognition API](/api/omr/) can handle, how fast it runs, and how to shape
a production integration around it.

## Limits

### What are the limits?

These are the current values. They are not contractual: read them at runtime from
[`GET /omr/capabilities`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrCapabilities)
rather than hardcoding them, so your client keeps working when they change.

| Limit | Current value | Capabilities field |
|:--|:--|:--|
| Pages per job | 50 | `maxPages` |
| Files per job | 100 | `maxFiles` |
| Size per file | 25 MiB (26,214,400 bytes) | `maxFileSize` |
| Jobs processing in parallel | 10 per account | `maxParallelJobs` |
| Accepted input types | PDF, JPEG, PNG, WebP, TIFF, GIF, AVIF, HEIC, HEIF | `acceptedMimeTypes` |

If your workload needs more than this, email <developers@flat.io> and tell
us what you are running. These limits are adjustable.

### How many jobs can I run at the same time?

**10** per account, as reported by `maxParallelJobs`. Queue beyond that in your own worker rather than
firing everything at once.

This is a **different limit** from the REST API request rate, which is 7,200 authenticated requests
per hour. See [Rate limits](/api/rate-limits) for the request headers that tell you where you stand.
Polling a job with the `wait` parameter is the cheapest way to follow progress without burning
request quota. See [Follow progress](/api/omr/jobs#step-4-follow-progress).

### Which file formats are accepted?

**PDF plus a range of image formats**, listed in the table above and reported by
`acceptedMimeTypes`. JPEG and PNG are the safe default; HEIC and HEIF matter in practice because that
is what an iPhone camera produces by default.

One caveat worth knowing: the [auto simple import](/api/omr/import) through
[`POST /scores`](https://flat.io/developers/docs/api/reference#tag/Score/operation/createScore)
handles **PDF only**. If you need to send photos or scanned images, use the
[Interactive Jobs API](/api/omr/jobs), which takes every accepted type and lets you add pages one at
a time.

Capturing on a phone? Use the platform's on-device document scanner rather than a raw camera photo,
and upload one file per page. See
[How should I capture it?](/api/omr/faq/quality#my-users-photograph-sheet-music-with-a-phone-how-should-i-capture-it)

Give each file either a `filename` with a recognizable extension or an explicit `mimeType`. If
neither is present the call returns `400` (`OMR_MIME_REQUIRED`).

## Performance

### How long does a conversion take?

A single page document typically takes **around 30 seconds**. Occasionally it can take **up to about
a minute per page**.

Multi-page documents are processed **partly in parallel**, depending on the number of pages, parts,
and instruments, so total time does not grow linearly with page count. A 10 page score is
considerably faster than 10 times a single page.

Design for this rather than guessing: the Jobs API reports a `progress` object with a `percent` and a
stable `key` you can map onto your own UI, and long-polling with `wait` returns as soon as the state
changes. See [Follow progress](/api/omr/jobs#step-4-follow-progress).

## Integration patterns

### Can my backend use one account for all my end users?

**Yes.** A single Flat account and token can process files on behalf of any number of end users. Your
users do **not** need their own Flat accounts, and they never have to connect one.

All credits are billed to the account behind the token, so this is the usual shape for a commercial
product: your backend holds one personal access token, and your users never see Flat. See
[Whose credits are spent](/api/omr/#whose-credits-are-spent) and
[Commercial use](/api/omr/faq/legal#can-i-use-omr-commercially-and-resell-the-output).

Use OAuth2 instead when you want each conversion billed to **your user's own** Flat account, for
example in an app that plugs into their existing Flat library.

### Can I cache and reuse the output instead of converting the same pages again?

Yes, and you should. The MusicXML and MIDI a job produces are **yours** to store, reuse, and serve to
as many of your own users as you like. See
[Commercial use](/api/omr/faq/legal#can-i-use-omr-commercially-and-resell-the-output).

Deduplicating uploads on your side, by hashing the file before you submit it, is the single easiest
way to cut credit spend when several users upload the same score.

### Do I have to create a Flat score?

No. Create the job with `output: "musicxml"` and the result **never enters a Flat Library**. You
download MusicXML, compressed MusicXML (`.mxl`), MIDI, or a `thumbnail.png` preview of the first
page straight from the [exports endpoint](/api/omr/jobs#exports).

This path also needs only the `omr` scope, not `scores`, and it is the one covered by the
[30 day retention window](/api/omr/jobs#retention-and-deletion), so you can delete the data as soon
as you have collected it.

Use `output: "library"` (the default) when you do want a score in the user's Flat Library, for
example so they can edit it in the Flat editor afterwards.

## Related

* [Capabilities and credits](/api/omr/#capabilities-and-credits) on the OMR overview.
* [Rate limits](/api/rate-limits) for the request-per-hour quota.
* [Credits and billing](/api/omr/faq/credits).

---

---
url: /developers/docs/api/omr/faq/quality.md
description: >-
  What Flat's OMR reads well, which languages are supported for lyric
  recognition, what to do when a conversion is inaccurate, and how to tell which
  OMR ML model version produced a result.
---

# Recognition quality and languages

What Flat's [Optical Music Recognition](/api/omr/) reads well, what it does with lyrics, and what to
do when a result is not what you expected.

## What OMR reads

### What kind of sheet music works well?

OMR works best on **clean, printed sheet music in standard notation**: engraved scores, good scans,
and sharp photos, from single instruments through grand-staff piano to full orchestral scores.
**Handwritten music and guitar tablature are not supported.** As a rule of thumb, if a page is hard
for a person to read, it is hard for Flat to read.

The help center is the source of truth for what is recognized, and it is kept current as the engine
improves:

* [Which notations are supported](https://help.flat.io/en/music-notation-software/omr/), the complete
  recognition matrix.
* [Getting the best results](https://help.flat.io/en/music-notation-software/omr/), capture and
  file-preparation tips worth passing on to your own users.

### Does score length or complexity affect quality?

**No.** The processing pipeline is the same regardless of how long a score is, and there is no score
splitting that would degrade longer pieces. If quality drops partway through a long score, that is a
notation or scan issue on those pages, not a length effect. It is worth reporting.

### How do I find out about recognition improvements?

The [OMR changelog](https://help.flat.io/en/music-notation-software/omr/changelog/) covers ML model
updates and other significant recognition changes. It does not list every bug fix.

For changes to the **API surface** itself, endpoints, fields, and behavior, see the
[REST API changelog](/api/changelog).

## Languages and lyrics

### Which languages are supported for lyrics?

The supported set is returned as `locales` (BCP 47 codes) and `localesDetails` (the same codes with
English display names, ready to drop into a language picker) by
[`GET /omr/capabilities`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrCapabilities),
which needs no authentication.

**65 languages** are currently supported:

Afrikaans (`af`), Albanian (`sq`), Arabic (`ar`), Azerbaijani (`az`), Bengali (`bn`),
Bosnian (`bs`), Bulgarian (`bg`), Chinese (Hong Kong) (`zh-HK`),
Chinese (Simplified) (`zh-Hans`), Chinese (Taiwan) (`zh-TW`), Croatian (`hr`), Czech (`cs`),
Danish (`da`), Dutch (`nl`), English (UK) (`en-GB`), English (US) (`en`), Estonian (`et`),
Filipino (`fil`), Finnish (`fi`), French (`fr`), French (Canada) (`fr-CA`), German (`de`),
Greek (`el`), Hindi (`hi`), Hungarian (`hu`), Icelandic (`is`), Indonesian (`id`), Irish (`ga`),
Italian (`it`), Japanese (`ja`), Japanese (Hiragana) (`ja-HIRA`), Kannada (`kn`), Korean (`ko`),
Kurdish (`ku`), Latin (`la`), Latvian (`lv`), Lithuanian (`lt`), Malay (`ms`), Maltese (`mt`),
Māori (`mi`), Marathi (`mr`), Nepali (`ne`), Norwegian (Bokmål) (`nb`), Occitan (`oc`),
Persian (`fa`), Polish (`pl`), Portuguese (`pt`), Portuguese (BR) (`pt-BR`), Romanian (`ro`),
Russian (`ru`), Serbian (`sr`), Slovak (`sk`), Slovenian (`sl`), Spanish (`es`), Swahili (`sw`),
Swedish (`sv`), Tamil (`ta`), Telugu (`te`), Thai (`th`), Turkish (`tr`), Ukrainian (`uk`),
Urdu (`ur`), Uzbek (`uz`), Vietnamese (`vi`), Welsh (`cy`).

**New languages are added over time**, so build your picker from `localesDetails` rather than
hardcoding a list.

### What do `locales` and `mainLanguage` actually do?

They tell the recognition pipeline which language to read **lyrics and text** in. They do not affect
the notation itself.

They are not just a hint. Flat runs **different OCR models depending on the languages you declare**,
and can run **several models over the same file** to get the best reading, then links the recognized
text back to the note positions. So `locales` genuinely changes which models see your pages, which is
why an accurate value is worth setting and why a wrong one degrades the lyrics.

* **`locales`** is set when you [create the job](/api/omr/jobs#step-1-create-a-draft-job), as an
  array of BCP 47 codes. Pass the languages the score is likely to use. Defaulting to the user's own
  locale, when it appears in `locales`, is a good starting point.
* **`mainLanguage`** is set when you [submit the `details` step](/api/omr/jobs#correcting-a-part) and
  overrides the job locale for the whole score. It is the natural place to let a user correct the
  language after seeing the detected title.

### What happens if the lyrics are in an unsupported language?

The job **succeeds and the lyrics come back wrong**, rather than failing with an error. Characters
and diacritics can be mangled, and there is no validation warning to tell you why.

So check that the language you need appears in `locales` **before** you build on it. If it is
missing, email <developers@flat.io>: languages get added on request, and
several in the list above arrived that way.

## Capturing on mobile

### My users photograph sheet music with a phone. How should I capture it?

Present the **platform's own on-device document scanner** rather than a raw camera shot.

A handheld photo does work. Flat pre-processes what you send, and a reasonably framed photo of a page
converts fine. But pre-processing can only recover so much from perspective skew, uneven lighting, a
shadow across the staff, or the desk still in frame, and **a better input always gives a better
result**. Sending a scanner-corrected page is the cheapest quality win available on mobile, and it
costs you nothing: the correction happens on the phone, before the upload.

Both scanners run **entirely on device**, are free, add no per-image cost, and give the user edge
detection, perspective correction, shading cleanup, multi-page capture, and a review pass **before**
anything is uploaded or a credit is spent. This is what the Flat and
[Opuscan](https://www.opuscan.com/omr/) mobile apps use, and neither app implements its own camera.

| Platform | API | Available since | Dependency |
|:--|:--|:--|:--|
| iOS | [`VNDocumentCameraViewController`](https://developer.apple.com/documentation/visionkit/vndocumentcameraviewcontroller) (VisionKit) | iOS 13 | None, it is a system framework |
| Android | [ML Kit Document Scanner](https://developers.google.com/ml-kit/vision/doc-scanner/android) (`GmsDocumentScanning`) | API 21 | `com.google.android.gms:play-services-mlkit-document-scanner`, delivered through Google Play services |

Minimal examples, in both cases handing you the captured pages in the order the user confirmed:

::: code-group

```swift [iOS]
import VisionKit

// Presenting the scanner.
let scanner = VNDocumentCameraViewController()
scanner.delegate = self
present(scanner, animated: true)

// VNDocumentCameraViewControllerDelegate.
func documentCameraViewController(
    _ controller: VNDocumentCameraViewController,
    didFinishWith scan: VNDocumentCameraScan
) {
    controller.dismiss(animated: true)
    // VisionKit has no page cap of its own: check the count against maxPages yourself.
    // Pages come back as UIImage, so encode each one before uploading.
    let pages = (0..<scan.pageCount).compactMap {
        scan.imageOfPage(at: $0).jpegData(compressionQuality: 0.8)
    }
    // Upload one page per call, in this order.
}
```

```kotlin [Android]
val options = GmsDocumentScannerOptions.Builder()
    .setScannerMode(SCANNER_MODE_BASE)
    .setPageLimit(maxPages)              // from GET /omr/capabilities
    .setResultFormats(RESULT_FORMAT_JPEG)
    .build()

GmsDocumentScanning.getClient(options)
    .getStartScanIntent(activity)
    .addOnSuccessListener { /* launch it */ }
    .addOnFailureListener { /* fall back to the file picker */ }

// In the activity result. RESULT_FORMAT_JPEG means the pages are already
// encoded JPEGs on disk, so there is nothing to convert.
val pages = GmsDocumentScanningResult.fromActivityResultIntent(data)?.pages
val uris = pages?.map { it.imageUri }
// Upload one page per call, in this order.
```

:::

Both are documented by the platform vendors:

* **iOS**: [`VNDocumentCameraViewController`](https://developer.apple.com/documentation/visionkit/vndocumentcameraviewcontroller),
  [`VNDocumentCameraViewControllerDelegate`](https://developer.apple.com/documentation/visionkit/vndocumentcameraviewcontrollerdelegate),
  and [`VNDocumentCameraScan`](https://developer.apple.com/documentation/visionkit/vndocumentcamerascan).
* **Android**: the [document scanner guide](https://developers.google.com/ml-kit/vision/doc-scanner/android)
  and the [`GmsDocumentScannerOptions`](https://developers.google.com/android/reference/com/google/mlkit/vision/documentscanner/GmsDocumentScannerOptions)
  reference.

Four things worth knowing before you wire this up:

* **Drive the page limit from the API.** Read `maxPages` from
  [`GET /omr/capabilities`](/api/omr/faq/limits#what-are-the-limits) rather than hardcoding a number,
  so a user cannot capture more pages than a job will accept, and so the value tracks the limit when
  it changes. ML Kit enforces it during capture through `setPageLimit`; VisionKit has no equivalent,
  so check `scan.pageCount` once the user is done and send them back if there are too many.
* **Keep a fallback on Android.** ML Kit's scanner is delivered through Google Play services, so it
  is unavailable on devices without them. That surfaces as a failure on `getStartScanIntent`, not as
  a missing class, so handle it and fall back to the file picker.
* **The camera permission works differently on each platform.** iOS needs an
  `NSCameraUsageDescription` string in your `Info.plist`. On Android the scanner runs inside Play
  services and owns the camera prompt itself, so your app may need no `CAMERA` permission at all.
* **`VNDocumentCameraViewController` does not run on the iOS simulator.** Fall back to a photo
  picker there so the flow stays testable during development.

There is no browser equivalent, so a web upload path still needs a plain file picker.

### Should I upload one file per page?

The thing to know first: **page order is upload order.**
[`POST /omr/jobs/{job}/files`](/api/omr/jobs#step-2-add-files) has no reorder parameter, so the
sequence of your calls *is* the page sequence of the score.

That makes the scanner's own review UI, where the user reorders, rotates, and deletes pages, the step
that decides page order. Upload in the order the user confirmed there and you need no reorder screen
of your own. Flat's Android app ships none for the camera path for exactly this reason.

So use the **[Interactive Jobs API](/api/omr/jobs#step-2-add-files)** for camera capture, and send
one file per page. It accepts images directly, so the scanner's pages go straight through with no
merging step at all: encode each one as JPEG or PNG and upload it. It is also the flow that gives you
the review step, live progress, and MusicXML without a Library score. See
[Which flow should I use?](/api/omr/faq/#which-flow-should-i-use-the-jobs-api-or-the-simple-import)

If your app also lets people pick an existing photo instead of scanning, note that
[HEIC and HEIF are accepted](/api/omr/faq/limits#which-file-formats-are-accepted) alongside JPEG and
PNG, so an iPhone photo can be uploaded as-is without transcoding.

### How should I size and compress captured pages?

**Start by uploading the scanner's output unchanged.** It is already cropped and corrected, and it is
normally well inside the 25 MiB per-file limit (`maxFileSize`). Flat's Android app uploads ML Kit's
JPEGs byte for byte.

Resize only if you need to, and do not be aggressive about it. OMR reads fine detail: ledger lines,
articulations, accidentals, and lyric text. Where Flat's apps do resize, they **cap the width at
2000 px and re-encode at JPEG quality 0.75 to 0.85**, which lands a portrait page around
0.5 to 1 MB. Treat that as a reasonable starting point rather than a Flat requirement.

The counterweight is the same rule that governs the rest of OMR: if a page is hard for a person to
read, it is hard for Flat to read. Stop compressing well before the staff lines start to break up.

One scanner setting belongs here too. Flat uses ML Kit's `SCANNER_MODE_BASE`, **not**
`SCANNER_MODE_BASE_WITH_FILTER`. The filter modes apply their own image enhancement, which is tuned
for text documents rather than for notation.

## When a result is wrong

### A conversion came back inaccurate. What do I do?

Email <developers@flat.io> with the **job ID** (the `id` from
`POST /omr/jobs`, or the task `id` for the auto simple import). That is the fastest thing to give us:
it lets us pull up the exact run, its inputs, and its internal quality report. Attaching the
**source file** and a description of what is wrong, ideally with measure numbers, helps too.

Concrete examples are far more useful than a general report, and they are how the engine gets
better.

What happens next:

1. We investigate whether the example is an **isolated case** or a **recurring limitation** in the
   recognition or score-assembly pipeline.
2. Recurring limitations are fixed in the product.
3. Once an improvement ships, we can **reprocess affected conversions**.

**There is no automatic credit refund** for a conversion that completes but is inaccurate. Credits
are reverted for jobs that *fail*, see
[Do failed jobs consume credits?](/api/omr/faq/credits#do-failed-cancelled-or-retried-jobs-consume-credits)
If you are running a large batch, tell us before you start rather than after.

### How do I know which OMR ML model version produced a result?

The version of the **OMR machine-learning model** that read your pages is **embedded in the MusicXML
output**. Record it alongside the result and you can tell later which of your conversions predate a
given improvement, which is exactly what you need when deciding what to reprocess.

### Is there a confidence score for a whole job?

Not for the job as a whole. What you do get is per-part confidence during the optional
[`details` review step](/api/omr/jobs#step-5-review-detected-instruments): each detected instrument
carries a `resolvedConfidence` of `high`, `medium`, or `low`, which is what the Flat and Opuscan apps
use to decide what to put in front of a user for confirmation. Rendering that step is the most effective
quality control you can add to an integration.

## Related

* [What OMR can read](/api/omr/#what-omr-can-read) on the OMR overview.
* [Add files](/api/omr/jobs#step-2-add-files) in the Jobs API, where upload order sets page order.
* [Review detected instruments](/api/omr/jobs#step-5-review-detected-instruments) in the Jobs API.
* [OMR changelog](https://help.flat.io/en/music-notation-software/omr/changelog/).

---

---
url: /developers/docs/api/omr.md
description: >-
  Turn PDFs and photos of sheet music into editable Flat scores through the API.
  Overview of the two OMR import flows, scopes, credits, capabilities, and
  errors.
---

# Optical Music Recognition (OMR)

Flat's **Optical Music Recognition** turns a PDF or photo of sheet music into music you can use: a
fully editable score in the Flat Library, or a MusicXML or MIDI file for your own tools. You send the
file, Flat recognizes the staves, notes, and symbols, and you get back the result to play, edit, and
export.

> Looking for the end-user OMR feature instead? See the
> [OMR help center article](https://help.flat.io/en/music-notation-software/omr/) and its
> [changelog](https://help.flat.io/en/music-notation-software/omr/changelog/). If you or your users
> just want to turn files into scores without writing code, and without a Flat account, try
> [Opuscan](https://www.opuscan.com/omr/), our dedicated scan-to-score product.

![Optical Music Recognition converts a PDF or photo of sheet music into an editable Flat score, or a downloadable MusicXML or MIDI file.](/img/omr/hero.png)

## Powered by Tutteo's own AI model

Every PDF and photo is processed by **[Tutteo](https://tutteo.com)'s own in-house deep-learning
model**, the Optical Music Recognition engine built by our company, [Tutteo](https://tutteo.com),
behind [Flat](https://flat.io) and [Opuscan](https://www.opuscan.com/omr/), not a third-party engine. It does not just spot symbols, it reads them in musical context, the way a trained
musician would, so the score it rebuilds actually makes sense.

* **Reads in context.** Rhythm, pitch, and layout are read together, not symbol by symbol.
* **Understands structure.** Separates instruments and voices, and attaches lyrics, chords, and text
  to the right notes.
* **Improves with every release.** Built end to end in-house, so recognition gets measurably better
  over time.

## Two ways to import

There are two ways to run OMR through the API:

* The **[Interactive Jobs API](/api/omr/jobs)** gives the **best results**. You can set the locales,
  review and correct the detected instruments and title, follow live progress, and export MusicXML
  without adding it to your Flat Library. It also supports adding pages one by one (ideal for mobile
  capture). This
  is the recommended path for a polished integration.
* The **[Auto simple import](/api/omr/import)** is the **fewest calls** and shares one code path with
  your MusicXML and MIDI imports: send a file to `POST /scores`, poll the task, get a score. Reach for
  it when you just want a Library score and do not need the review step or progress.

| | Interactive Jobs API | Auto simple import |
|:--|:--|:--|
| **Endpoint** | [`/omr/jobs/*`](https://flat.io/developers/docs/api/reference#tag/OMR) | [`POST /scores`](https://flat.io/developers/docs/api/reference#tag/Score/operation/createScore) (+ [tasks](https://flat.io/developers/docs/api/reference#tag/Task/operation/getTask)) |
| **Best for** | Controlling instruments and locales, a progress UI, multi-image or mobile capture | A single PDF, or unifying MusicXML / MIDI / PDF import behind one call |
| **Result** | A Library score, or a MusicXML file you download directly (without importing it into the Library) | A score in the Flat Library |
| **Review step** | Optional `details` step (correct title, language, instruments) | No |
| **Live progress** | Long-polling with a localized progress key | Task `percent` |
| **Calls to ship** | 3 or more | 2 |

## Authentication and scopes

Every OMR request is authenticated like the rest of the API (see [Authentication](/api/authentication)).
A [Personal Access Token](/api/authentication#personal-access-tokens) is the quickest way to start.

For OAuth2 apps, request these scopes:

| Scope | When you need it |
|:--|:--|
| `omr` | Every OMR request (both flows). |
| `scores` | Additionally, whenever OMR **creates a score** in the Library: the Auto simple import, and the Interactive Jobs API with `output: library` (the default). Not needed for `output: musicxml`. |

In the Interactive Jobs API, a request that creates a Library score without the `scores` scope is
rejected with `403` (`OMR_SCORES_SCOPE_REQUIRED`). The Auto simple import enforces the `scores` scope
through the standard endpoint scope check, and separately returns `403` (`OMR_SCOPE_REQUIRED`) when the
`omr` scope is missing. Personal access tokens and web sessions carry the account's own permissions and
are not subject to these OAuth scope checks.

## Capabilities and credits

OMR runs on **credits** tied to a Flat account, charged **per page** at job start. Call
[`GET /omr/capabilities`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrCapabilities)
to feature-detect at runtime instead of hardcoding limits: it returns the supported steps, export
formats and outputs, the file, page, and parallel-job limits, `costPerPage`, and the account's
`remainingCredits`. See the
[`getOmrCapabilities`](https://flat.io/developers/docs/api/reference#tag/OMR/operation/getOmrCapabilities)
reference for the full response.

The response also carries `retentionDays` (30 by default), how long a job's files and results are
kept, and `localesDetails`, the recognition languages with their English names, ready for a language
picker. See [Retention and deletion](/api/omr/jobs#retention-and-deletion).

No authentication is needed to call it, so you can feature-detect before a user connects their
account. Called without one, the limits returned are those of the free plan and `remainingCredits`
is omitted, since there is no account to report a balance for.

**1 credit is 1 page** (`costPerPage` is `1`), drawn from the **same pool as the Flat web,
desktop, and mobile apps**. There is no separate API meter.

Read `remainingCredits` before you start a job so a user never discovers the problem as a failure:

::: code-group

```bash [curl]
curl -H "Authorization: Bearer $TOKEN" "https://api.flat.io/v2/omr/capabilities"
```

```js [JavaScript]
const caps = await fetch('https://api.flat.io/v2/omr/capabilities', { headers: auth }).then((r) => r.json());

if (pageCount * caps.costPerPage > caps.remainingCredits) {
  // Send the user to https://flat.io/settings/ai-credits before starting the job.
}
```

```python [Python]
caps = requests.get("https://api.flat.io/v2/omr/capabilities", headers=auth).json()

if page_count * caps["costPerPage"] > caps["remainingCredits"]:
    # Send the user to https://flat.io/settings/ai-credits before starting the job.
    ...
```

:::

### Current limits

These are today's values, given so you can size an integration before writing code. They are not
contractual, and an unauthenticated call reports the free plan's limits, so read them from
`GET /omr/capabilities` with your own token rather than hardcoding them.

| Limit | Current value | Capabilities field |
|:--|:--|:--|
| Pages per job | 50 | `maxPages` |
| Files per job | 100 | `maxFiles` |
| Size per file | 25 MiB | `maxFileSize` |
| Jobs processing in parallel | 10 per account | `maxParallelJobs` |
| Accepted input types | PDF, JPEG, PNG, WebP, TIFF, GIF, AVIF, HEIC, HEIF | `acceptedMimeTypes` |

These limits are adjustable: [contact us](mailto:developers@flat.io) if your workload needs more.
They are separate from the API [rate limits](/api/rate-limits), which cap requests per hour.

### Processing time

A single-page document typically takes **around 30 seconds**, and occasionally up to about a minute
per page. Multi-page documents are processed partly in parallel depending on the pages, parts, and
instruments involved, so total time does not grow linearly with page count.

The [Interactive Jobs API](/api/omr/jobs#step-4-follow-progress) reports live `progress` and supports
long-polling, so you can show real progress instead of guessing.

### Whose credits are spent

Credits belong to the **Flat account that owns the token** you authenticate with:

* With a [Personal Access Token](/api/authentication#personal-access-tokens), that is your own account.
* With OAuth2, that is the account of the user who authorized your app.

For each job, credits are drawn in this order:

1. The page allowance included in the account's **Flat or Flat for Education subscription**.
2. **Credit packs** bought on the account. Packs do not expire while the account is active.

A single account can process files **on behalf of any number of end users**, who do not need Flat
accounts of their own. That is the usual shape for a commercial integration: your backend holds one
token, your users never see Flat. Use OAuth2 instead when each conversion should be billed to your
user's own Flat account.

::: warning Opuscan credits are separate
[Opuscan](https://www.opuscan.com/omr/) is a separate consumer product sold through the app stores.
Credits bought inside Opuscan are tied to that store account and **cannot be used with this API**,
and credits on your Flat account do not appear in Opuscan. See the
[FAQ](/api/omr/faq/credits#do-credits-bought-in-the-opuscan-apps-work-with-the-api).
:::

### Buying credits

Credit packs are purchased from
[your account's AI credits page](https://flat.io/settings/ai-credits?ref=dev-docs-omr). Packs run up
to 3,000 credits, and the price per page improves at every size, with the best rates on the largest
packs. Usage-based (pay as you
go) billing is planned for a future release.

Packs are **one-off purchases**: not a subscription, no auto-renewal, and no expiry while the account
is active. The 1,000 and 3,000 packs sit behind the **"Need 1000+ credits?"** link on that page
rather than in the default grid.

Credits are **only ultimately consumed by successful conversions**. They are charged when a job
starts, then reverted if the job ends in `error` or is
[canceled](/api/omr/jobs#cancel-a-job) before the worker finishes.

When the account is out of credits, over quota, or the plan does not include OMR, requests that
consume credits return **`402`**. Show `remainingCredits` and `costPerPage` to warn users before you
start a job, and point them to
[flat.io/settings/ai-credits](https://flat.io/settings/ai-credits?ref=dev-docs-omr) to top up.

Need more than the largest pack? [Contact us](mailto:developers@flat.io) to discuss custom pricing
and a contract for larger volumes.

## What OMR can read

OMR works best on clean, printed sheet music: engraved scores, good scans, and sharp photos, in
standard notation (single instruments, grand-staff, and multi-instrument scores). Handwritten music
and tablature are not supported. As a rule of thumb, if a page is hard for a person to read, it is
hard for Flat to read.

For the full, up-to-date details, see the help center:

* [Which notations are supported](https://help.flat.io/en/music-notation-software/omr/) (the complete recognition matrix).
* [Getting the best results](https://help.flat.io/en/music-notation-software/omr/) (capture and file-preparation tips).
* [OMR changelog](https://help.flat.io/en/music-notation-software/omr/changelog/) (recognition improvements over time).

For lyric language support, what to do about an inaccurate conversion, and how to tell which model
version produced a result, see the
[recognition quality FAQ](/api/omr/faq/quality).

## Commercial use, privacy, and terms

You can use OMR to process sheet music uploaded by customers who hold the necessary rights, and
deliver the resulting MusicXML and MIDI to them outside of Flat. No attribution is required, and
there is no requirement to keep the result in a Flat library. You and your users remain responsible
for having the appropriate rights to the source material.

**Files you submit, and the outputs generated from them, are not used to train or improve our
models.** Our recognition models are trained on synthetic data we generate ourselves and on
public-domain sheet music we source independently.

The API is covered by Flat's
[Terms of Service and Privacy Policy](https://help.flat.io/en/policies/). You can rely on our
published [Data Processing Addendum](https://help.flat.io/en/education/policies/data-processing-addendum/),
and our infrastructure providers, subprocessors, and hosting regions are documented in the
[data and infrastructure article](https://help.flat.io/en/general/data-infrastructure/#infrastructure-providers).

See the [commercial use, privacy, and data FAQ](/api/omr/faq/legal) for the detail, including exactly
what remains after a job is deleted.

## Errors

A failed **job** reports a stable `errorCode` plus a localized `errorMessage`. The Auto simple import
surfaces the same failures through the task's error message. `errorCode` is an open string: new codes
may be added, so branch on the ones you handle and keep a generic fallback.

| `errorCode` | Meaning |
|:--|:--|
| `NO_MUSIC_DETECTED` | No musical content found (poor scan, rotated page, or tablature). |
| `CORRUPTED_FILE` | The input file is corrupted and could not be read. |
| `UNSUPPORTED_FORMAT` | The file format or notation is not supported yet. |
| `UNSUPPORTED_TABLATURE` | The file is guitar tablature, not supported yet. |
| `ENCRYPTED_PDF` | The PDF is password-protected. |
| `TOO_LARGE` | The document is too large or has an unusual shape to process. |
| `ENGINE_TIMEOUT` | Recognition took longer than expected and was stopped. |
| `GENERIC` | Unspecified failure. |

HTTP statuses you should handle:

| Status | When it happens |
|:--|:--|
| `400` | Invalid request, for example adding a file to a job that is no longer a draft (`OMR_JOB_NOT_DRAFT`), or a file whose type cannot be determined (`OMR_MIME_REQUIRED`). |
| `402` | Out of credits, over quota, or OMR not included in the plan. See [Buying credits](#buying-credits) and [Why did I get a 402?](/api/omr/faq/credits#why-did-i-get-a-402). |
| `403` | Missing a required scope: `OMR_SCOPE_REQUIRED` (the `omr` scope), or `OMR_SCORES_SCOPE_REQUIRED` (the `scores` scope for Library output in the Jobs API). Also returned when acting on a job the account does not own. |
| `404` | Job, task, or export not found (or the requested export format is not available). |
| `409` | State conflict, for example submitting a step the job is not awaiting, or canceling a job the worker is actively processing. Also `OMR_JOB_EXPIRED` when the job's data has been erased, `OMR_JOB_IN_PROGRESS` when deleting a job that has not finished, and `OMR_JOB_NOT_EXPIRABLE` when deleting a job whose result went to the Library. |

See the [Errors](/api/errors) page for the general error response format.

## Next steps

* [Auto simple import](/api/omr/import) - the quickest path to a score.
* [Interactive Jobs API](/api/omr/jobs) - full control, progress, and the review step.
* [FAQ](/api/omr/faq/) - credits and billing, limits, recognition quality, and commercial use.
* [Instrument IDs](/api/instruments) - the catalog used to correct detected parts.
* [API Reference: OMR](https://flat.io/developers/docs/api/reference#tag/OMR).

---

---
url: /developers/docs/embed/api/parts.md
description: 'Manage individual parts, instruments, and their audio settings'
---

# Parts & Instruments

Manage individual parts, instruments, and their audio settings

## Methods

### getPartVolume() {#getpartvolume}

Get the volume of a specific part

Retrieves the current volume level for a specific instrument part in the score.

```typescript
getPartVolume(parameters: { partUuid: string; }): Promise<number>
```

**Parameters:**

* `parameters.partUuid` - `string`

**Returns:** `Promise<number>`

**Throws:**

* `Error` - If the part UUID is invalid or volume cannot be retrieved

**Example:**

```typescript
const embed = new Embed('container', config);
const partVolume = await embed.getPartVolume({ partUuid: '00000000-0000-0000-0000-000000000001' });
console.log(partVolume);
```

**See also:**

* [`setPartVolume()`](#setpartvolume) - Set the volume for a part
* [`getParts()`](#getparts) - Get all parts information

***

### setPartVolume() {#setpartvolume}

Set the volume of a specific part

Sets the volume level for a specific instrument part in the score. Part volumes are independent but affected by the master volume.

```typescript
setPartVolume(parameters: { partUuid: string; volume: number; }): Promise<void>
```

**Parameters:**

* `parameters.partUuid` - `string`
* `parameters.volume` - `number`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the part UUID or volume value is invalid

**Examples:**

```typescript
// Set violin part to 75% volume
const parts = await embed.getParts();
await embed.setPartVolume({
  partUuid: parts[0].uuid,
  volume: 75
});
```

**See also:**

* [`getPartVolume()`](#getpartvolume) - Get the volume for a part
* [`mutePart()`](#mutepart) - Mute a part

***

### mutePart() {#mutepart}

Mute a specific part

Mutes the audio output for a specific instrument part. The part's volume setting is preserved and can be restored using `unmutePart()`.

```typescript
mutePart(parameters: { partUuid: string; }): Promise<void>
```

**Parameters:**

* `parameters.partUuid` - `string`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the part UUID is invalid or muting fails

**Example:**

```typescript
const embed = new Embed('container', config);
await embed.mutePart({ partUuid: '00000000-0000-0000-0000-000000000001' });
```

**See also:**

* [`unmutePart()`](#unmutepart) - Unmute a part
* [`setPartVolume()`](#setpartvolume) - Set part volume to 0 (alternative)

***

### unmutePart() {#unmutepart}

Unmute a specific part

Restores the audio output for a previously muted part. The part returns to its previous volume level before it was muted.

```typescript
unmutePart(parameters: { partUuid: string; }): Promise<void>
```

**Parameters:**

* `parameters.partUuid` - `string`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the part UUID is invalid or unmuting fails

**Example:**

```typescript
const embed = new Embed('container', config);
await embed.unmutePart({ partUuid: '00000000-0000-0000-0000-000000000001' });
```

**See also:**

* [`mutePart()`](#mutepart) - Mute a part

***

### setPartSoloMode() {#setpartsolomode}

Enable solo mode for a part

Enables solo mode for a specific part, which mutes all other parts while keeping the selected part audible. Multiple parts can be in solo mode simultaneously.

```typescript
setPartSoloMode(parameters: { partUuid: string; }): Promise<void>
```

**Parameters:**

* `parameters.partUuid` - `string`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the part UUID is invalid or solo mode cannot be set

**Examples:**

```typescript
// Solo the violin part
const parts = await embed.getParts();
const violinPart = parts.find(p => p.instrument === 'violin');
await embed.setPartSoloMode({ partUuid: violinPart.uuid });
```

**See also:**

* [`unsetPartSoloMode()`](#unsetpartsolomode) - Disable solo mode
* [`getPartSoloMode()`](#getpartsolomode) - Check solo mode status

***

### unsetPartSoloMode() {#unsetpartsolomode}

Disable solo mode for a part

Disables solo mode for a specific part. If this was the only part in solo mode, all parts return to their normal volume/mute states. If other parts remain in solo mode, this part will be muted.

```typescript
unsetPartSoloMode(parameters: { partUuid: string; }): Promise<void>
```

**Parameters:**

* `parameters.partUuid` - `string`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the part UUID is invalid or solo mode cannot be unset

**Example:**

```typescript
const embed = new Embed('container', config);
await embed.unsetPartSoloMode({ partUuid: '00000000-0000-0000-0000-000000000001' });
```

**See also:**

* [`setPartSoloMode()`](#setpartsolomode) - Enable solo mode
* [`getPartSoloMode()`](#getpartsolomode) - Check solo mode status

***

### getPartSoloMode() {#getpartsolomode}

Get the solo mode status of a part

Checks whether a specific part is currently in solo mode.

```typescript
getPartSoloMode(parameters: { partUuid: string; }): Promise<boolean>
```

**Parameters:**

* `parameters.partUuid` - `string`

**Returns:** `Promise<boolean>`

**Throws:**

* `Error` - If the part UUID is invalid

**Example:**

```typescript
const embed = new Embed('container', config);
const partSoloMode = await embed.getPartSoloMode({ partUuid: '00000000-0000-0000-0000-000000000001' });
console.log(partSoloMode);
```

**See also:**

* [`setPartSoloMode()`](#setpartsolomode) - Enable solo mode
* [`unsetPartSoloMode()`](#unsetpartsolomode) - Disable solo mode

***

### getPartReverb() {#getpartreverb}

Get the reverb level of a part

Retrieves the current reverb (reverberation) effect level for a specific instrument part. Reverb adds spatial depth and ambience to the sound.

```typescript
getPartReverb(parameters: { partUuid: string; }): Promise<number>
```

**Parameters:**

* `parameters.partUuid` - `string`

**Returns:** `Promise<number>`

**Throws:**

* `Error` - If the part UUID is invalid or reverb cannot be retrieved

**Example:**

```typescript
const embed = new Embed('container', config);
const partReverb = await embed.getPartReverb({ partUuid: '00000000-0000-0000-0000-000000000001' });
console.log(partReverb);
```

**See also:**

* [`setPartReverb()`](#setpartreverb) - Set the reverb level

***

### setPartReverb() {#setpartreverb}

Set the reverb level of a part

Sets the reverb (reverberation) effect level for a specific instrument part. Higher values create more spacious, ambient sound.

```typescript
setPartReverb(parameters: { partUuid: string; reverberation: number; }): Promise<void>
```

**Parameters:**

* `parameters.partUuid` - `string`
* `parameters.reverberation` - `number`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the part UUID or reverb value is invalid

**Examples:**

```typescript
// Add subtle reverb to piano
await embed.setPartReverb({
  partUuid: pianoPart.uuid,
  reverberation: 30
});
```

**See also:**

* [`getPartReverb()`](#getpartreverb) - Get the current reverb level

***

### getParts() {#getparts}

Get information about all parts

Retrieves detailed information about all instrument parts in the score, including their names, instruments, and unique identifiers.

```typescript
getParts(): Promise<PartConfiguration[]>
```

**Returns:** `Promise<PartConfiguration[]>`

**Throws:**

* `Error` - If no score is loaded or parts cannot be retrieved

**Examples:**

```typescript
// Get all parts
const parts = await embed.getParts();
parts.forEach(part => {
  console.log(`${part.name}: ${part.uuid}`);
});
```

**See also:**

* [`getDisplayedParts()`](#getdisplayedparts) - Get currently visible parts
* [`setDisplayedParts()`](#setdisplayedparts) - Choose which parts to display

***

### getDisplayedParts() {#getdisplayedparts}

Get the currently displayed parts

Retrieves information about which parts are currently visible in the score. Some parts may be hidden for focused practice or simplified viewing.

```typescript
getDisplayedParts(): Promise<PartConfiguration[]>
```

**Returns:** `Promise<PartConfiguration[]>`

**Throws:**

* `Error` - If displayed parts cannot be retrieved

**Example:**

```typescript
const embed = new Embed('container', config);
const displayedParts = await embed.getDisplayedParts();
console.log(displayedParts);
```

**See also:**

* [`getParts()`](#getparts) - Get all parts in the score
* [`setDisplayedParts()`](#setdisplayedparts) - Change which parts are visible

***

### setDisplayedParts() {#setdisplayedparts}

Set which parts to display

Controls which instrument parts are visible in the score. Parts can be identified by their UUID, index, name, or abbreviation. Hidden parts are not displayed but still play during playback unless muted.

```typescript
setDisplayedParts(parts: string[]): Promise<void>
```

**Parameters:**

* `parts` - `string[]`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If part identifiers are invalid

**Examples:**

```typescript
// Show only violin and piano parts by UUID
const parts = await embed.getParts();
const violin = parts.find(p => p.instrument === 'violin');
const piano = parts.find(p => p.instrument === 'piano');
await embed.setDisplayedParts([violin.uuid, piano.uuid]);
```

```typescript
// Show parts by index
await embed.setDisplayedParts(['0', '2', '3']);
```

**See also:**

* [`getParts()`](#getparts) - Get all available parts
* [`getDisplayedParts()`](#getdisplayedparts) - Check which parts are visible

***

---

---
url: /developers/docs/embed/api/playback.md
description: 'Control playback, volume, speed, and metronome settings'
---

# Playback Control

Control playback, volume, speed, and metronome settings

## Methods

### play() {#play}

Start playback

Begins playing the score from the current cursor position. If playback was previously paused, it resumes from the pause position. If stopped, it starts from the beginning or the current cursor position.

```typescript
play(): Promise<void>
```

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If no score is loaded or playback cannot start

**Examples:**

```typescript
// Start playback
await embed.play();
```

**See also:**

* [`pause()`](#pause) - Pause playback
* [`stop()`](#stop) - Stop playback

***

### pause() {#pause}

Pause playback

Pauses the score playback at the current position. The playback position is maintained, allowing you to resume from the same point using `play()`.

```typescript
pause(): Promise<void>
```

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If no score is loaded or playback cannot be paused

**Examples:**

```typescript
// Pause playback
await embed.pause();
```

**See also:**

* [`play()`](#play) - Start or resume playback
* [`stop()`](#stop) - Stop and reset playback

***

### stop() {#stop}

Stop playback

Stops the score playback and resets the playback position to the beginning of the score. Unlike `pause()`, the playback position is not maintained.

```typescript
stop(): Promise<void>
```

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If no score is loaded or playback cannot be stopped

**Examples:**

```typescript
// Stop playback
await embed.stop();
```

**See also:**

* [`play()`](#play) - Start playback
* [`pause()`](#pause) - Pause playback

***

### mute() {#mute}

Mute playback

Mutes all audio output from the score playback. The playback continues but without sound. This is equivalent to setting the master volume to 0 but preserves the previous volume setting.

```typescript
mute(): Promise<void>
```

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If muting fails

**Examples:**

```typescript
// Mute audio
await embed.mute();
```

**Note:** There is no unmute method; use setMasterVolume to restore audio

**See also:**

* [`setMasterVolume()`](#setmastervolume) - Set master volume level

***

### getMasterVolume() {#getmastervolume}

Get the current master volume

Retrieves the current master volume level for score playback.

```typescript
getMasterVolume(): Promise<number>
```

**Returns:** `Promise<number>`

**Throws:**

* `Error` - If the volume cannot be retrieved

**Example:**

```typescript
const embed = new Embed('container', config);
const masterVolume = await embed.getMasterVolume();
console.log(masterVolume);
```

**See also:**

* [`setMasterVolume()`](#setmastervolume) - Set the master volume

***

### setMasterVolume() {#setmastervolume}

Set the master volume

Sets the master volume level for score playback. This affects all parts proportionally based on their individual volume settings.

```typescript
setMasterVolume(parameters: { volume: number; }): Promise<void>
```

**Parameters:**

* `parameters.volume` - `number`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the volume value is invalid or cannot be set

**Examples:**

```typescript
// Set volume to 50%
await embed.setMasterVolume({ volume: 50 });
```

```typescript
// Mute audio
await embed.setMasterVolume({ volume: 0 });
```

**See also:**

* [`getMasterVolume()`](#getmastervolume) - Get the current master volume

***

### getMetronomeMode() {#getmetronomemode}

Get the metronome mode

Retrieves the current metronome setting, which controls when the metronome clicks are played during playback.

```typescript
getMetronomeMode(): Promise<MetronomeMode>
```

**Returns:** `Promise<MetronomeMode>`

**MetronomeMode**

Possible values: `0`, `1`, `2`

**Throws:**

* `Error` - If metronome mode cannot be retrieved

**Example:**

```typescript
const embed = new Embed('container', config);
const metronomeMode = await embed.getMetronomeMode();
console.log(metronomeMode);
```

**See also:**

* [`setMetronomeMode()`](#setmetronomemode) - Change metronome mode

***

### setMetronomeMode() {#setmetronomemode}

Set the metronome mode

Controls when metronome clicks are played during score playback.

```typescript
setMetronomeMode(mode: MetronomeMode): Promise<void>
```

**Parameters:**

* `mode` - `MetronomeMode`

**MetronomeMode**

Possible values: `0`, `1`, `2`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If the mode value is invalid

**Examples:**

```typescript
// Enable continuous metronome
await embed.setMetronomeMode(1);
```

```typescript
// Use count-in only
await embed.setMetronomeMode(0);
```

**See also:**

* [`getMetronomeMode()`](#getmetronomemode) - Get current mode

***

### getPlaybackSpeed() {#getplaybackspeed}

Get the playback speed

Retrieves the current playback speed multiplier. Normal speed is 1.0.

```typescript
getPlaybackSpeed(): Promise<number>
```

**Returns:** `Promise<number>`

**Throws:**

* `Error` - If speed cannot be retrieved

**Example:**

```typescript
const embed = new Embed('container', config);
const playbackSpeed = await embed.getPlaybackSpeed();
console.log(playbackSpeed);
```

**See also:**

* [`setPlaybackSpeed()`](#setplaybackspeed) - Change playback speed

***

### setPlaybackSpeed() {#setplaybackspeed}

Set the playback speed

Adjusts the playback speed without affecting pitch. Useful for practice at slower or faster tempos.

```typescript
setPlaybackSpeed(speed: number): Promise<void>
```

**Parameters:**

* `speed` - `number`

**Returns:** `Promise<void>`

**Throws:**

* `Error` - If speed is outside valid range

**Examples:**

```typescript
// Slow down for practice
await embed.setPlaybackSpeed(0.5);
```

```typescript
// Return to normal speed
await embed.setPlaybackSpeed(1.0);
```

**See also:**

* [`getPlaybackSpeed()`](#getplaybackspeed) - Get current speed

***

---

---
url: /developers/docs/embed/api/data.md
description: 'Access and query score structure, measures, notes, and metadata'
---

# Score Data & Structure

Access and query score structure, measures, notes, and metadata

## Methods

### getNbMeasures() {#getnbmeasures}

Get the number of measures in the score

Retrieves the total count of measures (bars) in the currently loaded score.

```typescript
getNbMeasures(): Promise<number>
```

**Returns:** `Promise<number>`

**Throws:**

* `Error` - If no score is loaded

**Example:**

```typescript
const embed = new Embed('container', config);
const nbMeasures = await embed.getNbMeasures();
console.log(nbMeasures);
```

**See also:**

* [`getMeasuresUuids()`](#getmeasuresuuids) - Get measure identifiers
* [`getMeasureDetails()`](#getmeasuredetails) - Get detailed measure information

***

### getMeasuresUuids() {#getmeasuresuuids}

Get the measure UUIDs of the score

Retrieves the unique identifiers for all measures in the score. These UUIDs can be used to reference specific measures in other API calls.

```typescript
getMeasuresUuids(): Promise<string[]>
```

**Returns:** `Promise<string[]>`

**Throws:**

* `Error` - If no score is loaded

**Example:**

```typescript
const embed = new Embed('container', config);
const measuresUuids = await embed.getMeasuresUuids();
console.log(measuresUuids);
```

**See also:**

* [`getNbMeasures()`](#getnbmeasures) - Get the total number of measures
* [`getMeasureDetails()`](#getmeasuredetails) - Get details for a specific measure

***

### getMeasureDetails() {#getmeasuredetails}

Get detailed measure information

Retrieves comprehensive information about the current measure at the cursor position, including time signature, key signature, tempo, and other properties.

```typescript
getMeasureDetails(): Promise<MeasureDetails>
```

**Returns:** `Promise<MeasureDetails>`

**MeasureDetails**

Comprehensive details about a measure

Properties:

* `clef`: `Clef` - Current clef in this measure
* `'displayed-time'`: `DisplayedTime` - Time signature as displayed (can differ for pickup measures, etc.)
* `key`: `Key` - Current key signature
* `tempo`: `Tempo` - Tempo marking (always included, populated from current tempo)
* `time`: `Time` - Actual time signature
* `transpose`: `Transpose` - Transposition settings for this measure

**Throws:**

* `Error` - If no score is loaded or details cannot be retrieved

**Example:**

```typescript
const embed = new Embed('container', config);
const measureDetails = await embed.getMeasureDetails();
console.log(measureDetails);
```

**See also:**

* [`getNbMeasures()`](#getnbmeasures) - Get measure count
* [`getMeasuresUuids()`](#getmeasuresuuids) - Get measure identifiers

***

### getNbParts() {#getnbparts}

Get the number of parts in the score

Retrieves the total count of instrument parts in the currently loaded score.

```typescript
getNbParts(): Promise<number>
```

**Returns:** `Promise<number>`

**Throws:**

* `Error` - If no score is loaded

**Example:**

```typescript
const embed = new Embed('container', config);
const nbParts = await embed.getNbParts();
console.log(nbParts);
```

**See also:**

* [`getParts()`](#getparts) - Get detailed part information
* [`getPartsUuids()`](#getpartsuuids) - Get part identifiers

***

### getPartsUuids() {#getpartsuuids}

Get the part UUIDs of the score

Retrieves the unique identifiers for all parts in the score. These UUIDs are used to reference specific parts in volume, mute, and other part-specific operations.

```typescript
getPartsUuids(): Promise<string[]>
```

**Returns:** `Promise<string[]>`

**Throws:**

* `Error` - If no score is loaded

**Example:**

```typescript
const embed = new Embed('container', config);
const partsUuids = await embed.getPartsUuids();
console.log(partsUuids);
```

**See also:**

* [`getNbParts()`](#getnbparts) - Get the total number of parts
* [`getParts()`](#getparts) - Get detailed part information

***

### getMeasureVoicesUuids() {#getmeasurevoicesuuids}

Get voice UUIDs for a specific measure

Retrieves the unique identifiers of all voices present in a specific measure of a part. Voices represent independent melodic lines within a part.

```typescript
getMeasureVoicesUuids(parameters: { partUuid: string; measureUuid: string; }): Promise<string[]>
```

**Parameters:**

* `parameters.partUuid` - `string`
* `parameters.measureUuid` - `string`

**Returns:** `Promise<string[]>`

**Throws:**

* `Error` - If the part or measure UUID is invalid

**Example:**

```typescript
const embed = new Embed('container', config);
const measureVoicesUuids = await embed.getMeasureVoicesUuids({
  partUuid: '00000000-0000-0000-0000-000000000001',
  measureUuid: '00000000-0000-0000-0000-000000000002'
});
console.log(measureVoicesUuids);
```

**See also:**

* [`getMeasureNbNotes()`](#getmeasurenbnotes) - Count notes in a voice

***

### getMeasureNbNotes() {#getmeasurenbnotes}

Get the number of notes in a voice

Counts the total number of notes (including rests) in a specific voice within a measure. This is useful for iterating through notes or determining voice complexity.

```typescript
getMeasureNbNotes(parameters: { partUuid: string; measureUuid: string; voiceUuid: string; }): Promise<number>
```

**Parameters:**

* `parameters.partUuid` - `string`
* `parameters.measureUuid` - `string`
* `parameters.voiceUuid` - `string`

**Returns:** `Promise<number>`

**Throws:**

* `Error` - If any UUID is invalid

**Example:**

```typescript
const embed = new Embed('container', config);
const measureNbNotes = await embed.getMeasureNbNotes({
  partUuid: '00000000-0000-0000-0000-000000000001',
  measureUuid: '00000000-0000-0000-0000-000000000002',
  voiceUuid: '00000000-0000-0000-0000-000000000003'
});
console.log(measureNbNotes);
```

**See also:**

* [`getNoteData()`](#getnotedata) - Get details about specific notes
* [`getMeasureVoicesUuids()`](#getmeasurevoicesuuids) - Get voice UUIDs

***

### getNoteData() {#getnotedata}

Get information about a specific note

Retrieves detailed information about a note at a specific position, including pitch, duration, articulations, and other musical properties.

```typescript
getNoteData(parameters: { partUuid: string; measureUuid: string; voiceUuid: string; noteIdx: number; }): Promise<NoteDetails>
```

**Parameters:**

* `parameters.partUuid` - `string`
* `parameters.measureUuid` - `string`
* `parameters.voiceUuid` - `string`
* `parameters.noteIdx` - `number`

**Returns:** `Promise<NoteDetails>`

**NoteDetails**

Detailed information about a note or rest Note: The actual structure of complex fields (articulations, harmony, etc.) depends on the score content and Flat's internal representation

Properties:

* `articulations`: `string[]` - List of articulation markings (e.g., 'accent', 'staccato', 'tenuto')
* `classicHarmony`: `null | RomanNumeralData` - Classical harmony notation (Roman numerals, etc.)
* `durationType`: `string` - Duration type in MusicXML format (e.g., 'quarter', 'eighth', 'half', 'whole')
* `dynamicStyle`: `null | string` - Dynamic marking style (e.g., 'p', 'f', 'mf', 'crescendo')
* `ghostNotes`: `boolean[]` - Ghost note status for each pitch in chord (for guitar/drums)
* `hammerOnPullOffs`: `boolean[]` - Hammer-on/pull-off status for each pitch (for guitar)
* `harmony`: `null | JazzChordData` - Jazz/pop chord symbol
* `hasArpeggio`: `boolean` - Whether this note/chord has an arpeggio marking
* `hasGlissando`: `boolean` - Whether this note starts a glissando
* `isChord`: `boolean` - Whether this is a chord (multiple pitches)
* `isInSlur`: `boolean` - Whether this note is part of a slur
* `isRest`: `boolean` - Whether this is a rest (no pitches)
* `isTied`: `boolean` - Whether this note is tied to the next
* `lines`: `number[]` - Staff line positions for each pitch
* `lyrics`: `LyricLine[]` - Lyrics attached to this note
* `nbDots`: `number` - Number of augmentation dots
* `nbGraces`: `number` - Number of grace notes attached
* `ornaments`: `OrnamentObject` - Ornaments on the note
* `pitches`: `Pitch[]` - Array of pitches (empty for rests)
* `technical`: `string[]` - Technical markings (for strings/guitar, e.g., 'up-bow', 'down-bow', 'harmonic')
* `tupletType`: `null | TupletType` - Tuplet information if part of irregular grouping
* `wedgeType`: `WedgeType` - Wedge (hairpin) type if present

**Throws:**

* `Error` - If the position is invalid or note not found

**Example:**

```typescript
const embed = new Embed('container', config);
const noteData = await embed.getNoteData({
  partUuid: '00000000-0000-0000-0000-000000000001',
  measureUuid: '00000000-0000-0000-0000-000000000002',
  voiceUuid: '00000000-0000-0000-0000-000000000003',
  noteIdx: 0
});
console.log(noteData);
```

**See also:**

* [`getMeasureNbNotes()`](#getmeasurenbnotes) - Get total notes in voice

***

### playbackPositionToNoteIdx() {#playbackpositiontonoteidx}

Convert playback position to note index

Finds the note index that corresponds to a specific playback position. This is useful for synchronizing visual elements with audio playback.

```typescript
playbackPositionToNoteIdx(parameters: { partUuid: string; voiceUuid: string; playbackPosition: PlaybackPosition; }): Promise<number>
```

**Parameters:**

* `parameters.partUuid` - `string`
* `parameters.voiceUuid` - `string`
* `parameters.playbackPosition` - `PlaybackPosition`

**Returns:** `Promise<number>`

**Throws:**

* `Error` - If the position cannot be mapped to a note

**Example:**

```typescript
const embed = new Embed('container', config);
await embed.playbackPositionToNoteIdx({
  partUuid: '00000000-0000-0000-0000-000000000001',
  voiceUuid: '00000000-0000-0000-0000-000000000003',
  playbackPosition: 
});
```

**See also:**

* [`getNoteData()`](#getnotedata) - Get note details at index

***

### getNoteDetails() {#getnotedetails}

Get note details at cursor position

Retrieves detailed information about the note at the current cursor position, including pitch, duration, and musical attributes.

```typescript
getNoteDetails(): Promise<NoteDetails>
```

**Returns:** `Promise<NoteDetails>`

**NoteDetails**

Detailed information about a note or rest Note: The actual structure of complex fields (articulations, harmony, etc.) depends on the score content and Flat's internal representation

Properties:

* `articulations`: `string[]` - List of articulation markings (e.g., 'accent', 'staccato', 'tenuto')
* `classicHarmony`: `null | RomanNumeralData` - Classical harmony notation (Roman numerals, etc.)
* `durationType`: `string` - Duration type in MusicXML format (e.g., 'quarter', 'eighth', 'half', 'whole')
* `dynamicStyle`: `null | string` - Dynamic marking style (e.g., 'p', 'f', 'mf', 'crescendo')
* `ghostNotes`: `boolean[]` - Ghost note status for each pitch in chord (for guitar/drums)
* `hammerOnPullOffs`: `boolean[]` - Hammer-on/pull-off status for each pitch (for guitar)
* `harmony`: `null | JazzChordData` - Jazz/pop chord symbol
* `hasArpeggio`: `boolean` - Whether this note/chord has an arpeggio marking
* `hasGlissando`: `boolean` - Whether this note starts a glissando
* `isChord`: `boolean` - Whether this is a chord (multiple pitches)
* `isInSlur`: `boolean` - Whether this note is part of a slur
* `isRest`: `boolean` - Whether this is a rest (no pitches)
* `isTied`: `boolean` - Whether this note is tied to the next
* `lines`: `number[]` - Staff line positions for each pitch
* `lyrics`: `LyricLine[]` - Lyrics attached to this note
* `nbDots`: `number` - Number of augmentation dots
* `nbGraces`: `number` - Number of grace notes attached
* `ornaments`: `OrnamentObject` - Ornaments on the note
* `pitches`: `Pitch[]` - Array of pitches (empty for rests)
* `technical`: `string[]` - Technical markings (for strings/guitar, e.g., 'up-bow', 'down-bow', 'harmonic')
* `tupletType`: `null | TupletType` - Tuplet information if part of irregular grouping
* `wedgeType`: `WedgeType` - Wedge (hairpin) type if present

**Throws:**

* `Error` - If no note is at the cursor position

**Example:**

```typescript
const embed = new Embed('container', config);
const noteDetails = await embed.getNoteDetails();
console.log(noteDetails);
```

**See also:**

* [`getCursorPosition()`](#getcursorposition) - Get cursor position
* [`getNoteData()`](#getnotedata) - Get note at specific position

***

---

---
url: /developers/docs/embed/api/score-management.md
description: Methods for loading and exporting scores in various formats
---

# Score Management

Methods for loading and exporting scores in various formats

## Methods

### loadFlatScore() {#loadflatscore}

Load a score hosted on Flat

Loads a Flat score by its unique identifier. For private scores, you must provide the sharing key obtained from a private link.

```typescript
loadFlatScore(score: string | { score: string; sharingKey?: string; }): Promise<void>
```

**Parameters:**

* `score.score` - `string`
* `score.sharingKey?` - `string`

**Returns:** `Promise<void>`

**Throws:**

* `TypeError` - If the score parameter is invalid
* `Error` - If the score cannot be loaded (e.g., not found, access denied)

**Examples:**

```typescript
// Load a public score
await embed.loadFlatScore('56ae21579a127715a02901a6');
```

```typescript
// Load a private score with sharing key
await embed.loadFlatScore({
  score: '56ae21579a127715a02901a6',
  sharingKey: 'f79c3c0dd1fc76ed8b30d6f2c845c8c30f11fe88d9fc39ab96e8e407629d4885'
});
```

***

### loadMusicXML() {#loadmusicxml}

Load a MusicXML score

Loads a MusicXML score from a string or binary data. The score will be converted to Flat's internal format and displayed in the embed.

```typescript
loadMusicXML(score: string | Uint8Array): Promise<void>
```

**Parameters:**

* `score` - `string | Uint8Array`

**Returns:** `Promise<void>`

**Throws:**

* `TypeError` - If the score format is invalid
* `Error` - If the MusicXML cannot be parsed or loaded

**Examples:**

```typescript
// Load from XML string
const xmlString = '<?xml version="1.0"?>...';
await embed.loadMusicXML(xmlString);
```

```typescript
// Load from compressed MXL file
const response = await fetch('score.mxl');
const buffer = await response.arrayBuffer();
await embed.loadMusicXML(new Uint8Array(buffer));
```

***

### loadMIDI() {#loadmidi}

Load a MIDI score

Loads a MIDI file and converts it to sheet music notation. Note that MIDI files contain performance data rather than notation, so the conversion may not perfectly represent the original musical intent.

```typescript
loadMIDI(score: Uint8Array): Promise<void>
```

**Parameters:**

* `score` - `Uint8Array`

**Returns:** `Promise<void>`

**Throws:**

* `TypeError` - If the score format is invalid
* `Error` - If the MIDI file cannot be parsed or loaded

**Examples:**

```typescript
// Load MIDI file from URL
const response = await fetch('song.mid');
const buffer = await response.arrayBuffer();
await embed.loadMIDI(new Uint8Array(buffer));
```

```typescript
// Load MIDI file from file input
const file = document.getElementById('fileInput').files[0];
const buffer = await file.arrayBuffer();
await embed.loadMIDI(new Uint8Array(buffer));
```

***

### loadJSON() {#loadjson}

Load a Flat JSON score

Loads a score from Flat's native JSON format. This format preserves all score data and is the most reliable way to transfer scores between Flat applications.

```typescript
loadJSON(score: string | Record<string, unknown>): Promise<void>
```

**Parameters:**

* `score` - `string | Record<string, unknown>`

**Returns:** `Promise<void>`

**Throws:**

* `TypeError` - If the JSON is invalid or cannot be parsed
* `Error` - If the score data is malformed or cannot be loaded

**Examples:**

```typescript
// Load from JSON object
const scoreData = await fetch('score.json').then(r => r.json());
await embed.loadJSON(scoreData);
```

```typescript
// Load from JSON string
const jsonString = '{"score-partwise": {...}}';
await embed.loadJSON(jsonString);
```

***

### loadABC() {#loadabc}

Load an ABC notation score

Loads a score from [ABC notation](https://en.wikipedia.org/wiki/ABC_notation), a text-based music notation format. The ABC string is converted to Flat's native format and rendered as sheet music.

```typescript
loadABC(score: string): Promise<void>
```

**Parameters:**

* `score` - `string`

**Returns:** `Promise<void>`

**Throws:**

* `TypeError` - If the ABC notation is invalid or cannot be parsed
* `Error` - If the score cannot be loaded

**Examples:**

```typescript
// Load from ABC string
await embed.loadABC('X:1\nT:Example\nM:4/4\nK:C\nCDEF|');
```

```typescript
// Load from fetched ABC file
const response = await fetch('tune.abc');
const abc = await response.text();
await embed.loadABC(abc);
```

***

### getJSON() {#getjson}

Get the score in Flat JSON format

Exports the currently loaded score as Flat's native JSON format. This format preserves all score data including notation, layout, and metadata.

```typescript
getJSON(): Promise<Record<string, unknown>>
```

**Returns:** `Promise<Record<string, unknown>>`

**Throws:**

* `Error` - If no score is currently loaded

**Examples:**

```typescript
// Export and save score data
const scoreData = await embed.getJSON();
const jsonString = JSON.stringify(scoreData);

// Save to file
const blob = new Blob([jsonString], { type: 'application/json' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'score.json';
a.click();
```

***

### getMusicXML() {#getmusicxml}

Convert the displayed score to MusicXML

Exports the currently loaded score as MusicXML, the standard format for sheet music notation exchange. Supports both uncompressed XML and compressed MXL formats.

```typescript
getMusicXML(options?: { compressed?: boolean; }): Promise<string | Uint8Array>
```

**Parameters:**

* `options.compressed` *(optional)* - `boolean`

**Returns:** `Promise<string | Uint8Array>`

**Throws:**

* `TypeError` - If options parameter is invalid
* `Error` - If no score is loaded or conversion fails

**Examples:**

```typescript
// Get uncompressed MusicXML
const xml = await embed.getMusicXML();
console.log(xml); // <?xml version="1.0"...
```

```typescript
// Get compressed MusicXML (.mxl)
const mxl = await embed.getMusicXML({ compressed: true });
const blob = new Blob([mxl], { type: 'application/vnd.recordare.musicxml' });
const url = URL.createObjectURL(blob);
```

***

### getPNG() {#getpng}

Convert the displayed score to PNG image

Exports the currently loaded score as a PNG image. Supports various export options including resolution, layout mode, and output format.

```typescript
getPNG(options?: { result?: 'Uint8Array' | 'dataURL'; dpi?: number; layout?: 'track' | 'page'; }): Promise<Uint8Array | string>
```

**Parameters:**

* `options.result` *(optional)* - `'Uint8Array' | 'dataURL'`: Export result (either a PNG returned as Uint8Array or in dataURL)
* `options.dpi` *(optional)* - `number`: DPI of exported image (min: 50, max: 300, default: 150)
* `options.layout` *(optional)* - `'track' | 'page'`: Layout of exported image

**Returns:** `Promise<Uint8Array | string>`

**Throws:**

* `TypeError` - If options parameter is invalid
* `Error` - If no score is loaded or conversion fails

**Examples:**

```typescript
// Get PNG as Uint8Array
const pngData = await embed.getPNG();
const blob = new Blob([pngData], { type: 'image/png' });
```

```typescript
// Get PNG as data URL for direct display
const dataUrl = await embed.getPNG({ result: 'dataURL' });
document.getElementById('preview').src = dataUrl;
```

```typescript
// High resolution export with page layout
const hqPng = await embed.getPNG({ dpi: 300, layout: 'page' });
```

***

### getMIDI() {#getmidi}

Convert the displayed score to MIDI

Exports the currently loaded score as a MIDI file. The MIDI file will contain performance data including notes, tempo, dynamics, and instrument information. Note that some notation elements may not be represented in MIDI format.

```typescript
getMIDI(): Promise<Uint8Array>
```

**Returns:** `Promise<Uint8Array>`

**Throws:**

* `Error` - If no score is loaded or conversion fails

**Examples:**

```typescript
// Export score as MIDI
const midiData = await embed.getMIDI();

// Save as file
const blob = new Blob([midiData], { type: 'audio/midi' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'score.mid';
a.click();
```

```typescript
// Play MIDI in browser (requires Web MIDI API)
const midiData = await embed.getMIDI();
// ... use with Web MIDI API or MIDI player library
```

***

### getMP3() {#getmp3}

Convert the displayed score to MP3 audio

Exports the currently loaded score as an MP3 audio file. The audio is rendered client-side using the browser's audio capabilities. This may take some time depending on the score length and complexity.

```typescript
getMP3(): Promise<Uint8Array>
```

**Returns:** `Promise<Uint8Array>`

**Throws:**

* `Error` - If no score is loaded or audio rendering fails

**Examples:**

```typescript
// Get MP3 and play it
const mp3Data = await embed.getMP3();
const blob = new Blob([mp3Data], { type: 'audio/mpeg' });
const url = URL.createObjectURL(blob);
const audio = new Audio(url);
audio.play();
```

```typescript
// Download MP3 file
const mp3Data = await embed.getMP3();
const blob = new Blob([mp3Data], { type: 'audio/mpeg' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'score.mp3';
a.click();
```

***

### getWAV() {#getwav}

Convert the displayed score to WAV audio

Exports the currently loaded score as a WAV audio file. The audio is rendered client-side using the browser's audio capabilities. WAV files are uncompressed and larger than MP3 but provide lossless audio quality.

```typescript
getWAV(): Promise<Uint8Array>
```

**Returns:** `Promise<Uint8Array>`

**Throws:**

* `Error` - If no score is loaded or audio rendering fails

**Examples:**

```typescript
// Get WAV and play it
const wavData = await embed.getWAV();
const blob = new Blob([wavData], { type: 'audio/wav' });
const url = URL.createObjectURL(blob);
const audio = new Audio(url);
audio.play();
```

```typescript
// Download WAV file
const wavData = await embed.getWAV();
const blob = new Blob([wavData], { type: 'audio/wav' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'score.wav';
a.click();
```

***

### getPDF() {#getpdf}

Convert the displayed score to PDF

Exports the currently loaded score as a PDF file. The PDF is generated client-side and includes all pages of the score with proper page layout.

```typescript
getPDF(options?: { parts?: string[]; isConcertPitch?: boolean; multiMeasuresRests?: boolean; outlineColoredNotes?: boolean; }): Promise<Uint8Array>
```

**Parameters:**

* `options.parts` *(optional)* - `string[]`: Filter to specific parts (array of part UUIDs)
* `options.isConcertPitch` *(optional)* - `boolean`: Export in concert pitch instead of transposed (default: false)
* `options.multiMeasuresRests` *(optional)* - `boolean`: Merge consecutive empty measures (default: false)
* `options.outlineColoredNotes` *(optional)* - `boolean`: Outline colored notes for B\&W printing (default: false)

**Returns:** `Promise<Uint8Array>`

**Throws:**

* `TypeError` - If options parameter is invalid
* `Error` - If no score is loaded or conversion fails

**Examples:**

```typescript
// Get PDF as Uint8Array
const pdfData = await embed.getPDF();
const blob = new Blob([pdfData], { type: 'application/pdf' });
```

```typescript
// Export specific parts with options
const parts = await embed.getParts();
const violinPdf = await embed.getPDF({
  parts: [parts[0].uuid],
  multiMeasuresRests: true,
  isConcertPitch: true
});
```

***

### getSVG() {#getsvg}

Convert the displayed score to SVG

Exports the currently loaded score as Scalable Vector Graphics (SVG). SVG is a vector format that can be scaled to any size without loss of quality, making it ideal for web display, printing, and embedding in documents.

```typescript
getSVG(options?: { layout?: 'track' | 'page'; }): Promise<string>
```

**Parameters:**

* `options.layout` *(optional)* - `'track' | 'page'`: Layout of exported SVG (default: 'track')

**Returns:** `Promise<string>`

**Throws:**

* `TypeError` - If options parameter is not an object
* `Error` - If no score is loaded or conversion fails

**Examples:**

```typescript
// Export score as SVG string
const svgString = await embed.getSVG();
document.getElementById('preview').innerHTML = svgString;
```

```typescript
// Export with page layout
const svgString = await embed.getSVG({ layout: 'page' });
const blob = new Blob([svgString], { type: 'image/svg+xml' });
const url = URL.createObjectURL(blob);
```

***

### getFlatScoreMetadata() {#getflatscoremetadata}

Get the metadata of the score (for scores hosted on Flat)

Retrieves metadata for scores that are hosted on Flat, including title, composer, collaborators, creation date, and other information available through Flat's API. This method only works for scores loaded via `loadFlatScore()`.

```typescript
getFlatScoreMetadata(): Promise<ScoreDetails>
```

**Returns:** `Promise<ScoreDetails>`

**ScoreDetails**

Complete score details including metadata and statistics

Properties:

* `id`: `string` - The unique identifier of the score
* `sharingKey` *(optional)*: `string` - The private sharing key of the score (available when the `privacy` mode is set to `privateLink`)
* `title`: `string` - The title of the score
* `privacy`: `ScorePrivacy` - Privacy setting of the score
* `user`: `UserPublic` - User who created the score
* `htmlUrl`: `string` - The url where the score can be viewed in a web browser
* `editHtmlUrl`: `string` - The url where the score can be edited in a web browser
* `subtitle` *(optional)*: `string` - Subtitle of the score
* `lyricist` *(optional)*: `string` - Lyricist of the score
* `arranger` *(optional)*: `string` - Arranger of the score
* `composer` *(optional)*: `string` - Composer of the score
* `description` *(optional)*: `string` - Description of the creation
* `tags` *(optional)*: `string[]` - Tags describing the score
* `creationType` *(optional)*: `ScoreCreationType` - Type of creation
* `license` *(optional)*: `ScoreLicense` - License of the score
* `licenseText` *(optional)*: `string` - Additional license text written on the exported/printed score
* `durationTime` *(optional)*: `number` - In seconds, an approximative duration of the score
* `numberMeasures` *(optional)*: `number` - The number of measures in the score
* `mainTempoQpm` *(optional)*: `number` - The main tempo of the score (in QPM)
* `mainKeySignature` *(optional)*: `number` - The main key signature of the score (expressed between -7 and 7).
* `rights` *(optional)*: `ResourceRights` - Access rights for the score
* `collaborators`: `ResourceCollaborator[]` - The list of the collaborators of the score
* `creationDate`: `string` - The date when the score was created
* `modificationDate` *(optional)*: `string` - The date of the last revision of the score
* `publicationDate` *(optional)*: `string` - The date when the score was published on Flat
* `scheduledDeletionDate` *(optional)*: `string` - The date when the score will be definitively deleted.
  This date can be in the past if the score will be deleted at the next deletion batch.
* `highlightedDate` *(optional)*: `string` - The date when the score was highlighted (featured) on our community
* `organization` *(optional)*: `string` - If the score has been created in an organization, the identifier of this organization
* `parentScore` *(optional)*: `string` - If the score has been forked, the unique identifier of the parent score
* `instruments`: `string[]` - An array of the instrument identifiers used in the last version of the score.
  The format of the strings is `{instrument-group}.{instrument-id}`.
* `instrumentsNames`: `string[]` - An array of the instrument names that match the indexes from the `instruments` list
* `samples`: `string[]` - An array of the audio samples identifiers used in the different score parts.
  The format of the strings is `{instrument-group}.{sample-id}`.
* `googleDriveFileId` *(optional)*: `string` - If the score exists on Google Drive, this field will contain the unique identifier
* `likes` *(optional)*: `ScoreLikesCounts` - Like statistics
* `comments` *(optional)*: `ScoreCommentsCounts` - Comment statistics
* `views` *(optional)*: `ScoreViewsCounts` - View statistics
* `plays` *(optional)*: `ScorePlaysCounts` - Play statistics
* `collections` *(optional)*: `string[]` - The list of parent collections which includes all the collections this score is included in

**Throws:**

* `Error` - If no Flat score is loaded or metadata is unavailable

**Example:**

```typescript
const embed = new Embed('container', config);
const flatScoreMetadata = await embed.getFlatScoreMetadata();
console.log(flatScoreMetadata);
```

**See also:**

* [Flat API Reference - getScore](https://flat.io/developers/api/reference/#operation/getScore)

***

---

---
url: /developers/docs/embed/introduction.md
description: >-
  Use our high-quality music and tabs notation engraving in your web sites and
  blogs with our customizable and interactive HTML Embed.
---

# Sheet music Embed

Flat is the most advanced music notation software on the web. Our products include high-quality music and tabs engraving, web-based music notation editing, real-time collaboration across devices, the complete history of every modification made on the music scores, WebAudio Playback and WebMIDI inputs/output... and much more!

Flat's Music notation Embed lets the visitors and users of your website view, edit, listen and print sheet music directly in your web pages with complete customization and endless possibilities. Discover a non-customized version of our embed to experience it:

## Flat's Technology

The [Flat platform](https://flat.io) is built on modern and standard web technologies and is the result of several years of R\&D. Flat's music engraving technology uses standard HTML5 (SVG) and JavaScript that works with any web browser including tablets and smartphones (your visitors and users won't need any app, plugin, or Flash).

Many people and companies have requested us to use our great technology and beautiful music engraving in their projects, apps, software, websites, and blogs. That's why we decided it make it available via an embeddable `<iframe>`:

* In a few click or lines or code, you get interactive sheet music ready to use on your website.
* You can easily create and edit music notation and TABs with our web editor [Flat](https://flat.io) and display them in no time on any web page.
* You can also [embed our editor directly in your site](javascript-editor), and let your users or visitors create and edit MusicXML files.
* We manage the hosting, the maintenance and of course the automatic updates and improvements with no modifications required on your end!

## Flat's Embed

You can try the embed for free with a personal [Flat](https://flat.io) account. Just create or open any sheet music, click on "Share > Embed" and you directly get the HTML code ready to use (no customization or API available). To use the full embed product, [sign up for a free trial](https://flat.io/embed).

Get our [JavaScript SDK](javascript) to use the full capabilities of the embed: easily interact with the sheet music, load and export any file on the fly, use our [embeddable editor](javascript-editor)... and much more! Check out our [live demos](demos) to see what's possible.

If you want to [customize it](url-parameters) (e.g. removing Flat Branding, changing the controls displayed, the colors and theme) or use our embed commercially, [subscribe to one our embed plan](https://flat.io/developers/apps).

Our embed offers include displaying sheet music in a completely customizable and interactive viewer and the ability for your users to edit sheet music in the embed. Any questions or requests? Please [feel free to reach out](mailto:developers@flat.io) and we will make our embed work for you!

---

---
url: /developers/docs/embed/url-parameters.md
description: >-
  Quickly customize our music notation engraving embed with the different URL
  parameters available and add your own sheet music viewer on your website.
---

# Sheet music Embed URL parameters

When [embedding sheet music](index.html) in your website or blog, you can easily customize and control to appearance, the display and the features available for your visitors and users.

The easiest way is by adding different URL parameters of our iframe, you can find the different options available for you below.

Please note that most of the customizations below are ony available in our [Embed Starter and Pro plans](https://flat.io/embed), or may  require the usage of an [API key](https://flat.io/developers/apps). If you need additional options not listed below, feel free to [contact us](mailto:developers@flat.io), we will make sure our embed works for you!

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| `appId` | Your application identifier (aka API key) | [Get yours](https://flat.io/embed) |
| `userId` | End-user opaque identifier for billing & analytics purpose | [Learn more](/embed/usage-billing) |
| `sharingKey` | The score sharing key when the privacy mode is `privateLink` |  |
| `locale` | The language of the user interface | See [available locales](#available-locales) below (default: `en`) |
| `mode` | The mode of the embed | `view`, [`edit`](javascript-editor) [\*](#options-only-available-on-embed-plan) (default = `view`) |

### Available locales

The following locales are supported for the `locale` parameter (default: `en`):

* Danish (`da`)
* Dutch (`nl`)
* English US (`en`)
* English UK (`en-GB`)
* Filipino (`fil`)
* Finnish (`fi`)
* French (`fr`)
* Canadian French (`fr-CA`)
* German (`de`)
* Hindi (`hi`)
* Indonesian (`id`)
* Italian (`it`)
* Japanese (`ja`)
* Japanese Hiragana (`ja-HIRA`)
* Korean (`ko`)
* Malay (`ms`)
* Norwegian Bokmål (`nb`)
* Polish (`pl`)
* Portuguese (`pt`)
* Brazilian Portuguese (`pt-BR`)
* Romanian (`ro`)
* Russian (`ru`)
* Spanish (`es`)
* Swedish (`sv`)
* Turkish (`tr`)
* Simplified Chinese (`zh-Hans`)
* Traditional Chinese Hong Kong (`zh-HK`)
* Traditional Chinese Taiwan (`zh-TW`)

## Layout and Music notation Engraving parameters

These URL query strings control the engraving display of your music scores. You can get more details by clicking on the parameter name.

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| [`layout`](#layout-mode-layout) | Display the score in responsive, page or track mode | `responsive`, `page` or `track` (default = `responsive`) |
| [`zoom`](#zoom-zoom) | Default zoom value | `auto` or `0.1` to `3` (default = `auto`)|
| [`parts`](#parts-to-display-parts) | Specify the parts to display | All the parts |
| [`drawOnlyFirstPage`](#first-page-only-drawonlyfirstpage) [\*](#options-only-available-on-embed-plan) | Only display the first `page` | `true` or `false` (default = `false`) |
| [`noHeader`](#hide-header-noheader) [\*](#options-only-available-on-embed-plan) | Hide the header of the first `page` (title, composer, lyricist) | `true` or `false` (default = `false`) |
| [`hideNonTab`](#tablature-only-hidenontab) [\*](#options-only-available-on-embed-plan) | Only display the tablatures | `true` or `false` (default = `false`) |
| `showTabRests` [\*](#options-only-available-on-embed-plan) | Display rests in TAB staff | `true` or `false` (default = `false`) |
| [`hideTempo`](#hide-tempo-marks-hidetempo) [\*](#options-only-available-on-embed-plan) | Do not display tempo marks | `true` or `false` (default = `false`) |
| [`displayOutOfPitch`](#out-of-range-notes-displayoutofpitch) [\*](#options-only-available-on-embed-plan) | Highlight notes our of tessitura | `true` or `false` (default = `true`) |
| [`displayFirstLinePartsNames`](#hide-part-names-displayfirstlinepartsnames) [\*](#options-only-available-on-embed-plan) | Hide part names | `true` or `false` (default = `true`) |
| [`displayOtherLinesPartsNames`](#hide-subsequent-part-names-displayotherlinespartsnames) [\*](#options-only-available-on-embed-plan) | Hide non first line part names | `true` or `false` (default = `false`) |
| [`respectSystemBreaks`](#system-breaks-respectsystembreaks) [\*](#options-only-available-on-embed-plan) | Respect system breaks on responsive layout | `false` |
| [`layoutId`](#saved-engraving-layout-layoutid) [\*](#options-only-available-on-embed-plan) | Apply a saved layout template from your account | [Read more](#saved-engraving-layout)

## Controls & Theme customization

If you want to customize the controls, including changing their main colors or hide some of them, you can add the following options in your URL.

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| [`theme*`](#embed-theme) [\*](#options-only-available-on-embed-plan)| Change the embed theme | [Read more](#embed-theme) |
| [`branding`](#remove-flat-branding-branding) [\*](#options-only-available-on-embed-plan) | Display or hide Flat logo | `true` or `false` (default = `true`)|
| [`controlsDisplay`](#controls-visibility-controlsdisplay) [\*](#options-only-available-on-embed-plan) | Display or hide main controls | `true` or `false` (default = `true`)|
| [`controlsPosition`](#controls-position-controlsposition) [\*](#options-only-available-on-embed-plan) | Controls position | `bottom` or `top` (default = `bottom`)|
| [`controlsPlay`](#playback-control-controlsplay) [\*](#options-only-available-on-embed-plan) | Display or hide the playback controls | `true` or `false` (default = `true`)|
| [`hideFlatPlayback`](#hide-flat-playback-hideflatplayback) [\*](#options-only-available-on-embed-plan) | Hide Flat playback | `true` or `false` (default = `false`)|
| [`controlsFullscreen`](#fullscreen-control-controlsfullscreen) [\*](#options-only-available-on-embed-plan) | Display or hide the fullscreen button | `true` or `false` (default = `true`)|
| [`controlsPanel`](#extra-controls-button-controlspanel) [\*](#options-only-available-on-embed-plan) | Display or hide the extra controls button | `true` or `false` (default = `true`)|
| [`controlsZoom`](#zoom-controls-controlszoom) [\*](#options-only-available-on-embed-plan) | Display or hide the zoom control | `true` or `false` (default = `true`)|
| [`controlsPrint`](#print-control-controlsprint) [\*](#options-only-available-on-embed-plan) | Display or hide the print button | `true` or `false` (default = `true`)|
| [`controlsParts`](#parts-list-controlsparts) [\*](#options-only-available-on-embed-plan) | Display or hide the parts list | `true` or `false` (default = `false`)|

## Audio & Video sources

On any score on hosted on Flat, you can link one or multiple audio/video sources. These ones can be hosted on YouTube, SoundCloud or Vimeo. You can easily synchronize them using our user interface or [REST API](https://flat.io/developers/api/reference/#operation/addScoreTrack).

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| `audioSource` | Audio source to use when loading the embed | `playback`, `default` (the track marked as default, or playback if none), or the [unique identifier of the track to use](https://flat.io/developers/api/reference/#operation/listScoreTracks) (default value = `playback`) |
| [`videoPosition`](#video-position-videoposition) | Display position of the video in the embed | `top`, `bottom`, `left`, `float`, `hidden` (default = `hidden`) |
| `videoFitWidth` | Should the video width fit the width of the container | `true` or `false` (default = `false`) |
| `videoMaxHeight` | Give a max height for the video | CSS size value (e.g. `400px`) |
| `playbackMetronome`[\*](#options-only-available-on-embed-plan)  | Metronome mode | `count-in`, `inactive`, `active` (default = `inactive`) |
| [`noAudio`](#enable-or-disable-audio-capabilities-noaudio) [\*](#options-only-available-on-embed-plan) | Enable or disable the audio capabilities | `true` or `false` (default = `false`)|
| [`noPlayNote`](#enable-or-diable-the-audio-feedback-when-changing-notes-noplaynote) [\*](#options-only-available-on-embed-plan) | Enable or diable the audio feedback when changing notes ("play-note")  | `true` or `false` (default = `false`)|

## Playback & MIDI options

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| `playbackMetronome` [\*](#options-only-available-on-embed-plan) | Metronome mode | `count-in`, `inactive`, `active` (default = `inactive`) |
| `playbackVolumeMaster` [\*](#options-only-available-on-embed-plan) | Master volume | `0` to `1` (default = `1`) |
| `MIDI` [\*](#options-only-available-on-embed-plan) | Enable MIDI Output Controls | `true` or `false` (default = `false`) |

## Editor mode

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| `editorInterface` [\*](#options-only-available-on-embed-plan) | Editor interface style | `desktop` or `mobile` (default = `desktop`) |
| [`toolsetId`](#editor-toolset) [\*](#options-only-available-on-embed-plan)  | Editor Toolset | [The toolset id to use (see below)](#editor-toolset) |
| `useQuarterTone` [\*](#options-only-available-on-embed-plan) | Always enable quarter tone edition | `false` |

## Parameters details and demos

### Layout mode (`layout`)

Change how the music notation is displayed on the page.

We support three different engraving modes:

* `responsive`

![Layout Responsive mode](/img/embed-layout-responsive.png)

* `page`

![Layout Page mode](/img/embed-layout-page.png)

* `track` (default)

![Layout page mode](/img/embed-layout-track.png)

### Zoom (`zoom`)

Control the scaling of the sheet music display.

You can use different zoom values:

* `auto` (default): If you use a [`page` layout mode](#layout-mode-layout), the page will always fit the width of the embed, and be resize if you resize the embed. In [`track` layout mode](#layout-mode-layout), this is equivalent to `1`.
* `0.1` to `3`: A scaling value, where `1` is the regular size and `3` multiples the size by 3.

Example with `zoom=3` (i.e. Zoom x3):

![Embed zoom](/img/embed-zoom.png)

### Parts to display (`parts`)

Specify which instruments or voices to show in the score.

By default, the embed will display all the parts of your embedded documents. You can choose the parts to display by default, by providing the list of the parts with a `parts` parameter.

This parameter supports multiple formats for the parts references, which must be separated by a comma:

* Parts UUIDs,
* Part indexes (idx), starting at `0` for the first part,
* Part names (e.g. `Piano`),
* Part Abbreviation (e.g. `Pno.`)

Examples of valid inputs:

* `parts=0,3,4`
* `parts=Violin,Viola`

You can also use the [`controlsParts` option](#parts-list-controlsparts) to display a component that will allow your users to choose the part(s) to display.

### First page only (`drawOnlyFirstPage`)

Display only the first page of the score, useful for previews.

If you want to only draw the first page of the score, for example, to create a preview of a score. Please note that the complete file will still be completely loaded in the embed. To protect it, we advise you to use a dedicated preview file with only 1 page or little more available to display.

Here is a demo with this option and the following parameters:

* `drawOnlyFirstPage=true`
* `branding=false`
* `controlsPosition=top`
* `controlsPrint=false`

![Only display the first page](/img/embed-drawOnlyFirstPage.png)

### Hide header (`noHeader`)

Remove the title and composer information from the first page.

You can use the parameter `noHeader` set to `true` to hide the header part of the page when using a page layout (`layout` = `page`).

### Tablature only (`hideNonTab`)

Show only tablature staves and hide standard notation.

If you want to only display the tablatures of the parts, and hide the music notations staves, you can enable the `hideNonTab` option.

![Only TAB](/img/embed-hideNonTab.png)

### Hide tempo marks (`hideTempo`)

Remove tempo markings from the displayed score.

If you want to hide the tempo marks, you can enable the `hideTempo` option.

![No tempo marks](/img/embed-hideTempo.png)

### Out of range notes (`displayOutOfPitch`)

Highlight notes that are outside an instrument's playable range.

If notes go out of the tessitura (out of the available sound range for the instrument), there will be not playback for those notes.
By default we highlight those notes with a red color, and some transparency effect.
If you want to remove this behaviour, you can set the `displayOutOfPitch` to false.

![Notes out of tessitura](/img/embed-displayOutOfPitch.png)

### Hide part names (`displayFirstLinePartsNames`)

Remove instrument names from the score.

If you want to hide the part (instrument) names, you can set the `displayFirstLinePartsNames` option to false.

![Do not display part names](/img/embed-hideAllPartName.png)

### Hide subsequent part names (`displayOtherLinesPartsNames`)

Show instrument names only on the first system.

If you want to only display part (instrument) names on the first system, you can set the `displayOtherLinesPartsNames` option to false.

![Do not display part names](/img/embed-hideOtherPartName.png)

### System breaks (`respectSystemBreaks`)

Maintain manual system breaks in responsive layout mode.

If you want the responsive layout to respect the layout settings for the number of measures per system, and the
forced system breaks, you can set the `respectSystemBreaks` option to true.

### Remove Flat branding (`branding`)

Hide the Flat logo and attribution (requires paid plan).

To remove the Flat logo from the controls, set the parameter `branding` to `false`.

![No Flat branding](/img/embed-branding.png)

### Controls visibility (`controlsDisplay`)

Show or hide the playback control bar.

If you implements your own controls or don't need them, you can disable the ones in the embed by setting the parameter `controlsDisplay` to `false`.

![Embed controls](/img/embed-controls.png)

### Controls position (`controlsPosition`)

Set where the control bar appears on screen.

By default the controls are displayed at the `bottom` of the embed. You can choose the display them at the top by setting the parameter `controlsPosition` to `top`.

![Embed controls at the top](/img/embed-ctrl-top.png)

### Playback control (`controlsPlay`)

Show or hide the play/pause button.

This control is displayed by default, you can hide it by setting this parameter to `false`.

![Playback control](/img/embed-play-ctrl.png)

### Audio capabilities (`noAudio`)

Enable or disable all audio playback features.

When this parameter is set to true, playback will be disabled, and no sound will be heard when adding a note or moving the cursor. Additionally, playback shortcuts will be deactivated.

### Note audio feedback (`noPlayNote`)

Play sound when adding or editing notes.

When this parameter is set to true, no sound will play when adding a note or moving the cursor.

### Hide Flat playback (`hideFlatPlayback`)

Show only alternative audio sources, not Flat's built-in playback.

If you want to display only the alternative audio sources (mp3/video/soundcloud), set this one to true.

![Hide Flat Playback](/img/embed-hideFlatPlayback.png)

### Fullscreen control (`controlsFullscreen`)

Show or hide the fullscreen button.

This control is displayed by default, you can hide it by setting this parameter to `false`.

![Fullscreen control](/img/embed-fullscreen-ctrl.png)

### Extra controls button (`controlsPanel`)

Show or hide the menu for additional controls.

This control is displayed by default, you can hide it by setting this parameter to `false`.

![Side Panel control](/img/embed-panel-ctrl.png)

### Zoom controls (`controlsZoom`)

Show or hide the zoom in/out controls.

This side panel is enabled by default, you can disable it by setting this parameter to `false`.

![Zoom control](/img/embed-fullscreen-ctrl.png)

### Print control (`controlsPrint`)

Show or hide the print button.

This control is displayed by default, you can hide it by setting this parameter to `false`.

![Print control](/img/embed-fullscreen-ctrl.png)

### Parts list (`controlsParts`)

Show or hide the instrument selection dropdown.

This component can be displayed by setting this parameter to `true`, and having a score with at least two parts.

![Print control](/img/embed-parts-ctrl.png)

### Editor Toolset

When using our embeddable editor, you might want to only make specific tools available to your end-users. Toolsets configurations are linked to your Flat developer account and can be managed in the [Embed Generator page](https://flat.io/developers/embed/generator):

* Select the score to embed (or one of your testing scores if you want to use [`loadMusicXML()` from our SDK](/embed/javascript#loadmusicxmlscore-mixed-promisevoid-error))
* Click on "**Editor**" under the "**Embed mode**"
* Under the customizations features, you will be able to select and manage your toolsets:

![Select a toolset](/img/embed-toolset-input.png)

You can then create and update your own configurations. They will be previewed on the generator page, making it easy to test and experiment our embed with your custom toolsets.

![Select a toolset](/img/embed-toolset-panel-edit.png)

Once you selected a toolset, its identifier (`toolsetId`) will be displayed in the generated code or iframe URL at the bottom of the page.

**Notes about toolsets**:

* Using a toolset **will enable or disable the tools across the embed**: toolbars, interfaces on the top of the score, mouse, keyboard shortcuts, and JavaScript API methods.
* Since the configurations are saved in your developer account, when updating the configuration on the generator page, **the updated configuration will also be applied in your existing embeds where you are using the same `toolsetId`**.

## Saved engraving layout (`layoutId`)

In the editor on our webapp, [you can save custom configuration of engraving](https://flat.io/help/en/music-notation-software/layout-templates) layout and re-use them across scores. This can includes custom text fonts, engraving fonts, colors, spacings, sizes, etc.

On our [generator page](https://flat.io/developers/embed/generator), you can select a layout to get its unique identifier and pass it as parameter when loading the embed (`layoutId`).

This will allow to easily update all your embedded scores when you want to change some engraving settings, those will dynamically be applied to all your embedded scores where the identifier is used.

### Embed theme

You can completely change the embed theme by changing the different color options available:

| Parameter | Element | Values |
|-----------|---------|--------|
| `themePrimary` | Theme primary color (e.g. play button) | [color (hex, rgba() or hsla()](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themePrimaryDark` | Theme primary dark color (e.g. used for hover/focus states) | [color (hex, rgba() or hsla()](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeControlsBackground` | Controls bar background | [color (hex, rgba() or hsla()](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeSlider` | Playback slider color | [color (hex)](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeCursorV0` | Cursor 1st Voice color | [color (hex)](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeCursorV1` | Cursor 2nd Voice color | [color (hex)](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeSelection` | Selection color | [color (hex)](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeScoreBackground` | Background of score | `white` or `transparent` |

Please note that these parameters need to be encoded if needed (e.g. `themeControlsBackground=%23B71C1C`).

Demo: Let's say that we want to hide the Flat branding, display the controls different reds (controls background and main voice cursor). We can use the following options as query strings:

* [`branding=false`](#remove-flat-branding-branding)
* `themeControlsBackground=#B71C1C`
* `themePrimary=#E53935`
* `themeCursorV0=#E53935`

![Embed themes demo](/img/embed-colors.png)

The `transparent` background option (`themeScoreBackground`) can be used when your page has a light background that is not white and that you are using the [`page` layout mode](#layout-mode-layout):

![Non-white background](/img/embed-transparent-background.png)

### Video position (`videoPosition`)

When using an [audio or video source](#audio--video-sources), you can customize the position of the player: `top`, `bottom`, `left`, `float`, `hidden`.

### `top`

![Video on the top of the score](/img/embed-video-top.png)

### `left`

![Video on the left of the score](/img/embed-video-left.png)

### `float`

![Video floating of the score](/img/embed-video-float.png)

## Options only available on Embed plan

All the options with a `*` are only available in our [Embed plans](https://flat.io/embed). Other options are also available on [Flat](https://flat.io) and [Flat for Education](https://flat.io/edu).

---

---
url: /developers/docs/embed/oembed.md
description: >-
  Simply use our music notation engraving interactive embed in your web pages
  with the oEmbed standard.
---

# Sheet music oEmbed

[oEmbed](http://oembed.com/) is an open standard to easily embed content from oEmbed providers into your site. The Flat oEmbed endpoint serves our embed code for any Flat Score URL:

* `https://flat.io/score/*`
* `https://*.flat.io/score/*`

This oEmbed endpoint work with any score shared as **Public** or **Private with sharing link** (scores with the privacy `public` or `privateLink` in our REST API).

## Endpoint

Flat's oEmbed is available at the following URL:

```text
https://flat.io/services/oembed
```

JSON Example:

```bash
$ curl "https://flat.io/services/oembed?format=json&url=https%3A%2F%2Fflat.io%2Fscore%2F56ae21579a127715a02901a6"
{
    "version": "1.0",
    "type": "rich",
    "provider_name": "Flat",
    "provider_url": "https://flat.io",
    "author_url": "https://flat.io/flat",
    "author_name": "Flat Team",
    "width": 800,
    "height": 400,
    "title": "House of the Rising Sun",
    "html": "<iframe src=\"https://flat.io/embed/56ae21579a127715a02901a6?\" allowfullscreen height=\"400\" width=\"800\" frameBorder=\"0\"></iframe>",
    "thumbnail_url": "https://flat.io/api/v2/scores/56ae21579a127715a02901a6/revisions/last/thumbnail.png"
}
```

XML Example:

```bash
$ curl "https://flat.io/services/oembed?format=xml&url=https%3A%2F%2Fflat.io%2Fscore%2F56ae21579a127715a02901a6"
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<oembed>
  <version>1.0</version>
  <title>House of the Rising Sun</title>
  <type>rich</type>
  <width>800</width>
  <height>400</height>
  <html>&lt;iframe src=&#34;https://flat.io/embed/56ae21579a127715a02901a6?&#34; allowfullscreen height=&#34;400&#34; width=&#34;800&#34; frameBorder=&#34;0&#34;&gt;&lt;/iframe&gt;</html>
  <author_name>Flat Team</author_name>
  <author_url>https://flat.io/flat</author_url>
  <provider_name>Flat</provider_name>
  <provider_url>https://flat.io</provider_url>
  <thumbnail_url>https://flat.io/api/v2/scores/56ae21579a127715a02901a6/revisions/last/thumbnail.png</thumbnail_url>
</oembed>
```

## oEmbed Parameters

We support all the following standard parameters:

| Parameters | Required | Description | Default value |
|:-----------|:---------|-------------|---------------|
| `url` | required | The URL of the sheet music to be embedded ||
| `format` | optional | The returned format (`json` and `xml` are supported) | `json` |
| `maxwidth` | optional | The maximum width of a rendered score in whole pixels. This value must be at least `100`, otherwise the width will be 100px. | `800` |
| `maxheight` | optional | The maximum height of a rendered score in whole pixels. This value must be at least `100`, otherwise the width will be 100px. | `400`

## Custom [Embed URL Parameters](url-parameters)

If extra query parameters are specified in the oEmbed request or in the URL you are retrieving embedding information from, they will be passed to the final embed URL. This allows you to easily use all of your [Embed URL Parameters](url-parameters).

```text
https://flat.io/services/oembed?format=json&url=https%3A%2F%2Fflat.io%2Fscore%2F56ae21579a127715a02901a6&layout=track
https://flat.io/services/oembed?format=json&url=https%3A%2F%2Fflat.io%2Fscore%2F56ae21579a127715a02901a6%3Flayout%3Dtrack
```

---

---
url: /developers/docs/api/reference.md
---


---

---
url: /developers/docs/api/flat-for-education.md
---

# Using our APIs with Flat for Education

Our REST API is the perfect solution to interact with your Flat for Education accounts and extend the capabilities of our platform. Let's discover on this page how to take full advantage of its features.

In this page:

* [Available features in the API](#available-features-in-the-api)
* [Your first steps with our REST API](#your-first-steps-with-our-rest-api)
* [Interacting with other teachers and students' accounts](#interacting-with-other-teachers-and-students-accounts)
  * [Search user account ID](#search-user-account-id)
  * [Create access token for your end-user](#create-access-token-for-your-end-user)
  * [Use the delegated access token](#use-the-delegated-access-token)
* [Creating Sign-in links](#creating-sign-in-links)
  * [Search user account ID](#search-user-account-id-1)
  * [New sign-in link](#new-sign-in-link)

Any questions? Please contact our team at <edu@flat.io>.

## Available features in the API

Our web and mobile applications use the same API we make available to our customers, which means most of our platform features can be used programmatically.

For example:

* [Creating a new score or import a new score file](https://flat.io/developers/api/reference/#operation/createScore) in a user account.
* [Creating](https://flat.io/developers/api/reference/#operation/createOrganizationUser), [managing](https://flat.io/developers/api/reference/#operation/listOrganizationUsers), and [deleting](https://flat.io/developers/api/reference/#operation/removeOrganizationUser) students and teachers accounts.
* [Creating](https://flat.io/developers/api/reference/#operation/createClass), [accessing](https://flat.io/developers/api/reference/#operation/listClasses)  classes, and [managing rostering](https://flat.io/developers/api/reference/#operation/addClassUser).
* [Creating](https://flat.io/developers/api/reference/#operation/createAssignment) assignments, [submitting them as students](https://flat.io/developers/api/reference/#operation/createSubmission), and [exporting grades](https://flat.io/developers/api/reference/#operation/exportSubmissionsReviewsAsCsv).

Let's discover below how to get started with our API.

## Your first steps with our REST API

To get started with our Flat for Education API:

1. If you do not have a Flat for Education school account, [create one on our website](https://flat.io/edu).
2. Using your education account, [register a new app](https://flat.io/developers/apps). Then on the left menu, choose **"Flat API > Personal Tokens"**.
   Choose a name and the authorization scopes for your first token.

That's all, you can directly use our API with this token by setting it in the `Authorization` headers of your requests:

```http
Authorization: Bearer my-api-personal-access-token
```

Here is an example with cURL:

```bash
curl -H 'Authorization: Bearer <my_api_personal_access_token>' \
  https://api.flat.io/v2/me
```

## Interacting with other teachers and students' accounts

Our education REST API includes an endpoint that lets you create delegated access tokens. These tokens let you interact with our product as another teachers or students without any user interaction required.
For example, you could automatically create classes or assignments for your teachers or create or upload scores in your students' accounts.

Once you created a student or teacher account whether [with our interface](https://flat.io/help/en/education/invite-students.html) or [our API](https://flat.io/developers/api/reference/#operation/createOrganizationUser), [create a personal access token](https://flat.io/developers/apps) as explained above with the `edu.admin.users` authorization.

For the following examples, let's set our token in a shell variable

```bash
export TOKEN=my-api-personal-access-token
```

### Search user account ID

If you do not know the unique identifier of the student/teacher account, you can use the [`GET /v2/organizations/users`](https://flat.io/developers/api/reference/#operation/listOrganizationUsers) API method to search it:

```bash
curl 'https://api.flat.io/v2/organizations/users?q=student42@gedu.demo.flat.io' \
  -H "Authorization: Bearer $TOKEN"
```

```json
[
  {
    "id": "STUDENT_USER_ID",
    "type": "user",
    "organizationRole": "user",
    "classRole": "student",
    "username": "tony",
    ...
  }
]
```

### Create access token for your end-user

Now create an access token for this student using [your admin API endpoint `POST /v2/organizations/users/{user}/accessToken`](https://flat.io/developers/api/reference/#operation/createOrganizationUserAccessToken).

For example with the `scores` authorization scope to be able to create new scores in the student's account and `collections` to access to their library:

```bash
curl -X POST 'https://api.flat.io/v2/organizations/users/STUDENT_USER_ID/accessToken' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"scopes": ["scores", "collections"]}'
```

```json
{
  "id": "61a4bc9750724f0013fdc7fd",
  "name": "Access token created by organization admin",
  "token": "An access token for your student account",
  "issuedDate": "2021-11-29T11:42:15.475Z",
  "expirationDate": "2021-11-30T11:42:15.475Z",
  "scopes": [
    "scores",
    "collections"
  ]
}
```

### Use the delegated access token

With the newly created access token, you can interact with the end-user account without any user interaction needed. For example, you can list your student library:

```bash
export STUDENT_TOKEN=student-access-token

curl 'https://api.flat.io/v2/collections/root/scores' \
  -H "Authorization: Bearer $STUDENT_TOKEN"
```

```json
[
  {
    "id": "615adeb58e4ed600136ab31d",
    "title": "My first assignment - Tony Morris",
    "privacy": "private",
    ....
  },
  ....
]
```

## Creating Sign-in links

Our education REST API includes an endpoint that lets you create sign in links for your users. They can typically be used to redirect your end-users to our platform while connecting them.

Once you created a student or teacher account whether [with our interface](https://flat.io/help/en/education/invite-students.html) or [our API](https://flat.io/developers/api/reference/#operation/createOrganizationUser), [create a personal access token](https://flat.io/developers/apps) as explained above with the `edu.admin.users` authorization.

For the following examples, let's set our token in a shell variable

```bash
export TOKEN=my-api-personal-access-token
```

### Search user account ID

If you do not know the unique identifier of the student/teacher account, you can use the [`GET /v2/organizations/users`](https://flat.io/developers/api/reference/#operation/listOrganizationUsers) API method to search it:

```bash
curl 'https://api.flat.io/v2/organizations/users?q=student42@gedu.demo.flat.io' \
  -H "Authorization: Bearer $TOKEN"
```

```json
[
  {
    "id": "STUDENT_USER_ID",
    "type": "user",
    "organizationRole": "user",
    "classRole": "student",
    "username": "tony",
    ...
  }
]
```

### New sign-in link

Now create a sign in link for this end-user using [your admin API endpoint `POST /v2/organizations/users/{user}/signinLink`](https://flat.io/developers/api/reference/#operation/createOrganizationUserSigninLink):

```bash
curl -X POST 'https://api.flat.io/v2/organizations/users/STUDENT_USER_ID/signinLink' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'
```

```json
{
  "url": "https://flat.io/auth/signin-link/xxxxxxxxxxxxxxxxxxx?next=%2F",
  "expirationDate": "2021-11-30T13:12:09.783Z"
}
```

The returned URL can be used once by your end-user to sign in. We recommand to use it in a HTTP Temporary Redirect ([302](https://en.wikipedia.org/wiki/HTTP_302)).

Optionally you can provide a [`destinationPath`](https://flat.io/developers/api/reference/#operation/createOrganizationUserSigninLink), for example, to redirect the user to a specific assignment or score once logged in.

## Discover the API

Check out [our API reference to learn more](https://flat.io/developers/api/reference/) about the REST API possibilities:

* [Scores](https://flat.io/developers/api/reference/#tag/Score) and [library collections](https://flat.io/developers/api/reference/#tag/Collection)
* [Flat for Education accounts management](https://flat.io/developers/api/reference/#operation/listOrganizationUsers)
* [Classes](https://flat.io/developers/api/reference/#operation/listClasses) and [assignments](https://flat.io/developers/api/reference/#operation/listAssignments).

Do you have some feedback about our product and APIs? Please contact our product team at <edu@flat.io>.