Flat REST API Changelog

We regularly update our API and services, you can discover all the changes to our public specification. While we try to avoid breaking changes during the Beta Period, they will be written below in bold if any.

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 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.