Developer changelog

Flat now runs a remote Model Context Protocol server at https://mcp.flat.io/mcp, so any MCP client can work with the scores in a customer's Flat account.

• Four initial tools: search, score_get, score_export (MusicXML, compressed MusicXML, MIDI) and score_create (MusicXML, MIDI, ABC, MuseScore, Guitar Pro). Existing scores are never edited, deleted or made public.
• OAuth 2.1 with PKCE, single mcp scope, client registration through Client ID Metadata Documents or Dynamic Client Registration. No API key: the customer approves each client on Flat's consent screen.
• Works with Claude Code, Codex, Gemini CLI, Cursor and VS Code with a single command or config entry.

Requires an active Flat Power subscription on the connecting account. This first version covers reading and creating scores; we'll add tools based on your feedback at developers@flat.io.

Full guide: Flat MCP server.

The developer dashboard is rebuilt around what your integration can do. Each capability (Embed, OMR, REST API, Import API, LTI) gets a card with its scope, pricing and documentation, and the ones your app already uses come first.

• A new OMR section at the account level, with your jobs, your credits and their history in one place, since OMR credits are shared by all your apps.
• Try OMR before you write code. The playground takes a PDF or photos, shows the page count, the cost per page and the balance you would be left with, then runs the job once you confirm. Output goes to MusicXML downloads, nothing lands in your library.
• Clearer app pages. Personal tokens, OAuth2 credentials and OMR access are grouped per application, with the credentials that carry the OMR scope called out.

Open it from flat.io/developers.

Our REST API specification moves to OpenAPI 3.1, the OMR API closes its beta period, and Flat for Education assignments open up beyond listing and creating.

• The OMR API is stable. Endpoints, fields and behavior now follow our usual deprecation process before any breaking change. A new FAQ covers credits and billing, limits and processing times, recognition quality and languages, and commercial use and privacy.
• Read, update and delete assignments in Flat for Education. Deleting an assignment also removes its submissions and the students' copies; archive it instead to keep the work.
• Credit ledger. A new call lists your credit history; the balance stays on the OMR capabilities call.
• Finale files (.musx) can be imported, on a best-effort basis, and scanned music import (PDF and images) is documented on score creation.
• OpenAPI 3.1. Nullable fields use the 3.1 syntax; tooling pinned to OpenAPI 3.0 needs an update. The mimeType field was removed from OMR file uploads.

• Data retention you control. OMR jobs now tell you how long their files are kept (30 days by default), each MusicXML job carries its expiry date, and you can erase a job's files and results as soon as you have collected them.
• Feature detection before sign-in. The OMR capabilities call works without an account and lists the supported recognition languages with their names.
• ABC notation export for any score revision, alongside MusicXML, MIDI and the other formats. Like MIDI, it does not carry the full engraving.
• Free Record assignments can be configured through the API in Flat for Education.
• Errors coming from an upstream provider (Google Classroom, for example) now carry the provider's own localized message.

Flat's OMR engine is now available programmatically through the developer API. Send PDFs or photos, follow recognition progress, review the detected instruments, then import the result as an editable score in a Flat library or export MusicXML or MIDI. It's the same in-house model that powers PDF and photo import in the editor, now available at scale for your own apps and workflows.

The dedicated OMR API (v2.24.0) builds on the background PDF import added to score creation in v2.23.0: ask for task support when importing a file and poll the task until the score is ready. See the API changelog for the details of both releases.

The largest specification update since 2024, catching the API up with two years of product changes.

• Import from 15+ formats. Guitar Pro, MuseScore, ABC notation, PowerTab, Capella, MEI, Overture, TablEdit, Band-in-a-Box, Karaoke MIDI, MuseData, Score Writer, Bagpipe Music Writer and Encore join MusicXML and MIDI, and scores can be exported as native .flat files.
• Virtual collections. All scores, collaborations and likes replace the legacy folder hierarchy in the library, matching the redesigned Flat library.
• Flat for Education. Performance assignments with audio or video recordings and backing track, metronome and speed options; group submissions for shared writing; rich text instructions; student sub-groups; scheduled and individually targeted Microsoft Teams assignments; rich descriptions and assignment types in the resource library.
• Unified LTI configuration for LTI 1.1 and 1.3, including dynamic registration. The previous LTI 1.1 credentials calls are deprecated.
• Yearly statistics on scores, public score counts on profiles, and removal of a few long-deprecated fields.

