Tags: FlatIO/api-reference
Tags
feat(api): API specification v2.22.0
* 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`.
feat(api): API specification v2.20.0
* 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.
feat(api): API specification v2.19.0
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.
feat(api): API specification v2.18.0
* 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`.
feat(api): API specification v2.15.0
* 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.
PreviousNext