Tags: FlatIO/api-reference
Tags
feat(api): API specification v2.26.0
The assignment resource becomes readable and writable.
`/classes/{class}/assignments/{assignment}` carried a single path-level `x-private`,
hiding `getAssignment`, `updateClassAssignment` and `deleteAssignment` together, while
listing, creating, archiving, copying and the whole submissions surface were already
public. So an integrator could create an assignment and manage every submission on it,
and could not read, update or delete the assignment itself. All three now carry
descriptions written against the controllers: the partial-update semantics of `PUT` and
the exception `attachments` makes to them, and the reach of `DELETE`, which also removes
the submissions, the students' dedicated copies of the attached scores, the class posts
and notifications, and the assignment on Google Classroom or Microsoft Teams when the
class is synchronized.
Also new: `listBillingCreditsHistory` (`GET /billing/credits/history`) with
`CreditTransaction` and `CreditTransactionList`, the credit ledger behind the OMR
imports.
`listOrganizationUsers` accepts `creationDate` and `username` for `sort`, and its schema
no longer carries an `enum` under an `items` that a string parameter has no use for.
`countOrgaUsers` drops a similar stray `items` from its integer response.
`OmrCapabilities` gains `acceptedExtensions`, and the two OMR upload schemas lose the
`mimeType` the server never read. `createScore` documents Finale `.musx` import and the
scanned music path. `LtiConfiguration1p3` is a real union over its three modes, where the
previous shape flattened to the dynamic variant alone and produced clients that rejected
configurations they had legitimately received.
This is the first specification published as OpenAPI 3.1.0. `nullable: true` is now
`type: [<type>, 'null']` across 41 schema nodes. No field changed nullability. The
flattened derivative was regenerated and carries the same 123 operations.
feat(api): API specification v2.25.0
Optical Music Recognition (OMR), Beta API: data retention is now part of the public
specification. GET /omr/capabilities reports retentionDays, and jobs created with
output: musicxml carry a retention object whose expiryDate is fixed at creation.
- DELETE /omr/jobs/{job} (deleteOmrJob): erase a job's files and results on demand
instead of waiting for the deadline. The job keeps the status it finished with,
stays listable, and records retention.expiredDate. Idempotent. Returns 409 for a
job that has not finished (OMR_JOB_IN_PROGRESS) and for one whose result went to
the Library (OMR_JOB_NOT_EXPIRABLE).
- getOmrJobFile and getOmrJobExport: return 409 (OMR_JOB_EXPIRED) once a job's data
has been erased.
- listOmrJobs: new `expired` filter, usable alongside `status`.
- getOmrCapabilities: available without authentication, so a client can
feature-detect before a user connects an account. Adds localesDetails, the
supported recognition languages with their English names. The fields the server
always returns are now declared required; retentionDays stays optional.
Scores:
- getScoreRevisionData: added `abc` export, for ABC notation. Like MIDI, this format
is lossy and does not carry the full engraving of the score.
- ScoreTrack: `score` is now optional.
Flat for Education:
- Assignment and AssignmentUpdate: added freeRecord.
- listEduResources: the `parent` documentation points at listEduLibraries for the
library ids rather than listing them, since which libraries an account can open
depends on the account.
Errors:
- FlatErrorResponse: added providerMessage, a localized message from an upstream
provider when a request fails on their side.
This release also drops content that was never usable: four path items that carried
only shared parameters because every operation on them is internal, and two component
parameters no public operation referenced.
feat(api): API specification v2.24.0
Public OMR API (Beta): new resumable /omr endpoints to import sheet music images and PDFs (job lifecycle: create, upload files, start, poll, review, export MusicXML/MIDI, cancel) plus GET /omr/capabilities. Added the omr OAuth2 scope; importing to the Library (output library) also requires scores.
Scores: POST /scores builder import now references the Instrument IDs reference and the @flat/instruments package for instrument values.
Flat for Education: POST /organizations/{organization}/users adds the accountAdmin role.
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.
PreviousNext