• Added methods getMP3 and getWAV for audio export
• Added the exportProgress event, so a long export can show progress

• User score listings are public profiles. Listing a user's scores now returns only their public scores, with new pagination and sorting, the change announced in 2020.
• Score details expose the edit URL, instrument names and any scheduled deletion date; collections report their scores count; public profiles show likes and plays counts.
• Flat for Education. Filter the resource library by assignment type, subject and grade; resources carry a sharing description and privacy capabilities; assignments can restrict note playing and audio tracks; submissions support LTI 1.1 and 1.3 grade services.

• Paginated likes on user profiles, and the product a user is on in their account details.
• Resource rights say whether the caller is the owner, a user collaborator or a group collaborator, with the date each collaborator was added. Score details add the main key signature, highlight date and organization.
• Flat for Education. Invitations can be reused several times; submissions gain a graded state plus playback and LTI details; an assignment can be copied to the resource library only if it is not already there; organizations get their own resource libraries with an organization-wide privacy level.

Read the structure of the loaded score from your code.

• Parts and voices: getNbParts, getPartsUuids, getMeasureVoicesUuids
• Notes: getMeasureNbNotes, getNoteData, playbackPositionToNoteIdx
• New URL parameter noAudio disables audio playback
• Fixed setMasterVolume calling the wrong underlying method

• Removed support for jQuery in the constructor — pass a DOM element or its id instead
• The published npm module ships TypeScript types
• Separate ES and UMD builds

• Create LTI links from Flat for Education resource library items, to place them in an LMS course directly.
• The maximum grade on an assignment goes from 100 to 10,000 points.
• Score metadata (subtitle, composer, lyricist, arranger, description, license…) can now be cleared through the API, not only set.

• Resource Library API (beta). Browse and manage Flat for Education resource libraries, with two new OAuth2 scopes for full and read-only access. Assignments can be copied to the resource library.
• Test students. Create testing student accounts in a class to try assignments as a student would.
• Assignments report what you can do with them (edit, publish, archive…), whether their attachments are dedicated copies, and any issue encountered. Submission history records the source of a change when it comes from Google Classroom, Microsoft Teams or an LMS.
• Resetting a submission keeps it in place instead of deleting it; class metadata (level, skills, size) and Microsoft sign-in details on accounts are exposed.
• Score revisions return their start and end dates; score builders can enable quarter tones; copies can keep the original title.

• Measures: getNbMeasures, getMeasuresUuids
• Navigation: goLeft, goRight, scrollToCursor
• Metronome: getMetronomeMode, setMetronomeMode
• Playback speed: getPlaybackSpeed, setPlaybackSpeed

• Sign-in links and delegated access tokens. Flat for Education admins can create a sign-in link for any user of their organization, or an access token acting on that user's behalf: the basis for custom portals and single sign-on integrations.
• Japanese in hiragana (ja-HIRA) joins the supported locales; public comments expose their moderation state.
• Audio exports return the MP3 set as the default track when one exists. The option to request only cached exports was removed, since audio exports are always served from cache now.

• Score builder. Create a blank score without importing a MusicXML file: give a list of instruments and, optionally, the time signature, key signature, tablature, chord grids and page layout.
• Flat for Education. Organization users can be created with a role; worksheets can shuffle their exercises; student submissions list the exercises they contain.

• Playback tracks. List the tracks Flat generates and syncs automatically (playback as an MP3), fetch the synchronization points of the latest playback file, and get the CDN URL of an export in the response body.
• Flat for Education. Teachers can reset a student's submission; classes report the accounts that could not be added during a sync; assignments and submissions expose their Microsoft Teams state and links; assignment copies can be scheduled; performance submissions carry their saved audio track.
• Profiles gain a cover picture, and the current user's id can be fetched on its own.

• loadFlatScore accepts a sharingKey, so a privately shared score can be loaded
• Added setTrack, useTrack and seekTrackTo to set the audio track dynamically

• Grade exports. Download an assignment's grades as a CSV or Excel file.
• Assignments carry their type and a cover image; copying an assignment can overwrite an existing draft with another assignment's content.
• Collaborators show whether they are still a pending invitation.

