Patch release. No breaking change.

• Optical Music Recognition (OMR):
  • POST /omr/jobs (createOmrJob): Added autoRotate. Off by default: pages are recognized in the orientation they are uploaded in, which is right when your client lets the user rotate pages before upload. Set it to true when it does not (for example a server-to-server integration importing scans as they come) and the server detects and corrects pages uploaded sideways or upside down before recognition. Small tilt correction always runs. OmrJob echoes the value.
• Documentation only, no change on the wire.

Full changelog: https://flat.io/developers/docs/api/changelog

Patch release. No wire change, no breaking change.

• LTI:
  • POST /organizations/lti/credentials (createLtiConfiguration): The 200 response is now LtiConfiguration directly, instead of an inline allOf wrapping it to add registrationUrl. LtiConfiguration1p3Dynamic already carries that property, so the response is unchanged on the wire. The wrapper made code generators emit a type extending a union, which some languages cannot express at all.

• Our API specification is now in OpenAPI 3.1.0 (previously 3.0.3). Nullable fields are declared type: [<type>, 'null'] instead of nullable: true. No field changed nullability, but tooling pinned to 3.0 will need updating.
• Flat for Education:
  • GET, PUT and DELETE /classes/{class}/assignments/{assignment} (getAssignment, updateClassAssignment, deleteAssignment): Read, update and delete an assignment. Previously only listing and creating were public. PUT updates only the properties it carries, except attachments, which replaces the list. DELETE also removes the submissions and the students' copies of the attached scores; use archiveAssignment to withdraw an assignment and keep the work.
  • GET /organizations/users (listOrganizationUsers): sort accepts creationDate and username.
• Scores:
  • POST /scores (createScore): Finale .musx files can now be imported, on a best effort basis. Also documented the scanned music import (PDF and images, requires supportsTasks, spends credits).
• 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.
  • New FAQ section covering credits and billing, limits and performance, recognition quality and languages, and commercial use, privacy, and data.
  • GET /billing/credits/history (listBillingCreditsHistory): New. The credit ledger. Sum only entries whose state is active, and read the balance from getOmrCapabilities.
  • GET /omr/capabilities (getOmrCapabilities): Added acceptedExtensions.
  • OmrJobFileUpload and OmrJobInputFile: Removed mimeType.

• 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.
  • 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.
  • 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. 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 points at listEduLibraries for the library ids you can pass, rather than listing them.
• Errors:
  • FlatErrorResponse: Added providerMessage, a localized message from an upstream provider (for example Google Classroom) when a request fails on their side.

• 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. 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 and the @flat/instruments package for the possible group and instrument values.
• Flat for Education:
  • POST /organizations/{organization}/users (createOrganizationUser): Added the accountAdmin role option (UserCreation).

Asynchronous PDF import with OMR (Optical Music Recognition), see the Importing PDFs with OMR guide

• POST /scores: added supportsTasks on file imports. When true and the imported file requires OMR (e.g. a PDF), the API responds 202 Accepted with a Task reference instead of the score.
• New import-omr task type. Clients poll GET /tasks/{task} until state: done, then read the new score id from the task's score field.
• 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).

• 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):

  • 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, Grading Composition Assignments):
    • 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.
    • 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):
    • 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):
    • 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.

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

• Keep rights property optional on ScoreDetails

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