Flat REST API v2.22.0: Score Library Update, Student Groups, LTI 1.3 Configuration, and More

We just released v2.22.0 of the Flat REST API. This update brings API support for several features we shipped in the product over the past months, along with new endpoints and improvements across the board.

This release includes a breaking change in the collections API: the root and sharedWithMe collection aliases are deprecated and replaced by virtual collections. See the collections section below for details and migration steps.

Score library and collections (breaking change)

We redesigned the score library in Flat, and more recently in Flat for Education. The API now reflects those changes.

The root and sharedWithMe collection aliases are deprecated. The GET /collections endpoint now uses parent=user as the default, which returns all user collections including three new virtual collections:

• allScores – all scores in the user's account
• collaborations – all shared scores
• likes – liked scores

If your integration currently relies on root or sharedWithMe as collection parents, you should migrate to using user as the parent and the new virtual collections instead.

Collections also gained a few new properties:

• isPinned – whether the collection is pinned by its owner
• modificationDate – last modification timestamp
• A new modificationDate sort option on GET /collections

POST /collections/{collection}/untrash is also deprecated. Collections untrashing is no longer supported.

On the score side, ScoreDetails now includes a me object with isLiked and isInLibrary properties reflecting the authenticated user's relationship to the score.

Student groups API

We shipped Shared Writing for collaborative composition assignments. This update adds a full groups API for managing student sub-groups within classes and assignments.

New endpoints:

• GET /groups – list groups (filter by classroom, assignment, or type)
• POST /groups – create a group tied to a classroom
• PUT /groups/{group} – rename a group
• DELETE /groups/{group} – delete a group
• GET /groups/{group}/users – list group members
• POST /groups/{group}/users – add a student to a group
• DELETE /groups/{group}/users/{user} – remove a student from a group

Two group types are available: classStudentsSubGroup for groups within a class, and assignmentStudentsSubGroup for groups within a specific assignment.

Performance assignment options

Our performance assignments now expose several new recording and playback options in the API:

• recordingType – audio or video
• allowBackingTrack – allow students to use a backing track while recording
• allowMetronome – allow metronome during recording
• allowSpeedChange – allow tempo adjustment during recording
• submissionStudentsMode – single or group for shared writing assignments

Assignments and education resources also support rich-text descriptions with new descriptionHtml, teacherInstructionsHtml, and sharingDescriptionHtml properties.

Unified LTI configuration API

We recently upgraded Flat for Education to LTI 1.3 with support for Canvas, Schoology, Moodle, and Blackboard. The API now provides a single set of endpoints for managing both LTI 1.1 and LTI 1.3 configurations:

• GET /organizations/lti/configurations – list all LTI configurations
• POST /organizations/lti/configurations – create a configuration (1.1, 1.3 manual, 1.3 dynamic registration, or 1.3 deployment-based)
• PUT /organizations/lti/configurations/{configuration} – update a configuration
• DELETE /organizations/lti/configurations/{configuration} – delete a configuration

The new enableEmailMatching property controls whether email-based user matching is used during LTI authentication.

The previous LTI 1.1 credentials endpoints (/organizations/lti/credentials) are now deprecated in favor of this unified API.

Native .flat file export

You can now export scores in our native compressed format. The GET /scores/{score}/revisions/{revision}/{format} endpoint accepts flat as a format, returning a .flat file. The full list of supported export formats is now: json, mxl, xml, mp3, wav, midi, flat, thumbnail.png, and synchronizationPoints.

On the import side, we also documented the full range of formats supported by POST /scores: MusicXML, MIDI, Guitar Pro, MuseScore, ABC Notation, Encore, Capella, MEI, Overture, and more.

Organization and user improvements

• GET /organizations/users now supports a testAccounts filter, and UserDetailsAdmin includes an isEduTestingStudent flag for test student accounts.
• UserDetails gained an isEmailVerified property.
• OrganizationInvitation now includes an htmlUrl for a direct join link.
• ClassDetails gained a modificationDate property and updated lti context with hasNrpsService for LTI 1.1 and 1.3.
• UserPublic now includes allPublicScoresCount, the total number of public scores a user participates in.

Statistics

Score statistics endpoints (ScoreCommentsCounts, ScoreLikesCounts, ScorePlaysCounts, ScoreViewsCounts) now include yearly counts in addition to the existing weekly, monthly, and total values.

Other deprecations

• LTI 1.1 credentials endpoints (/organizations/lti/credentials) are deprecated. Use the new unified configuration API.
• The FlatLocales strict enum has been replaced by FlatLocalesString, a free-form string that gets auto-normalized.

Get started

Browse the complete specification in the Flat REST API Reference, or download the OpenAPI spec from GitHub. If you are building integrations with our sheet music embed, check out the Embed SDK v2 and the embed documentation.

Questions or feedback? Reach out at developers@flat.io.