• Grading through the API. Set draft and final grades, return a submission to a student, and read computed comment counters; the maximum points are stored with the grade.
• Submission comments. Create, list, update and delete comments on a submission.
• Assignment options. Toolsets, a playback limit, maximum points, Google Classroom topics, assigning specific students, locked templates, and details of LTI, Canvas and MusicFirst assignments.
• Admins can edit a managed account's username, name and email; user listings can be filtered by active license.
• The old studentComment and returnFeedback submission parameters were removed in favor of the new grading calls.

• Archive and unarchive assignments, and read an assignment's main type (new score, template or shared writing).
• Organization users. Create accounts with a first and last name, sort and filter user listings, count the users matching a filter, and filter group members by their sync source (Google Classroom, Microsoft Teams, Clever).
• Score details list the audio samples used by playback, with a normalized instrument list that no longer depends on the samples.

Control the mix from your code, and read what is under the cursor.

• Volume and mute: getMasterVolume, setMasterVolume, getPartVolume, setPartVolume, mutePart, unmutePart
• Solo and reverb: setPartSoloMode, unsetPartSoloMode, getPartSoloMode, getPartReverb, setPartReverb
• Inspection: getMeasureDetails, getNoteDetails
• Added events: noteDetails, measureDetails, cursorContext

• The specification moves to OpenAPI 3.0. Previous versions were described in OpenAPI 2 (Swagger).
• Scores expose an arranger and their plays statistics; a deletion can be scheduled to run shortly instead of sitting in the trash.
• Flat for Education. Assignment attachments can be Google Drive files, classes carry their Microsoft Teams details, and education accounts expose a first and last name.

• Metadata edits reach the editor live. Updating a score's title, subtitle, composer, lyricist or license text through the API is pushed to open editors in real time, and a new version is saved. Descriptions can be twice as long (2,000 characters).
• Education submissions expose their state (created, turned in, returned); revision metadata returns the last modification event.
• Turkish joins the supported locales; public profiles say whether an account belongs to the Flat team.

• Added getMIDI
• getMusicXML now returns a Uint8Array at the top level — the response no longer carries a .data property
• The cursor's voiceIdx is now voiceIdxInStaff

Updated for the embed release.

• The SDK now loads from flat-embed.com by default
• Removed the deprecated edit action and edit event
• Removed setNoteColor

• More import formats. Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar and MuseScore files can be imported, and imports accept a filename.
• Collections can be listed under a parent collection and report their creation date; scores list the collections they belong to.
• Contextual comments are anchored to a staff by identifier rather than by index, and resource rights say whether the caller is a collaborator.

• Collections API. Create, list, update, delete and restore collections, list their scores, and add or remove scores, with three new OAuth2 scopes for read-only, add-only and full access.
• Scores can be restored from the trash; deleting a score without admin rights unshares it from your account instead; a copy can target a specific collection.
• Comments can be filtered by type (document or inline).
• Part exports now take part identifiers instead of indexes, and from September 2019 a user's score listing only returns public scores.

• Organization account management. Admins can update managed accounts, and delete them or convert them to consumer accounts; user and invitation listings use cursor-based pagination.
• Classes gain an inactive state that can be activated again, and report their Canvas LMS domain and Clever section; assignments gain a draft state and an exercise attachment type.
• Profiles expose a theme and the instruments played.

• Added method focusScore to give the embed keyboard focus
• New defaultMode property in the editor config

• The first education APIs are public. Manage classes, assignments and submissions, organization accounts and invitations, LTI credentials, and the groups and users of an organization: everything a school integration needs.
• Scoped access. New OAuth2 scopes cover classes, assignments and organization administration, each with a read-only variant, so an integration only asks for what it needs.

Your code can now inspect how the embed is configured and turn it into an editor.

• Added methods: getEmbedConfig, setEditorConfig, edit
• Added event: edit

The SDK learns to load scores from MusicXML and to report what the reader is doing.

• Added methods: getAutoZoom, setAutoZoom, loadMusicXML, getMusicXML
• Added events: scoreLoaded, cursorPosition, rangeSelection, pause, stop, fullscreen, print
• Added integration tests

The first public release of Flat's REST API. Read and manage your account, scores, users and groups from your own apps and scripts, with OAuth2 for acting on behalf of other Flat users.

Everything since is recorded in the API changelog, and the developer documentation covers authentication, the reference and guides.