# Flat API - Public OpenAPI Specification # # https://flat.io/developers/docs/api/ # openapi: 3.0.3 info: title: Flat API description: | The Flat API allows you to easily extend the abilities of the [Flat Platform](https://flat.io), with a wide range of use cases including the following: * Creating and importing new music scores using MusicXML, MIDI, Guitar Pro, MuseScore, ABC notation, and many other formats * Browsing, updating, copying, exporting the user's scores (for example in MP3, WAV or MIDI) * Managing educational resources with Flat for Education: creating & updating the organization accounts, the classes, rosters and assignments. The Flat API is built on HTTP. Our API is RESTful It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. The [schema](/swagger.yaml) of this API follows the [OpenAPI Initiative (OAI) specification](https://www.openapis.org/), you can use and work with [compatible Swagger tools](http://swagger.io/open-source-integrations/). This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with [W3C spec](https://www.w3.org/TR/cors/). You can use your favorite HTTP/REST library for your programming language to use Flat's API. This specification and reference is [available on Github](https://github.com/FlatIO/api-reference). Getting Started and learn more: * [API Overview and introduction](https://flat.io/developers/docs/api/) * [Authentication (Personal Access Tokens or OAuth2)](https://flat.io/developers/docs/api/authentication.html) * [SDKs](https://flat.io/developers/docs/api/sdks.html) * [Rate Limits](https://flat.io/developers/docs/api/rate-limits.html) * [Changelog](https://flat.io/developers/docs/api/changelog.html) termsOfService: https://flat.io/legal contact: name: Flat url: https://flat.io/developers/docs/api/ email: developers@flat.io version: 2.23.0 x-logo: url: https://prod.flat-cdn.com/img/logo-flat.svg servers: - url: https://api.flat.io/v2 tags: - name: Account description: | These API endpoints are related to the Flat account you are currently using. When using an OAuth2 access token, you can use [`GET /me`](#operation/getAuthenticatedUser) to get information about the account. x-displayName: Accounts - name: Score description: | Sheet music is the main API object type available for all Flat account. Here is a typical lifecycle for a music score document on Flat: - An end user can **create a music score** or **import a document** using our [web interface](https://flat.io) or a third-party website/app (e.g. Google Drive) using this API (see [`POST /v2/scores`](#operation/createScore). The creation and import of music scores can be done with this single API endpoint. This one currently supports the [MusicXML](http://www.musicxml.com/) (compressed or not) and [MIDI](https://www.midi.org/specifications). - **List scores**: - The **owned scores** can be listed using the [collections API methods](#tag/Collection), especially [`GET /collections/{collection}/scores`](#operation/listCollectionScores). - The scores from a public account can be listed with [`GET /users/{user}/scores`](#operation/getUserScores). - Scores shared with a specific group can be listed with [`GET /groups/{group}/scores`](#operation/getGroupScores). - The metadata of a single score can be retrieved with [`GET /scores/{score}`](#operation/getScore). - Scores on Flat have **one or multiple revisions**: creating a new score will create a first revision. These **revisions can be listed** using [`GET /scores/{score}/revisions`](#operation/getScoreRevisions) and a specific **revision data can be downloaded** with [`GET /scores/{score}/revisions/{revision}/{format}`](#operation/getScoreRevisionData). New revisions can be created using our [sheet music editor](https://flat.io) or using [`POST /scores/{score}/revisions`](#operation/createScoreRevision) (this endpoint has similar parameters than during the score creation). The last revision of a document may not directly reflect the really last version of a music score: recent modifications can be made offline or not yet consolidated into a new revision. In average, a new revision is created every 100 modifications made with our editor. - Scores can be **shared publicly** by changing the privacy option with [`POST /scores/{score}`](#operation/editScore), or **individually shared** using the different collaborators API endpoints (see [`POST /scores/{score}/collaborators`](#operation/addScoreCollaborator)). x-displayName: Music scores - name: Collection description: | Collections let you organize your content in a Flat account. They work like a regular _folder_ with some specificities: - Our design goal here is to create a system similar to a _book_ or a _playlist of songs_. - Collections can't have children collections (except the `trash` that is a special collection). - Any score can be added to one or multiple collections. For example, you can have a single private score in two or more collections, or add any public or shared scores to one of your collections. All the collections don't have the same capabilities. Capabilities depend on the `type` of collection and the `rights` you have on a collection. They are available when [listing the collection](#operation/listCollections) or [retrieving the collection details](#operation/getCollection). By default, when using an OAuth2 access token or a personal token, all the new scores will be added to a dedicated app collection created in the user account. This collection has an alias `app`. For example, you can use `GET /v2/collections/app/scores` to list all the scores created by your app. At this time, only `private` privacy mode is widely available. Privacy modes `public`, `organizationPublic` and `privateLink`, and 1:1 sharing will be available in an upcoming update later this year. x-displayName: Collections of music scores - name: User x-displayName: Users profiles description: API methods related to the Flat Community user profiles and Flat for Education profiles - name: Organization x-displayName: Flat for Education Organizations description: Flat for Education Organizations - name: Class x-displayName: Flat for Education Classes description: Flat for Education Classes - name: EduResources x-displayName: Flat for Education Resources description: | Resource libraries in Flat for Education. - name: Group x-displayName: Flat for Education Groups description: Flat for Education Groups - name: Task x-displayName: Asynchronous tasks description: Scheduled and asynchronous tasks paths: /classes: get: tags: - Class summary: List the classes available for the current user operationId: listClasses parameters: - name: state in: query description: Filter the classes by state schema: type: string default: active enum: - active - inactive - archived responses: '200': description: The list of classes content: application/json: schema: type: array items: $ref: '#/components/schemas/ClassDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.classes.readonly post: tags: - Class summary: Create a new class description: | Classrooms on Flat allow you to create activities with assignments and post content to a specific group. When creating a class, Flat automatically creates two groups: one for the teachers of the course, one for the students. The creator of this class is automatically added to the teachers group. If the classsroom is synchronized with another application like Google Classroom, some of the meta information will automatically be updated. You can add users to this class using `PUT /classes/{class}/users/{user}`, they will automatically added to the group based on their role on Flat. Users can also enroll themselves to this class using `POST /classes/enroll/{enrollmentCode}` and the `enrollmentCode` returned in the `ClassDetails` response. operationId: createClass requestBody: content: application/json: schema: $ref: '#/components/schemas/ClassCreation' required: true responses: '200': description: The new class details content: application/json: schema: $ref: '#/components/schemas/ClassDetails' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes x-codegen-request-body-name: body /classes/{class}: parameters: - $ref: '#/components/parameters/class' get: tags: - Class summary: Get the details of a single class operationId: getClass responses: '200': description: The new class details content: application/json: schema: $ref: '#/components/schemas/ClassDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.classes.readonly put: tags: - Class summary: Update the class description: | Update the meta information of the class operationId: updateClass requestBody: description: Details of the Class content: application/json: schema: $ref: '#/components/schemas/ClassUpdate' required: true responses: '200': description: The new class details content: application/json: schema: $ref: '#/components/schemas/ClassDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes x-codegen-request-body-name: body /classes/{class}/archive: parameters: - $ref: '#/components/parameters/class' post: tags: - Class summary: Archive the class description: | Mark the class as `archived`. When this course is synchronized with another app, like Google Classroom, this state will be automatically be updated. operationId: archiveClass responses: '200': description: The class details content: application/json: schema: $ref: '#/components/schemas/ClassDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes delete: tags: - Class summary: Unarchive the class description: | Mark the class as `active`. When this course is synchronized with another app, like Google Classroom, this state will be automatically be updated. operationId: unarchiveClass responses: '200': description: The class details content: application/json: schema: $ref: '#/components/schemas/ClassDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes /classes/{class}/activate: parameters: - $ref: '#/components/parameters/class' post: tags: - Class summary: Activate the class description: | Mark the class as `active`. This is mainly used for classes synchronized from Clever that are initially with an `inactive` state and hidden in the UI. operationId: activateClass responses: '200': description: The class details content: application/json: schema: $ref: '#/components/schemas/ClassDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes /classes/{class}/users/{user}: parameters: - $ref: '#/components/parameters/class' - name: user in: path description: Unique identifier of the user required: true schema: type: string put: tags: - Class summary: Add a user to the class description: | This method can be used by a teacher of the class to enroll another Flat user into the class. Only users that are part of your Organization can be enrolled in a class of this same Organization. When enrolling a user in the class, Flat will automatically add this user to the corresponding Class group, based on this role in the Organization. operationId: addClassUser responses: '204': description: The user has been added to the class default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes delete: tags: - Class summary: Remove a user from the class description: | This method can be used by a teacher to remove a user from the class, or by a student to leave the classroom. Warning: Removing a user from the class will remove the associated resources, including the submissions and feedback related to these submissions. operationId: deleteClassUser responses: '204': description: The user has been removed from the class default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes /classes/{class}/students/{user}/submissions: parameters: - $ref: '#/components/parameters/class' - name: user in: path description: Unique identifier of the user required: true schema: type: string get: tags: - Class summary: List the submissions for a student description: | Use this method as a teacher to list all the assignment submissions sent by a student of the class operationId: listClassStudentSubmissions responses: '200': description: The list of submissions content: application/json: schema: type: array items: $ref: '#/components/schemas/AssignmentSubmission' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.classes.readonly - edu.assignments - edu.assignments.readonly /classes/{class}/assignments: parameters: - $ref: '#/components/parameters/class' get: tags: - Class summary: Assignments listing operationId: listAssignments parameters: [] responses: '200': description: List of assignments for the class content: application/json: schema: type: array items: $ref: '#/components/schemas/ClassAssignment' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.classes.readonly - edu.assignments - edu.assignments.readonly post: tags: - Class summary: Assignment creation description: | Use this method as a teacher to create and post a new assignment to a class. If the class is synchronized with Google Classroom, the assignment will be automatically posted to your Classroom course. operationId: createClassAssignment requestBody: content: application/json: schema: $ref: '#/components/schemas/ClassAssignmentUpdate' required: true responses: '200': description: The assignment has been created content: application/json: schema: $ref: '#/components/schemas/Assignment' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.assignments x-codegen-request-body-name: body /classes/{class}/assignments/{assignment}/copy: parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' post: tags: - Class summary: Copy an assignment description: | Copy an assignment to a specified class or the resource library For class assignments: - If the original assignment has a due date in the past, this new assignment will be created without a due date. - If the class is synchronized with an external app (e.g. Google Classroom), the copied assignment will also be posted on the external app. operationId: copyAssignment requestBody: content: application/json: schema: $ref: '#/components/schemas/AssignmentCopy' required: true responses: '200': description: The new created assignment content: application/json: schema: $ref: '#/components/schemas/AssignmentCopyResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.assignments x-codegen-request-body-name: body /classes/{class}/assignments/{assignment}/archive: parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' post: tags: - Class summary: Archive the assignment description: | Archive the assignment operationId: archiveAssignment responses: '200': description: The assignment details content: application/json: schema: $ref: '#/components/schemas/Assignment' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.assignments delete: tags: - Class summary: Unarchive the assignment. description: | Mark the assignment as `active`. operationId: unarchiveAssignment responses: '200': description: The assignment details content: application/json: schema: $ref: '#/components/schemas/Assignment' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.assignments /classes/{class}/assignments/{assignment}/submissions: parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' get: tags: - Class summary: List the students' submissions operationId: getSubmissions responses: '200': description: The submissions content: application/json: schema: type: array items: $ref: '#/components/schemas/AssignmentSubmission' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.classes.readonly - edu.assignments - edu.assignments.readonly put: tags: - Class summary: Create or edit a submission description: | Use this method as a student to create, update and submit a submission related to an assignment. Students can only set `attachments` and `submit`. Teachers can use `PUT /classes/{class}/assignments/{assignment}/submissions/{submission}` to update a submission by id. operationId: createSubmission requestBody: content: application/json: schema: $ref: '#/components/schemas/AssignmentSubmissionUpdate' required: true responses: '200': description: The submission content: application/json: schema: $ref: '#/components/schemas/AssignmentSubmission' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.assignments x-codegen-request-body-name: body /classes/{class}/assignments/{assignment}/submissions/csv: parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' get: tags: - Class summary: CSV Grades exports description: Export list of submissions grades to a CSV file operationId: exportSubmissionsReviewsAsCsv responses: '200': description: List of submissions content: text/csv: schema: type: string format: binary default: description: Error content: text/csv: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.classes.readonly - edu.assignments - edu.assignments.readonly /classes/{class}/assignments/{assignment}/submissions/excel: parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' get: tags: - Class summary: Excel Grades exports description: Export list of submissions grades to an Excel file operationId: exportSubmissionsReviewsAsExcel responses: '200': description: List of submissions content: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: type: string format: binary default: description: Error content: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.classes.readonly - edu.assignments - edu.assignments.readonly /classes/{class}/assignments/{assignment}/submissions/{submission}: parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' - $ref: '#/components/parameters/submission' get: tags: - Class summary: Get a student submission operationId: getSubmission responses: '200': description: A submission content: application/json: schema: $ref: '#/components/schemas/AssignmentSubmission' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.classes.readonly - edu.assignments - edu.assignments.readonly put: tags: - Class summary: Edit a submission description: | Use this method as a teacher to update the different submission and give feedback. Teachers can only set `return`, `draftGrade` and `grade` operationId: editSubmission requestBody: content: application/json: schema: $ref: '#/components/schemas/AssignmentSubmissionUpdate' required: true responses: '200': description: The submission content: application/json: schema: $ref: '#/components/schemas/AssignmentSubmission' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.assignments x-codegen-request-body-name: body delete: tags: - Class summary: Reset a submission description: | Use this method as a teacher to reset a submission and allow student to start over the assignment operationId: deleteSubmission parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' - $ref: '#/components/parameters/submission' responses: '200': description: The submission object once reset content: application/json: schema: $ref: '#/components/schemas/AssignmentSubmission' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.assignments x-codegen-request-body-name: body /classes/{class}/assignments/{assignment}/submissions/{submission}/history: parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' - $ref: '#/components/parameters/submission' get: tags: - Class operationId: getSubmissionHistory summary: Get the history of the submission description: | For teachers only. Returns a detailed history of the submission. This currently includes state and grade histories. security: - OAuth2: - edu.assignments - edu.assignments.readonly responses: '200': description: The history of the submission content: application/json: schema: type: array items: $ref: '#/components/schemas/AssignmentSubmissionHistory' '403': description: Not granted to access to this submission content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Submission not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' /classes/{class}/assignments/{assignment}/submissions/{submission}/comments: parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' - $ref: '#/components/parameters/submission' get: tags: - Class operationId: getSubmissionComments summary: List the feedback comments of a submission security: - OAuth2: - edu.assignments - edu.assignments.readonly responses: '200': description: The comments of the score content: application/json: schema: type: array items: $ref: '#/components/schemas/AssignmentSubmissionComment' '403': description: Not granted to access to this submission content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Submission not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' post: tags: - Class operationId: postSubmissionComment summary: Add a feedback comment to a submission security: - OAuth2: - edu.assignments requestBody: content: application/json: schema: $ref: '#/components/schemas/AssignmentSubmissionCommentCreation' required: true responses: '200': description: The comment content: application/json: schema: $ref: '#/components/schemas/AssignmentSubmissionComment' '403': description: Not granted to access to this submission content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Submission not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' /classes/{class}/assignments/{assignment}/submissions/{submission}/comments/{comment}: parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' - $ref: '#/components/parameters/submission' - $ref: '#/components/parameters/comment' put: tags: - Class operationId: updateSubmissionComment summary: Update a feedback comment to a submission security: - OAuth2: - edu.assignments requestBody: content: application/json: schema: $ref: '#/components/schemas/AssignmentSubmissionCommentCreation' required: true responses: '200': description: The comment content: application/json: schema: $ref: '#/components/schemas/AssignmentSubmissionComment' '403': description: Not granted to access to this submission content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Submission not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' delete: tags: - Class operationId: deleteSubmissionComment summary: Delete a feedback comment to a submission security: - OAuth2: - edu.assignments responses: '204': description: The comment has been deleted default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' /classes/{class}/assignments/{assignment}/submissions/{submission}/performanceAssessments: parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' - $ref: '#/components/parameters/submission' /classes/{class}/testStudent: parameters: - $ref: '#/components/parameters/class' post: tags: - Class summary: Create a test student account description: | Test students account can be created by teachers an admin and be used to experiment the assignments. - They are automatically added to the class. - They can be reset using this API endpoint (a new account will be created and the previous one scheduled for deletion). - These accounts don't use a user license. operationId: createTestStudentAccount parameters: - name: reset in: query description: | If true, the testing account will be re-created. required: false schema: type: boolean responses: '200': description: Test account created content: application/json: schema: $ref: '#/components/schemas/UserDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.classes /classes/enroll/{enrollmentCode}: parameters: - name: enrollmentCode in: path description: | The enrollment code, available to the teacher in `ClassDetails` required: true schema: type: string post: tags: - Class summary: Join a class description: | Use this method to join a class using an enrollment code given one of the teacher of this class. This code is also available in the `ClassDetails` returned to the teachers when creating the class or listing / fetching a specific class. Flat will automatically add the user to the corresponding class group based on this role in the organization. operationId: enrollClass responses: '200': description: The new class details content: application/json: schema: $ref: '#/components/schemas/ClassDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes /collections: get: tags: - Collection summary: List the collections description: | Use this method to list the user's collections. If no sort option is provided, the collections are sorted by `creationDate` `desc`. By default (`parent=user`), this returns all user account collections with virtual collections on the first page. To fetch your app collection details, you can use `GET /v2/collections/app`. operationId: listCollections parameters: - name: parent in: query description: | List the collections contained in this `parent` collection. When set to `user` (default), returns the user's own collections as well as collections shared with the user. Using `root` or `sharedWithMe` is **deprecated** and will be treated as `user`. schema: type: string default: user - name: sort in: query description: Sort schema: type: string enum: - creationDate - modificationDate - title - name: direction in: query description: Sort direction schema: type: string enum: - asc - desc - name: limit in: query description: This is the maximum number of objects that may be returned schema: maximum: 100 minimum: 1 type: integer default: 25 - name: next in: query description: | An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the `Link` header when requesting the API. These URLs will contain a `next` and `previous` cursor based on the available data. schema: type: string - name: previous in: query description: | An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the `Link` header when requesting the API. These URLs will contain a `next` and `previous` cursor based on the available data. schema: type: string responses: '200': description: List of collections content: application/json: schema: type: array items: $ref: '#/components/schemas/Collection' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - collections - collections.readonly post: tags: - Collection summary: Create a new collection description: | This method will create a new collection in your account. operationId: createCollection requestBody: content: application/json: schema: $ref: '#/components/schemas/CollectionCreation' required: true responses: '200': description: Collection created content: application/json: schema: $ref: '#/components/schemas/Collection' '400': description: Bad collection creation request content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - collections x-codegen-request-body-name: body /collections/{collection}: parameters: - name: collection in: path description: | Unique identifier of the collection. The following collection aliases are supported: - `root`: **Deprecated.** The root collection of the account - `app`: Alias for the current app collection - `trash`: Automatically contains resources that have been deleted The following virtual collections are supported: - `allScores`: All the scores contained in the user account - `collaborations`: All shared scores by the user or someone else - `likes`: Liked scores required: true schema: type: string get: tags: - Collection summary: Get collection details operationId: getCollection parameters: - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string responses: '200': description: Collection details content: application/json: schema: $ref: '#/components/schemas/Collection' '403': description: Not granted to access to this collection content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Collection not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - collections - collections.readonly put: tags: - Collection summary: Update a collection's metadata operationId: editCollection requestBody: content: application/json: schema: $ref: '#/components/schemas/CollectionModification' required: true responses: '200': description: Collection details content: application/json: schema: $ref: '#/components/schemas/Collection' '403': description: Not granted to access to this collection content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Collection not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - collections x-codegen-request-body-name: body delete: tags: - Collection summary: Delete the collection description: | This method will schedule the deletion of the collection. Until deleted, the collection will be available in the `trash`. operationId: deleteCollection parameters: [] responses: '204': description: Collection deleted '403': description: Not granted to access to this collection content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Collection not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - collections /collections/{collection}/untrash: parameters: - name: collection in: path description: Unique identifier of the collection. required: true schema: type: string post: tags: - Collection summary: Untrash a collection deprecated: true description: | **DEPRECATED** This method will restore the collection by removing it from the `trash` and add it back to the `root` collection. operationId: untrashCollection responses: '400': description: Bad request - Operation no longer supported content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - collections /collections/{collection}/scores: parameters: - name: collection in: path description: | Unique identifier of the collection. The following collection aliases are supported: - `root`: **Deprecated.** The root collection of the account - `app`: Alias for the current app collection - `trash`: Automatically contains resources that have been deleted The following virtual collections are supported: - `allScores`: All the scores contained in the user account - `collaborations`: All shared scores by the user or someone else - `likes`: Liked scores required: true schema: type: string - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string get: tags: - Collection summary: List the scores contained in a collection description: | Use this method to list the scores contained in a collection. If no sort option is provided, the scores are sorted by `modificationDate` `desc`. For example, to list the scores contained in your app collection, you can use `GET /v2/collections/app/scores`. operationId: listCollectionScores parameters: - name: sort in: query description: Sort schema: type: string enum: - creationDate - modificationDate - title - name: direction in: query description: Sort direction schema: type: string enum: - asc - desc - name: limit in: query description: This is the maximum number of objects that may be returned schema: maximum: 100 minimum: 1 type: integer default: 25 - name: next in: query description: | An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the `Link` header when requesting the API. These URLs will contain a `next` and `previous` cursor based on the available data. schema: type: string - name: previous in: query description: | An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the `Link` header when requesting the API. These URLs will contain a `next` and `previous` cursor based on the available data. schema: type: string responses: '200': description: List of scores content: application/json: schema: type: array items: $ref: '#/components/schemas/ScoreDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - collections /collections/{collection}/scores/{score}: parameters: - name: collection in: path description: | Unique identifier of the collection. The following collection aliases are supported: - `root`: **Deprecated.** The root collection of the account - `app`: Alias for the current app collection - `trash`: Automatically contains resources that have been deleted required: true schema: type: string - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string put: tags: - Collection summary: Add a score to the collection description: | This operation will add a score to a collection. The default behavior will make the score available across multiple collections. You must have the capability `canAddScores` on the provided `collection` to perform the action. operationId: addScoreToCollection responses: '200': description: Score details content: application/json: schema: $ref: '#/components/schemas/ScoreDetails' '403': description: Not granted to access to this collection or score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Collection or score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - collections - collections.add_scores requestBody: content: application/x-www-form-urlencoded: schema: type: object delete: tags: - Collection summary: Delete a score from the collection description: | This method will delete a score from the collection. Unlike [`DELETE /scores/{score}`](#operation/deleteScore), this score will not remove the score from your account, but only from the collection. This can be used to *move* a score from one collection to another, or simply remove a score from one collection when this one is contained in multiple collections. operationId: deleteScoreFromCollection responses: '204': description: Score removed from the collection '403': description: Not granted to access to this collection content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Collection not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - collections requestBody: content: application/x-www-form-urlencoded: schema: type: object parameters: - $ref: '#/components/parameters/eventProperties' /eduResources: get: tags: - EduResources operationId: listEduResources summary: List education resources in a library or folder parameters: - name: parent in: query description: | List the resources contained in this `parent` library or folder schema: type: string default: root - name: withoutSubfoldersResources in: query description: | For the `parent` = `organization`, do not include resources from subfolders. By default in the Resource Library UI, we include resources from subfolders, but for example in a picker like LTI, we don't want to include them. schema: type: boolean - name: type in: query description: | Filter the returned resources by type schema: type: string enum: - assignment - folder - name: subjects in: query description: | Filter the returned resources by subjects schema: type: array items: $ref: '#/components/schemas/TeachingTheme' - name: assignmentTypes in: query description: | Filter the returned resources by assignment types schema: type: array items: $ref: '#/components/schemas/AssignmentType' - name: grades in: query description: | Filter the returned resources by grades schema: type: array items: $ref: '#/components/schemas/Grade' - name: sort in: query description: Sort schema: type: string enum: - creationDate - updateDate - title default: creationDate - $ref: '#/components/parameters/sortDirection' - name: limit in: query description: This is the maximum number of resources that may be returned schema: maximum: 100 minimum: 1 type: integer default: 25 - $ref: '#/components/parameters/next' - $ref: '#/components/parameters/previous' responses: '200': description: List of resources content: application/json: schema: type: array items: $ref: '#/components/schemas/EduResource' headers: X-Total-Assignments-Count: description: Total number of assignments schema: type: integer X-Total-Folders-Count: description: Total number of folders schema: type: integer default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.resources.readonly - edu.assignments - edu.assignments.readonly post: tags: - EduResources operationId: createEduResource summary: Create a new education resource requestBody: content: application/json: schema: $ref: '#/components/schemas/EduResourceCreation' required: true responses: '200': description: Fetched resource content: application/json: schema: $ref: '#/components/schemas/EduResource' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.assignments /eduResources/libraries: get: tags: - EduResources operationId: listEduLibraries summary: List the education libraries responses: '200': description: Fetched resource content: application/json: schema: type: array description: List of libraries to display items: $ref: '#/components/schemas/EduLibrary' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.resources.readonly - edu.assignments - edu.assignments.readonly /eduResources/{resource}: parameters: - name: resource in: path required: true description: Unique identifier of the resource schema: type: string get: tags: - EduResources operationId: getEduResource summary: Get an education resource parameters: [] responses: '200': description: Fetched resource content: application/json: schema: $ref: '#/components/schemas/EduResource' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.resources.readonly - edu.assignments - edu.assignments.readonly put: tags: - EduResources operationId: updateEduResource summary: Update an education resource metadata description: | Update any resources metadata (e.g. title). Use this method to rename education resources folders or assignments. requestBody: content: application/json: schema: $ref: '#/components/schemas/EduResourceUpdate' required: true responses: '200': description: Fetched resource content: application/json: schema: $ref: '#/components/schemas/EduResource' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.assignments delete: tags: - EduResources operationId: deleteEduResource summary: Delete an education resource responses: '204': description: Resource deleted default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.assignments /eduResources/{resource}/move: parameters: - name: resource in: path required: true description: Unique identifier of the resource schema: type: string post: tags: - EduResources operationId: moveEduResource summary: Move an education resource requestBody: content: application/json: schema: $ref: '#/components/schemas/EduResourceMove' required: true responses: '200': description: Fetched resource content: application/json: schema: $ref: '#/components/schemas/EduResource' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.assignments /eduResources/{resource}/copy: parameters: - name: resource in: path required: true description: Unique identifier of the resource schema: type: string post: tags: - EduResources operationId: copyEduResource summary: Copy an education resource to a Resource Library requestBody: content: application/json: schema: $ref: '#/components/schemas/EduResourceCopy' required: true responses: '200': description: Fetched resource content: application/json: schema: $ref: '#/components/schemas/EduResource' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.assignments /eduResources/{resource}/copyToDemoClass: parameters: - name: resource in: path required: true description: Unique identifier of the resource schema: type: string post: tags: - EduResources operationId: copyEduResourceToDemoClass summary: Copy an education assignment to a teacher demo class description: | Once a resource library can be published to a class (`Assignment.capabilities.canPublishInClass = true`), this endpoint can be used for the feature "View as student". It will ensure the teacher has a demo class, then copy the assignment to the demo class. You can then use `POST /classes/{class}/testStudent` to create a testing student account in the demo class. responses: '200': description: Assignment copied to the demo class content: application/json: schema: $ref: '#/components/schemas/ClassAssignment' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.assignments /eduResources/{resource}/useInClass: parameters: - name: resource in: path required: true description: Unique identifier of the resource schema: type: string post: tags: - EduResources operationId: useEduResourceInClass summary: Use an education resource in a class description: | This endpoint will copy a resource and the underlying resources. The assignment will be created as a draft that can be completed with other options before publishing (e.g. due date, publication date for scheduling, etc.). requestBody: content: application/json: schema: $ref: '#/components/schemas/EduResourceUseInClass' required: true responses: '200': description: Assignment copied to the chosen class content: application/json: schema: $ref: '#/components/schemas/ClassAssignment' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.assignments /eduResources/{resource}/createLtiLink: parameters: - name: resource in: path required: true description: Unique identifier of the resource schema: type: string post: tags: - EduResources operationId: createEduResourceLtiLink summary: Create an LTI link for an education resource description: | This endpoint will return an LTI link that can be used to launch Flat for Education. The link, in a context from a class, will ensure the assignment has been copied in the class. responses: '200': description: Created LTI Link content: application/json: schema: $ref: '#/components/schemas/EduResourceLtiLink' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.assignments /eduResources/{resource}/assignment: parameters: - name: resource in: path required: true description: Unique identifier of the resource schema: type: string put: tags: - EduResources operationId: updateEduResourceAssignment summary: Update an education resource assignment requestBody: content: application/json: schema: $ref: '#/components/schemas/AssignmentUpdate' required: true responses: '200': description: Fetched resource content: application/json: schema: $ref: '#/components/schemas/Assignment' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.resources - edu.assignments /groups: get: operationId: listGroups tags: - Group summary: List groups description: | List all groups of a given type, filtered by either a classroom or an assignment. security: - OAuth2: - edu.classes - edu.classes.readonly - edu.admin - edu.admin.readonly - edu.admin.users.readonly parameters: - name: type in: query required: true schema: type: string enum: - classStudentsSubGroup - assignmentStudentsSubGroup - name: classroom in: query description: Classroom ID to filter by schema: type: string - name: assignment in: query description: Assignment ID to filter by schema: type: string responses: '200': description: List of groups content: application/json: schema: type: array items: $ref: '#/components/schemas/GroupDetails' '400': description: Bad Request - Invalid type or missing required parameters content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Not Found - Classroom or assignment not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' post: operationId: createGroup tags: - Group summary: Create a new group description: | Create a group of the given type, tied to a classroom, optionally with initial members. security: - OAuth2: - edu.classes - edu.admin - edu.admin.users requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupCreation' responses: '200': description: The new group content: application/json: schema: $ref: '#/components/schemas/GroupDetails' '400': description: Bad Request - Invalid type or missing required parameters content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '409': description: Conflict - Group name already exists content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' /groups/{group}: parameters: - $ref: '#/components/parameters/group' get: tags: - Group summary: Get group information operationId: getGroupDetails responses: '200': description: The group details content: application/json: schema: $ref: '#/components/schemas/GroupDetails' '404': description: Not Found - Group not found or insufficient permissions content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users - edu.admin.users.readonly - edu.classes - edu.classes.readonly put: operationId: renameGroup tags: - Group summary: Rename a group description: Rename a sub-group. Only available for class student groups. requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: New name for the group required: - name responses: '200': description: Updated group content: application/json: schema: $ref: '#/components/schemas/GroupDetails' '400': description: Bad Request - Invalid group ID or missing name content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Not Found - Group not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '409': description: Conflict - Group name already exists content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.admin - edu.admin.users delete: operationId: deleteGroup tags: - Group summary: Delete a group description: Delete a group. Only available to teachers of the classroom. responses: '204': description: Group deleted '403': description: Forbidden - Insufficient permissions or invalid group type content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Not Found - Group not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.admin - edu.admin.users /groups/{group}/users: parameters: - $ref: '#/components/parameters/group' get: tags: - Group summary: List group's users operationId: listGroupUsers parameters: - name: source in: query description: | Filter the users by their source schema: type: string enum: - googleClassroom - microsoftGraph - clever responses: '200': description: The list of users member of the group content: application/json: schema: type: array items: $ref: '#/components/schemas/UserPublic' '404': description: Not Found - Group not found or insufficient permissions content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users - edu.admin.users.readonly - edu.classes - edu.classes.readonly post: operationId: addGroupUser tags: - Group summary: Add a student to a group description: Add a student to the specified group (must be in the same class) security: - OAuth2: - edu.classes - edu.admin - edu.admin.users requestBody: required: true content: application/json: schema: type: object properties: user: type: string description: ID of the student to add required: - user responses: '200': description: Membership created content: application/json: schema: type: object properties: user: type: string description: User ID that was added '400': description: Bad Request - Invalid user ID or user not enrolled in class content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Forbidden - Insufficient permissions or invalid group type content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Not Found - Group not found or user not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' /groups/{group}/users/{user}: parameters: - $ref: '#/components/parameters/group' - name: user in: path required: true description: User ID schema: type: string delete: operationId: removeGroupUser tags: - Group summary: Remove a student from a class group description: Remove a student from a class group responses: '204': description: Membership removed '403': description: Forbidden - Insufficient permissions or invalid group type content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Not Found - Group not found or user not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.classes - edu.admin - edu.admin.users /groups/{group}/scores: parameters: - $ref: '#/components/parameters/group' get: tags: - Group - Score summary: List group's scores description: | Get the list of scores shared with a group. operationId: getGroupScores parameters: - name: parent in: query description: Filter the score forked from the score id `parent` schema: type: string responses: '200': description: The group's scores content: application/json: schema: type: array items: $ref: '#/components/schemas/ScoreDetails' '404': description: Not Found - Group not found or user not member of group content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores - scores.readonly /me: get: tags: - Account summary: Get current user account description: | Get details about the current authenticated User. operationId: getAuthenticatedUser parameters: - name: onlyId in: query description: Only return the user id schema: type: boolean default: false responses: '200': description: Current user details content: application/json: schema: $ref: '#/components/schemas/UserDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - account.public_profile - account.education_profile x-codeSamples: - lang: Python source: | from pprint import pprint import os import flat_api from flat_api.rest import ApiException configuration = flat_api.Configuration() configuration.access_token = os.environ['FLAT_ACCESS_TOKEN'] flat_api_client = flat_api.ApiClient(configuration) try: pprint(flat_api.AccountApi(flat_api_client).get_authenticated_user()) except ApiException as e: print(e) - lang: PHP source: | setAccessToken($_ENV['FLAT_ACCESS_TOKEN']); $api = new Flat\APIClient\Api\AccountApi(); try { $result = $api->getAuthenticatedUser(); print_r($result); } catch (Exception $e) { echo 'Exception when calling AccountApi->getAuthenticatedUser: ', $e->getMessage(), PHP_EOL; } /organizations/users: get: tags: - Organization summary: List the organization users operationId: listOrganizationUsers parameters: - name: sort in: query description: The order to sort the user list schema: type: string items: type: string enum: - firstname - lastname - lastActivityDate - licenseExpirationDate - $ref: '#/components/parameters/sortDirection' - $ref: '#/components/parameters/next' - $ref: '#/components/parameters/previous' - $ref: '#/components/parameters/role' - $ref: '#/components/parameters/searchInputQuery' - $ref: '#/components/parameters/groupIds' - $ref: '#/components/parameters/noActiveLicense' - $ref: '#/components/parameters/testAccounts' - name: licenseExpirationDate in: query description: Filter users by license expiration date or `active` / `notActive` schema: type: array items: type: string - name: onlyIds in: query description: Return only user ids schema: type: boolean - name: limit in: query description: This is the maximum number of objects that may be returned schema: maximum: 1000 minimum: 1 type: integer default: 25 responses: '200': description: List of users content: application/json: schema: type: array items: $ref: '#/components/schemas/UserDetailsAdmin' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users - edu.admin.users.readonly post: tags: - Organization summary: Create a new user account operationId: createOrganizationUser requestBody: content: application/json: schema: $ref: '#/components/schemas/UserCreation' required: true responses: '200': description: New user created content: application/json: schema: $ref: '#/components/schemas/UserDetailsAdmin' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users x-codegen-request-body-name: body /organizations/users/count: get: tags: - Organization summary: Count the organization users using the provided filters operationId: countOrgaUsers parameters: - $ref: '#/components/parameters/role' - $ref: '#/components/parameters/searchInputQuery' - $ref: '#/components/parameters/groupIds' - $ref: '#/components/parameters/noActiveLicense' - $ref: '#/components/parameters/testAccounts' responses: '200': description: Number of users content: application/json: schema: type: integer items: $ref: '#/components/schemas/UserDetailsAdmin' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users - edu.admin.users.readonly /organizations/users/{user}: parameters: - name: user in: path description: | Unique identifier of the Flat account required: true schema: type: string put: tags: - Organization summary: Update account information operationId: updateOrganizationUser requestBody: content: application/json: schema: $ref: '#/components/schemas/UserAdminUpdate' required: true responses: '200': description: User updated content: application/json: schema: $ref: '#/components/schemas/UserDetailsAdmin' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users x-codegen-request-body-name: body delete: tags: - Organization summary: Remove an account from Flat description: | This operation removes an account from Flat and its data, including: * The music scores created by this user (documents, history, comments, collaboration information) * Education related data (assignments and classroom information) operationId: removeOrganizationUser parameters: - name: convertToIndividual in: query description: | If `true`, the account will be only removed from the organization and converted into an individual account on our public website, https://flat.io. This operation will remove the education-related data from the account. Before realizing this operation, you need to be sure that the user is at least 13 years old and that this one has read and agreed to the Individual Terms of Services of Flat available on https://flat.io/legal. schema: type: boolean responses: '204': description: User deleted default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users /organizations/users/{user}/signinLink: parameters: - name: user in: path description: | Unique identifier of the Flat account required: true schema: type: string post: tags: - Organization summary: Create a sign in link for an organization user operationId: createOrganizationUserSigninLink requestBody: content: application/json: schema: $ref: '#/components/schemas/UserSigninLinkCreation' required: true responses: '200': description: Sign in link content: application/json: schema: $ref: '#/components/schemas/UserSigninLink' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users /organizations/users/{user}/accessToken: parameters: - name: user in: path description: | Unique identifier of the Flat account required: true schema: type: string post: tags: - Organization operationId: createOrganizationUserAccessToken summary: Create a delegated API access token for an organization user description: | This operation will create an API access token for a chosen organization user. This token will be valid for a limited time and can be used to access the API as the organization user. requestBody: content: application/json: schema: $ref: '#/components/schemas/OrganizationUserAccessTokenCreation' required: true responses: '200': description: Created API access token content: application/json: schema: $ref: '#/components/schemas/ApiAccessToken' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users /organizations/invitations: get: tags: - Organization summary: List the organization invitations operationId: listOrganizationInvitations parameters: - name: role in: query description: Filter users by role schema: type: string enum: - user - teacher - admin - name: limit in: query description: This is the maximum number of objects that may be returned schema: maximum: 1000 minimum: 1 type: integer default: 50 - name: next in: query description: | An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the `Link` header when requesting the API. These URLs will contain a `next` and `previous` cursor based on the available data. schema: type: string - name: previous in: query description: | An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the `Link` header when requesting the API. These URLs will contain a `next` and `previous` cursor based on the available data. schema: type: string responses: '200': description: List of invitations content: application/json: schema: type: array items: $ref: '#/components/schemas/OrganizationInvitation' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users - edu.admin.users.readonly post: tags: - Organization summary: Create a new invitation to join the organization description: | This method creates and sends invitation for teachers and admins. Invitations can only be used by new Flat users or users who are not part of the organization yet. If the email of the user is already associated to a user of your organization, the API will simply update the role of the existing user and won't send an invitation. In this case, the property `usedBy` will be directly filled with the uniquer identifier of the corresponding user. operationId: createOrganizationInvitation requestBody: content: application/json: schema: $ref: '#/components/schemas/OrganizationInvitationCreation' required: true responses: '200': description: New invitation created content: application/json: schema: $ref: '#/components/schemas/OrganizationInvitation' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users x-codegen-request-body-name: body /organizations/invitations/{invitation}: parameters: - name: invitation in: path description: Unique identifier of the invitation required: true schema: type: string delete: tags: - Organization summary: Remove an organization invitation operationId: removeOrganizationInvitation responses: '204': description: The invitation has been removed default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.users /organizations/lti/credentials: get: tags: - Organization summary: List LTI 1.x credentials operationId: listLtiCredentials deprecated: true description: | DEPRECATED. Use the unified endpoints under `/organizations/lti/configurations`. Note: Teachers may be restricted by the organization privacy setting `lti1p1AllowTeachersCredentials`. responses: '200': description: The list of LTI Credentials content: application/json: schema: type: array items: $ref: '#/components/schemas/LtiCredentials' '403': description: Not admin of an organization content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.lti - edu.admin.lti.readonly post: tags: - Organization summary: Create a new couple of LTI 1.x credentials description: | DEPRECATED. Use the unified endpoints under `/organizations/lti/configurations`. Note: Teachers may be restricted by the organization privacy setting `lti1p1AllowTeachersCredentials`. Flat for Education is a Certified LTI Provider. You can use these API methods to automate the creation of LTI credentials. You can read more about our LTI implementation, supported components and LTI Endpoints in our [Developer Documentation](https://flat.io/developers/docs/lti/). operationId: createLtiCredentials deprecated: true requestBody: content: application/json: schema: $ref: '#/components/schemas/LtiCredentialsCreation' required: true responses: '200': description: The LTI Credentials content: application/json: schema: $ref: '#/components/schemas/LtiCredentials' '403': description: Not admin of an organization content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.lti x-codegen-request-body-name: body x-logas-allowed-ro: true /organizations/lti/credentials/{credentials}: parameters: - name: credentials in: path description: | Credentials unique identifier required: true schema: type: string delete: tags: - Organization summary: Revoke LTI 1.x credentials operationId: revokeLtiCredentials responses: '204': description: Credentials revoked '403': description: Not admin of an organization content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Credentials not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' deprecated: true description: | DEPRECATED. Use the unified endpoints under `/organizations/lti/configurations`. Note: Teachers may be restricted by the organization privacy setting `lti1p1AllowTeachersCredentials`. security: - OAuth2: - edu.admin - edu.admin.lti /organizations/lti/configurations: get: tags: - Organization summary: List LTI configurations (1.1 and 1.3) operationId: listLtiConfigurations responses: '200': description: The list of LTI configurations for the caller's organization content: application/json: schema: type: array items: $ref: '#/components/schemas/LtiConfiguration' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.lti - edu.admin.lti.readonly post: tags: - Organization summary: Create a new LTI configuration (1.1 or 1.3) operationId: createLtiConfiguration requestBody: content: application/json: schema: $ref: '#/components/schemas/LtiConfigurationCreate' required: true responses: '200': description: The created LTI configuration content: application/json: schema: allOf: - $ref: '#/components/schemas/LtiConfiguration' - type: object properties: registrationUrl: type: string description: One-time registration URL (only for dynamic registration) default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.lti /organizations/lti/configurations/{configuration}: parameters: - name: configuration in: path required: true description: Configuration unique identifier schema: type: string put: tags: - Organization summary: Update an existing LTI configuration (edit 1.3; 1.1 not editable) operationId: updateLtiConfiguration requestBody: content: application/json: schema: $ref: '#/components/schemas/LtiConfigurationUpdate' required: true responses: '200': description: The updated configuration content: application/json: schema: $ref: '#/components/schemas/LtiConfiguration' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.lti delete: tags: - Organization summary: Delete an LTI configuration operationId: deleteLtiConfiguration responses: '204': description: Configuration deleted default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - edu.admin - edu.admin.lti /scores: post: tags: - Score summary: Create a new score description: | Use this API method to **create a new music score in the current User account**. This API endpoints provides 3 ways to create scores: * `ScoreCreationBuilderData` : Create a blank score by providing the list of instruments to use. You can optionally customize the initial key signature, time signature, enable TABs, Chord grids, as well as the page layout. * `ScoreCreationFileImport`: Import a file to create the new Flat document. **Preferred formats**: * **MusicXML**: `.xml`, `.musicxml`, `.mxl` (compressed) — MIME: `vnd.recordare.musicxml+xml`, `vnd.recordare.musicxml`. This is the only format that preserves all notation data (articulations, dynamics, layout, etc.) with full round-trip support. * **MIDI**: `.mid`, `.midi` — MIME: `audio/midi`. Only preserves pitch, timing, and instrument data; notation details are lost. **Also supported** (converted to MusicXML on import, some notation details may be lost): * **Guitar Pro**: `.gp`, `.gp3`, `.gp4`, `.gp5`, `.gpx`, `.gtp` * **MuseScore**: `.mscz`, `.mscx` * **ABC notation**: `.abc` — MIME: `text/vnd.abc` * **PowerTab**: `.ptb` * **Capella**: `.cap`, `.capx` * **MEI**: `.mei` * **Overture**: `.ove` * **TablEdit**: `.tef` * **Band-in-a-Box**: `.mgu`, `.sgu` * **Karaoke MIDI**: `.kar` * **MuseData**: `.md` * **Score Writer**: `.scw` * **Bagpipe Music Writer**: `.bmw`, `.bww` * **Encore**: `.enc` * `ScoreCreationGoogleDriveImport`: Import an existing Google Drive file from the connected Google Drive account. This API call will automatically create the first revision of the document, the score can be modified by the using our web application or by uploading a new revision of this file (`POST /v2/scores/{score}/revisions/{revision}`). The currently authenticated user will be granted owner of the file and will be able to add other collaborators (users and groups). If no `collection` is specified, the API will create the score in the most appropriate collection. When using an OAuth2 access token or a personal token, the score will be automatically added to your dedicated app collection in the account (`/v2/collections/app`). If a `collection` is specified and this one has more public privacy settings than the score (e.g. `public` vs `private` for the score), the privacy settings of the created score will be adjusted to the collection ones. You can check the adjusted privacy settings in the returned score `privacy`, and optionally adjust these settings if needed using `PUT /scores/{score}`. operationId: createScore requestBody: content: application/json: schema: $ref: '#/components/schemas/ScoreCreation' required: true responses: '200': description: Score created headers: x-flat-score-revision: $ref: '#/components/headers/X-Flat-Score-Revision' x-flat-score-revision-date: $ref: '#/components/headers/X-Flat-Score-Revision-Date' content: application/json: schema: $ref: '#/components/schemas/ScoreDetails' '202': description: Score will be imported using an asynchronous task (the API client has set `supportsTasks` to true) content: application/json: schema: $ref: '#/components/schemas/Task' '400': description: Bad score creation request content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '402': description: Account overquota or feature not included in plan content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores x-codegen-request-body-name: body x-codeSamples: - lang: Ruby source: | require 'flat_api' FlatApi.configure do |config| config.access_token = 'your_access_token' end begin score_data = File.open("my-score.musicxml", "r:UTF-8") { |f| f.read } body = FlatApi::ScoreCreationFileImport.new({ title: 'Score Title', data: score_data, }) p FlatApi::ScoreApi.new.create_score(body) rescue FlatApi::ApiError => e puts "Error when calling ScoreApi->create_score: #{e}" end - lang: Python source: | from pprint import pprint import os from urllib.request import urlopen from urllib.error import HTTPError import flat_api from flat_api.rest import ApiException SCORE_TO_IMPORT='https://gist.githubusercontent.com/gierschv/938479bec2bbe8c39eebbc9e19d027a0/raw/2caa4fa312184412d0d544feb361f918869ceaa5/hello-world.xml' configuration = flat_api.Configuration() configuration.access_token = os.environ['FLAT_ACCESS_TOKEN'] flat_api_client = flat_api.ApiClient(configuration) try: # Download a MusicXML "Hello World" hello_world = urlopen(SCORE_TO_IMPORT).read().decode('utf-8') # The new score meta, including the MusicXML file as `data` new_score = flat_api.ScoreCreation( title='Hello World', privacy='private', data=hello_world ) # Create the document and print the meta returned by the API pprint(flat_api.ScoreApi(flat_api_client).create_score(new_score)) except (ApiException, HTTPError) as e: print(e) - lang: PHP source: | setAccessToken($_ENV['FLAT_ACCESS_TOKEN']); $musicXml = file_get_contents('https://gist.githubusercontent.com/gierschv/938479bec2bbe8c39eebbc9e19d027a0/raw/2caa4fa312184412d0d544feb361f918869ceaa5/hello-world.xml'); try { $body = new \Flat\APIClient\Model\ScoreCreation(); $body->setTitle('Hello world'); $body->setPrivacy('private'); $body->setData($musicXml); $scoreApi = new Flat\APIClient\Api\ScoreApi(); $result = $scoreApi->createScore($body); print_r($result); } catch (Exception $e) { echo 'Exception when calling ScoreApi->createScore: ', $e->getMessage(), PHP_EOL; } /scores/{score}: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string get: tags: - Score summary: Get a score's metadata description: | Get the details of a score identified by the `score` parameter in the URL. The currently authenticated user must have at least a read access to the document to use this API call. operationId: getScore parameters: - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string responses: '200': description: Score details content: application/json: schema: $ref: '#/components/schemas/ScoreDetails' '402': description: Account overquota and this document is out of the granted quota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores - scores.readonly put: tags: - Score summary: Edit a score's metadata description: | This API method allows you to change the metadata of a score document (e.g. its `title` or `privacy`), all the properties are optional. To edit the file itself, create a new revision using the appropriate method (`POST /v2/scores/{score}/revisions/{revision}`). When editing the `title`, `subtitle`, `composer`, `lyricist`, `arranger` or `licenseText`, the metadatas will be instantly be updated, and a real-time action will be pushed to update the document lazily. This pending document modification will be automatically be saved as a new version by either a connected client or our internal versioning service. operationId: editScore requestBody: content: application/json: schema: $ref: '#/components/schemas/ScoreModification' required: true responses: '200': description: Score details content: application/json: schema: $ref: '#/components/schemas/ScoreDetails' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores x-codegen-request-body-name: body delete: tags: - Score summary: Delete a score description: | This method can be used by anyone that has at least read access to the document: - When called by an owner/admin, it will schedule the deletion of the score, its revisions, and complete history. The score won't be accessible anymore after calling this method and the user's quota will directly be updated. - When called by a collaborator, the score will be unshared (i.e. removed from the account & own collections). - When called by another user that has the score in its collections, the score will be removed from all the user collections. operationId: deleteScore parameters: - name: now in: query description: If `true`, the score deletion will be scheduled to be done ASAP schema: type: boolean default: false responses: '204': description: The score has been removed '403': description: Not granted to manage this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores /scores/{score}/untrash: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string post: tags: - Score summary: Untrash a score description: | This method will remove the score from the `trash` collection and from the deletion queue, and add it back to the original collections. operationId: untrashScore responses: '204': description: The score has been untrashed '403': description: Not granted to manage this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores /scores/{score}/submissions: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string get: tags: - Score - Class summary: List submissions related to the score description: | This API call will list the different assignments submissions where the score is attached. This method can be used by anyone that are part of the organization and have at least read access to the document. operationId: getScoreSubmissions responses: '200': description: List of submissions content: application/json: schema: type: array items: $ref: '#/components/schemas/AssignmentSubmission' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores - scores.readonly /scores/{score}/fork: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string post: tags: - Score summary: Fork a score description: | This API call will make a copy of the last revision of the specified score and create a new score. The copy of the score will have a privacy set to `private`. When using a [Flat for Education](https://flat.io/edu) account, the inline and contextualized comments will be accessible in the child document. operationId: forkScore parameters: - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ScoreFork' required: true responses: '200': description: Score details content: application/json: schema: $ref: '#/components/schemas/ScoreDetails' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores x-codegen-request-body-name: body /scores/{score}/collaborators: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string get: tags: - Score summary: List the collaborators description: | This API call will list the different collaborators of a score and their rights on the document. The returned list will at least contain the owner of the document. Collaborators can be a single user (the object `user` will be populated) or a group (the object `group` will be populated). operationId: getScoreCollaborators parameters: - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string responses: '200': description: List of collaborators content: application/json: schema: type: array items: $ref: '#/components/schemas/ResourceCollaborator' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores.readonly - scores post: tags: - Score summary: Add a new collaborator description: | Share a score with a single user or a group. This API call allows to add, invite and update the collaborators of a resource. - To add an existing Flat user to the resource, specify its unique identifier in the `user` property. - To invite an external user to the resource, specify its email in the `userEmail` property. - To add a Flat group to the resource, specify its unique identifier in the `group` property. - To update an existing collaborator, process the same request with different rights. operationId: addScoreCollaborator requestBody: content: application/json: schema: $ref: '#/components/schemas/ResourceCollaboratorCreation' required: true responses: '200': description: The newly added collaborator metadata content: application/json: schema: $ref: '#/components/schemas/ResourceCollaborator' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to manage this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores x-codegen-request-body-name: body /scores/{score}/collaborators/{collaborator}: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string - name: collaborator in: path description: | Unique identifier of a **collaborator permission**, or unique identifier of a **User**, or unique identifier of a **Group** required: true schema: type: string get: tags: - Score summary: Get a collaborator description: | Get the information about a collaborator (User or Group). operationId: getScoreCollaborator parameters: - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string responses: '200': description: Collaborator information content: application/json: schema: $ref: '#/components/schemas/ResourceCollaborator' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score or collaborator not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores.readonly delete: tags: - Score summary: Delete a collaborator description: | Remove the specified collaborator from the score operationId: removeScoreCollaborator responses: '204': description: The collaborator has been removed '403': description: Not granted to manage this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score or collaborator not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores requestBody: content: application/x-www-form-urlencoded: schema: type: object parameters: - $ref: '#/components/parameters/eventProperties' /scores/{score}/tracks: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string get: tags: - Score summary: List the audio or video tracks linked to a score description: | List all audio or video tracks linked to a score. **Access Control for Performance Submission Tracks:** Tracks with `purpose: 'performanceSubmission'` are filtered based on user role: * **Students**: Can only see their own performance submission tracks, plus all non-performance tracks * **Teachers and score admins**: Can see all tracks from all students The `assignment` query parameter can be used to filter tracks for a specific assignment, but the access control rules above still apply. operationId: listScoreTracks parameters: - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string - name: assignment in: query description: | An assignment id with which all the tracks returned will be related to schema: type: string - name: listAutoTrack in: query description: | If true, and if available, return last automatically synchronized Flat's mp3 export as an additional track schema: type: boolean responses: '200': description: List of tracks content: application/json: schema: type: array items: $ref: '#/components/schemas/ScoreTrack' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores - scores.readonly post: tags: - Score summary: Add a new video or audio track to the score description: | Use this method to add new track to the score. This track can then be played on flat.io or in an embedded score. This API method support medias hosted on SoundCloud, YouTube and Vimeo. operationId: addScoreTrack parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/ScoreTrackCreation' required: true responses: '200': description: Created track content: application/json: schema: $ref: '#/components/schemas/ScoreTrackCreationResponse' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores x-codegen-request-body-name: body /scores/{score}/tracks/{track}: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string - name: track in: path description: | Unique identifier of a score audio track required: true schema: type: string get: tags: - Score summary: Retrieve the details of an audio or video track linked to a score operationId: getScoreTrack parameters: - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string responses: '200': description: Track details content: application/json: schema: $ref: '#/components/schemas/ScoreTrack' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score or Track not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores - scores.readonly put: tags: - Score summary: Update an audio or video track linked to a score operationId: updateScoreTrack parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/ScoreTrackUpdate' required: true responses: '200': description: Updated track content: application/json: schema: $ref: '#/components/schemas/ScoreTrack' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score or Track not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores x-codegen-request-body-name: body delete: tags: - Score summary: Remove an audio or video track linked to the score operationId: deleteScoreTrack responses: '204': description: Track removed '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score or Track not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores /scores/{score}/comments: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string get: tags: - Score summary: List comments description: This method lists the different comments added on a music score (documents and inline) sorted by their post dates. operationId: getScoreComments parameters: - name: type in: query description: Filter the comments by type schema: type: string enum: - document - inline - name: sort in: query description: Sort schema: type: string enum: - date - name: direction in: query description: Sort direction schema: type: string enum: - asc - desc responses: '200': description: The comments of the score content: application/json: schema: type: array items: $ref: '#/components/schemas/ScoreComment' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores.readonly - scores.social - scores post: tags: - Score summary: Post a new comment description: | Post a document or a contextualized comment on a document. Please note that this method includes an anti-spam system for public scores. We don't guarantee that your comments will be accepted and displayed to end-user. Comments are be blocked by returning a `403` HTTP error and hidden from other users when the `spam` property is `true`. operationId: postScoreComment requestBody: content: application/json: schema: $ref: '#/components/schemas/ScoreCommentCreation' required: true responses: '200': description: The new comment content: application/json: schema: $ref: '#/components/schemas/ScoreComment' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score, to post a comment, or your API call triggered our spam filter. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores.social - scores x-codegen-request-body-name: body /scores/{score}/comments/{comment}: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string - name: comment in: path description: | Unique identifier of a sheet music comment required: true schema: type: string - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string put: tags: - Score summary: Update an existing comment operationId: updateScoreComment requestBody: content: application/json: schema: $ref: '#/components/schemas/ScoreCommentUpdate' required: true responses: '200': description: The edited comment content: application/json: schema: $ref: '#/components/schemas/ScoreComment' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score or not the original comment creator content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores.social - scores x-codegen-request-body-name: body delete: tags: - Score summary: Delete a comment operationId: deleteScoreComment responses: '204': description: The comment has been deleted '403': description: Not granted to access to this score or not the original comment creator content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score or comment not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores.social - scores requestBody: content: application/x-www-form-urlencoded: schema: type: object parameters: - $ref: '#/components/parameters/eventProperties' /scores/{score}/comments/{comment}/resolved: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string - name: comment in: path description: | Unique identifier of a sheet music comment required: true schema: type: string - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string put: tags: - Score summary: Mark the comment as resolved operationId: markScoreCommentResolved responses: '204': description: The comment has been marked as resolved '403': description: Not granted to mark this comment as resolved content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score or comment not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores.social - scores delete: tags: - Score summary: Mark the comment as unresolved operationId: markScoreCommentUnresolved parameters: - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string responses: '204': description: The comment has been unmarked as resolved '403': description: Not granted to unmark this comment as resolved content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score or comment not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores.social - scores /scores/{score}/revisions: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string get: tags: - Score summary: List the revisions description: | When creating a score or saving a new version of a score, a revision is created in our storage. This method allows you to list all of them, sorted by last modification. Depending the plan of the account, this list can be trunked to the few last revisions. operationId: getScoreRevisions parameters: - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string responses: '200': description: List of revisions content: application/json: schema: type: array items: $ref: '#/components/schemas/ScoreRevision' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores - scores.readonly post: tags: - Score summary: Create a new revision description: | Update a score by uploading a new revision for this one. operationId: createScoreRevision parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/ScoreRevisionCreation' required: true responses: '200': description: The new created revision metadata content: application/json: schema: $ref: '#/components/schemas/ScoreRevision' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to modify this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores x-codegen-request-body-name: body /scores/{score}/revisions/{revision}: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string - name: revision in: path description: | Unique identifier of a score revision. You can use `last` to fetch the information related to the last version created. required: true schema: type: string - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string get: tags: - Score summary: Get a score revision description: | When creating a score or saving a new version of a score, a revision is created in our storage. This method allows you to get a specific revision metadata. operationId: getScoreRevision responses: '200': description: Revision metadata content: application/json: schema: $ref: '#/components/schemas/ScoreRevision' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores - scores.readonly /scores/{score}/revisions/{revision}/{format}: parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string - name: revision in: path description: | Unique identifier of a score revision. You can use `last` to fetch the information related to the last version created. required: true schema: type: string - name: format in: path description: The format of the file you will retrieve required: true schema: type: string enum: - json - mxl - xml - mp3 - wav - midi - flat - thumbnail.png - synchronizationPoints get: tags: - Score summary: Get a score revision data description: | Retrieve the file corresponding to a score revision (the following formats are available): Flat JSON/Adagio JSON `json`, MusicXML `mxl`/`xml`, MP3 `mp3`, WAV `wav`, MIDI `midi`, Flat `flat`, a tumbnail of the first page `thumbnail.png` or auto sync points `synchronizationPoints`. operationId: getScoreRevisionData parameters: - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string - name: parts in: query description: | An optional a set of parts uuid to be exported. This parameter must be composed of parts uuids separated by commas. For example "59df645f-bb1c-f1b4-b573-d2afc4491f94,34ef645f-1aef-f3bc-1564-34cca4492b87". schema: type: string - name: defaultTrack in: query description: | When `format` is `mp3`, this property is set to true and the score has a default `ScoreTrack` (mp3), this one will be returned instead of the playback file. schema: type: boolean - name: url in: query description: | Returns a json with the `url` in it instead of redirecting schema: type: boolean responses: '200': description: Revision data headers: x-flat-score-revision: $ref: '#/components/headers/X-Flat-Score-Revision' x-flat-score-revision-date: $ref: '#/components/headers/X-Flat-Score-Revision-Date' content: application/json: schema: type: string format: binary application/vnd.recordare.musicxml+xml: schema: type: string format: binary application/vnd.recordare.musicxml: schema: type: string format: binary audio/mp3: schema: type: string format: binary audio/wav: schema: type: string format: binary audio/midi: schema: type: string format: binary image/png: schema: type: string format: binary application/octet-stream: schema: type: string format: binary '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score or associated file not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores - scores.readonly /scores/{score}/revisions/{revision}/{format}/task: post: tags: - Score summary: Create a new score export task description: | Some of the exports of a score takes are longer to process than a simple API requests. Use this endpoint to launch a new export of one score hosted on Flat. operationId: createExportTask parameters: - name: score in: path description: | Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). required: true schema: type: string - name: revision in: path description: | Unique identifier of a score revision. You can use `last` to fetch the information related to the last version created. required: true schema: type: string - name: format in: path description: The format of the file that will be generated or the target service name where the file will be exported required: true schema: type: string enum: - mp3 - wav - practicefirst - name: sharingKey in: query description: | This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/TaskExportOptions' required: false responses: '200': description: Task associated to the generation of the file content: application/json: schema: $ref: '#/components/schemas/Task' '402': description: Account overquota content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '403': description: Not granted to access to this score content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Score or associated file not found content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores - scores.readonly x-codegen-request-body-name: body /tasks/{task}: parameters: - name: task in: path description: Unique identifier for the task required: true schema: type: string get: tags: - Task summary: Get a task details description: | This method can be used to follow a task progression, for example while a score is being exported. operationId: getTask responses: '200': description: Task details content: application/json: schema: $ref: '#/components/schemas/Task' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - tasks.readonly /tasks/{task}/cancel: parameters: - name: task in: path description: Unique identifier for the task required: true schema: type: string /users/{user}: parameters: - name: user in: path description: | This route parameter is the unique identifier of the user. You can specify an email instead of an unique identifier. If you are executing this request authenticated, you can use `me` as a value instead of the current User unique identifier to work on the current authenticated user. required: true schema: type: string get: tags: - User summary: Get a public user profile description: | Get a profile of a Flat or Flat for Education User. operationId: getUser responses: '200': description: The user public details content: application/json: schema: $ref: '#/components/schemas/UserPublic' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - account.public_profile - account.education_profile /users/{user}/likes: parameters: - name: user in: path description: | Unique identifier of a Flat user. If you authenticated, you can use `me` to refer to the current user. required: true schema: type: string get: tags: - User - Score summary: List liked scores operationId: getUserLikes parameters: - $ref: '#/components/parameters/next' - $ref: '#/components/parameters/previous' - name: limit in: query description: This is the maximum number of objects that may be returned schema: maximum: 100 minimum: 1 type: integer default: 25 - name: ids in: query description: Return only the identifiers of the scores schema: type: boolean responses: '200': description: List of liked scores content: application/json: schema: type: array items: $ref: '#/components/schemas/ScoreDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - account.public_profile /users/{user}/scores: parameters: - name: user in: path description: | Unique identifier of a Flat user. If you authenticated, you can use `me` to refer to the current user. required: true schema: type: string get: tags: - User - Score summary: List user's scores description: | Get the list of public scores owned by a User. If you want to access to private scores, please use the [Collections API](#tag/Collection). For example `GET /v2/collections/allScores/scores` to list all recently updated scores. operationId: getUserScores parameters: - name: paginate in: query description: | When set to `true`, the API will return a paginated result. When set to `false` or unset, the API will return all the scores. If this parameter is unset or false, then limit/sort/direction/next/previous will be ignored. schema: type: boolean default: false - name: sort in: query description: Sort schema: type: string enum: - creationDate - modificationDate - title - name: direction in: query description: Sort direction schema: type: string enum: - asc - desc - name: limit in: query description: This is the maximum number of objects that may be returned schema: maximum: 100 minimum: 1 type: integer default: 25 - name: next in: query description: | An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the `Link` header when requesting the API. These URLs will contain a `next` and `previous` cursor based on the available data. schema: type: string - name: previous in: query description: | An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the `Link` header when requesting the API. These URLs will contain a `next` and `previous` cursor based on the available data. schema: type: string responses: '200': description: The user scores content: application/json: schema: type: array items: $ref: '#/components/schemas/ScoreDetails' default: description: Error content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' security: - OAuth2: - scores - scores.readonly components: securitySchemes: OAuth2: type: oauth2 description: | OAuth 2.0 authentication for your app or. Please only request the most restrictive and needed scopes. Using some of the scopes may require an additional review from our team. The Flat API supports **authorization code** and **implicit** flows. flows: authorizationCode: authorizationUrl: https://flat.io/auth/oauth tokenUrl: https://api.flat.io/oauth/access_token scopes: account.public_profile: | Provides access to the basic person's public profile. Education profiles may be anonymized with this scope, you can request the scope `education_profile` to access to the a basic education account profile. account.email: | Provices access to the person's email. account.education_profile: | Provides access to the basic person's education profile and public organization information. scores.readonly: | Allows read-only access to all a user's scores. You won't need this scope to read public scores. scores.social: | Allow to post comments and like scores scores: | Full, permissive scope to access all of a user's scores. 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. notifications.readonly: Read-only access to a user's notifications. edu.resources: Read-write access to the resource library. edu.resources.readonly: Read-only access to the resource library. 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. tasks.readonly: Read-only access to export tasks created by this account. schemas: AppScopes: type: string description: Available scopes enum: - account.public_profile - account.email - account.education_profile - scores.readonly - scores.social - scores - collections.readonly - collections.add_scores - collections - notifications.readonly - edu.resources - edu.resources.readonly - edu.classes - edu.classes.readonly - edu.assignments - edu.assignments.readonly - edu.admin - edu.admin.lti - edu.admin.lti.readonly - edu.admin.users - edu.admin.users.readonly - tasks.readonly AssignmentType: type: string description: Type of the assignment enum: - none - newScore - scoreTemplate - sharedWriting - worksheet - worksheetText - performance Assignment: type: object required: - id - type - title - attachments - capabilities properties: id: type: string description: Unique identifier of the assignment type: $ref: '#/components/schemas/AssignmentType' capabilities: required: - canEdit - canPublishInClass - canArchive - canUnarchive type: object description: Capabilities the current user has on this assignment. Each capability corresponds to a fine-grained action that a user may take. properties: canEdit: type: boolean description: | Whether the current user can edit the assignment canPublishInClass: type: boolean description: | Whether this assignment can be published in a class canPublishInClassError: type: object required: - code - message description: | If `canPublishInClass` and `canEdit` are false, the issue why this assignment cannot be published in a class properties: code: type: string description: A corresponding code for this error message: type: string description: A printable and localized message for this error canArchive: type: boolean description: | Whether the current user can archive the assignment canUnarchive: type: boolean description: | Whether the current user can unarchive the assignment title: type: string description: Title of the assignment description: type: string description: Student instructions and content of the assignment (plain text) descriptionHtml: type: string description: | HTML version of student instructions with rich text formatting. Supports the following HTML tags: p, br, strong, b, em, i, u, a, ul, ol, li, h1, h2, h3. teacherInstructions: type: string description: | Teacher-only instructions for this assignment. These instructions are only visible to teachers and are not returned when students view the assignment. If `teacherInstructionsHtml` is provided, this field will contain the plain text version for compatibility. teacherInstructionsHtml: type: string description: | HTML version of teacher-only instructions with rich text formatting. Supports the following HTML tags: p, br, strong, b, em, i, u, a, ul, ol, li, h1, h2, h3. cover: type: string description: The URL of the cover to display coverFile: type: string description: The id of the cover to display attachments: type: array items: $ref: '#/components/schemas/MediaAttachment' useDedicatedAttachments: type: boolean description: | For all assignments created after 02/2023, all the underlying resources must be dedicated and stored in the assignment. This boolean indicates that this assignment only supports dedicated attachments. maxPoints: type: number description: | If set, the grading will be enabled for the assignement releaseGrades: type: string enum: - auto - manual description: | For worksheets, how grading will work for the assignment: - If set to `auto`, the grades will be automatically released when the student submits the submissions - If set to `manual`, the grades will only be set as `draftGrade` and will be released when the teacher returns the submissions shuffleExercises: type: boolean description: Mixing worksheets exercises for each student toolset: type: string description: The id of the associated toolset nbPlaybackAuthorized: type: number description: The number of playback authorized on the scores of the assignment. restrictPlayNote: type: boolean description: Restrict the ability to get an audio feedback every time a student adds or selects a note. restrictToAudioTracks: type: boolean description: Restrict the audio source to provided audio tracks on a score. Students won't be able to use the editor playback. submissionStudentsMode: $ref: '#/components/schemas/AssignmentSubmissionStudentsMode' recordingType: type: string description: | For performance assignments: recording type that will be either 'audio' or 'video'. * `audio`: Only audio will be required during the recording. * `video`: Camera will be required during the recording. Only set when type is 'performance'. enum: - audio - video allowMetronome: type: boolean description: | For performance assignments: Enable students to use the metronome while they are recording, helping them stay in time. Only set when type is 'performance'. allowBackingTrack: type: boolean description: | For performance assignments: Enable students to listen to the accompaniment without their instrument part while they are playing. Only set when type is 'performance'. allowSpeedChange: type: boolean description: | For performance assignments: whether students can adjust the playback speed of the score during recording. * `true`: Students can change the tempo/speed during practice and recording * `false`: Tempo is fixed to the original score tempo Only set when type is 'performance'. description: Assignment details example: id: 636a724a89a6eaa0a54c3900 title: My first assignment description: Get started with Flat maxPoints: 100 attachments: - type: flat score: '0000000000000000' - type: link url: https://flat.io/developers - type: video url: https://www.youtube.com/watch?v=SNbRUiBZ4Uw title: Flat - The online collaborative music notation software description: Discover Flat on https://flat.io html: thumbnailUrl: https://i.ytimg.com/vi/SNbRUiBZ4Uw/maxresdefault.jpg thumbnailHeight: 1052 thumbnailWidth: 1868 authorName: Flat authorUrl: https://www.youtube.com/channel/UCEUIbEP9Rba_g0r4eeGhmXw AssignmentUpdate: type: object description: Assignment Resource Editing properties: type: $ref: '#/components/schemas/AssignmentType' title: type: string description: Title of the assignment maxLength: 1000 minLength: 1 description: type: string maxLength: 100000 description: Student instructions and content of the assignment (plain text) descriptionHtml: type: string maxLength: 100000 description: | HTML version of student instructions. When provided, the plain text version will be automatically extracted for compatibility. teacherInstructions: type: string maxLength: 100000 description: Teacher-only instructions (plain text) teacherInstructionsHtml: type: string maxLength: 100000 description: | HTML version of teacher-only instructions. When provided, the plain text version will be automatically extracted for compatibility. attachments: type: array items: $ref: '#/components/schemas/ClassAttachmentCreation' nbPlaybackAuthorized: type: number nullable: true description: The number of playback authorized on the scores of the assignment. restrictPlayNote: type: boolean description: Restrict the ability to get an audio feedback every time a student adds or selects a note. restrictToAudioTracks: type: boolean description: Restrict the audio source to provided audio tracks on a score. Students won't be able to use the editor playback. toolset: type: string nullable: true description: | The id of the toolset to apply to this assignment. The toolset will be copied to the assignment as a dedicated object to prevent unexpected changes when making modifications to the template toolset. This property can be set to null to delete the linked toolset and switch back to all the tools available for this assignment. coverFile: type: string nullable: true description: The id of the cover to display cover: type: string nullable: true description: The URL of the cover to display maxPoints: type: number nullable: true minimum: 0 maximum: 10000 description: | If set, the grading will be enabled for the assignement with this value as the maximum of points releaseGrades: type: string enum: - auto - manual description: | For worksheets, how grading will work for the assignment: - If set to `auto`, the grades will be automatically released when the student submits the submissions - If set to `manual`, the grades will only be set as `draftGrade` and will be released when the teacher returns the submissions shuffleExercises: type: boolean description: Mixing worksheets exercises for each student submissionStudentsMode: $ref: '#/components/schemas/AssignmentSubmissionStudentsMode' recordingType: type: string description: | For performance assignments: recording type that will be either 'audio' or 'video'. * `audio`: Only audio will be required during the recording. * `video`: Camera will be required during the recording. Only set when type is 'performance'. enum: - audio - video allowMetronome: type: boolean description: | For performance assignments: Enable students to use the metronome while they are recording, helping them stay in time. Only set when type is 'performance'. allowBackingTrack: type: boolean description: | For performance assignments: Enable students to listen to the accompaniment without their instrument part while they are playing. Only set when type is 'performance'. allowSpeedChange: type: boolean description: | For performance assignments: whether students can adjust the playback speed of the score during recording. * `true`: Students can change the tempo/speed during practice and recording * `false`: Tempo is fixed to the original score tempo Only set when type is 'performance'. example: title: First assignment description: Get started with Flat maxPoints: 100 attachments: - type: flat score: '0000000000000000' - type: link url: https://flat.io/developers AssignmentSubmissionStudentsMode: type: string description: | Submission mode for assignments: - "single": Individual submissions (default) - "group": Group submissions (for shared writing assignments) enum: - single - group AssignmentGroup: type: object properties: id: type: string description: The unique identifier of the group name: type: string description: The display name of the group parent: type: string description: The unique identifier of the parent class group. Only available for groups of type 'assignmentStudentsSubGroup'. May be null if the parent class group was deleted. members: type: array items: type: string description: Array of user IDs that are members of this group required: - id - name - members description: A group assigned to an assignment for shared writing assignments ClassGroupIdsToApplyToAssignment: type: array nullable: true items: type: string description: | Optional list of specific class group IDs to apply to the assignment. When transitioning to active state with group submission mode: - If provided: Only these specific groups will be applied - If not provided: All class groups will be applied, or randomized groups created if none exist AssignmentCopy: oneOf: - $ref: '#/components/schemas/AssignmentCopyToClass' - $ref: '#/components/schemas/AssignmentCopyToResourceLibrary' AssignmentCopyToResourceLibrary: type: object description: Copy the assignment to the EDU Resource Library required: - libraryParent properties: libraryParent: type: string description: Identifier of the parent resource where the new one will created, e.g. a folder id or `root` verifyIfNotAlreadyInResourceLibrary: type: boolean description: Option to check if the assignment is already in Resource Library example: libraryParent: '0000000000000000' AssignmentCopyToClass: type: object description: Copy the assignment to a class required: - classroom properties: classroom: type: string description: The destination classroom where the assignment will be copied assignment: type: string description: An optional destination assignment where the original assignement will be copied. Must be a draft. scheduledDate: type: string description: | The publication (scheduled) date of the assignment. If this one is specified, the assignment will only be listed to the teachers of the class. Alternatively the existing `scheduledDate` from the copied assignment will be used. format: date-time example: classroom: '0000000000000000' AssignmentSubmissionState: type: string description: State of the submission enum: - created - turnedIn - returned - graded AssignmentSubmissionHistoryState: type: string description: State of the submission history enum: - created - turnedIn - returned - graded - reset AssignmentSubmission: type: object required: - id - state - classroom - assignment - creator - creationDate - attachments - playback - comments properties: id: type: string description: Unique identifier of the submission state: $ref: '#/components/schemas/AssignmentSubmissionState' classroom: type: string description: | Unique identifier of the classroom where the assignment was posted assignment: type: string description: Unique identifier of the assignment creator: type: string description: The User identifier of the student who created the submission creationDate: type: string description: The date when the submission was created attachments: type: array items: $ref: '#/components/schemas/MediaAttachment' submissionDate: type: string description: The date when the student submitted their work returnDate: type: string description: The date when the teacher returned the work returnCreator: type: string description: | The User unique identifier of the teacher who returned the submission grade: type: number nullable: true description: Optional grade. If unset, no grade was set. draftGrade: type: number nullable: true description: Optional grade. If unset, no grade was set. This value is only visible by the teacher, and we will be set to `grade` once the teacher returns the submission maxPoints: type: number description: Optional max points for the grade. If set, a corresponding `draftGrade` or `grade` will be set. exercisesIds: type: array items: type: string description: The ids of exercises when they need to be in a specific order playback: type: array items: $ref: '#/components/schemas/AssignmentSubmissionPlayback' comments: type: object properties: total: type: number description: The total number of comments added to the submission unread: type: number description: The number of unread comments for the current user googleClassroom: $ref: '#/components/schemas/GoogleClassroomSubmission' microsoftGraph: $ref: '#/components/schemas/MicrosoftGraphSubmission' lti: type: object description: If set, this submission has a linked LTI 1.3 AGS or LTI 1.1 Outcomes required: - gradeService properties: gradeService: type: string description: | The kind of grading service available for this submission: - `ags2p0`: LTI 1.3 Assignment and Grade Services 2.0 - `outcomes1p1`: LTI 1.1 Outcomes 1.1 enum: - ags2p0 - outcomes1p1 sourcedid: type: string description: The sourcedid of the LTI submission when using LTI Outcomes description: Assignment Submission example: id: 58c4955c226ffff257211a90 classroom: 58c4725345cd836264f0b29e assignment: 58c49068524c03ec576ca43c creator: 559eb5c7f0d4d5e46d03781d attachments: - type: flat score: 58c4955a226ffff257211a8d title: Hello - Student returnCreator: 559eb5c7f0d4d5e46d000000 grade: 80 draftGrade: 82 googleClassroom: id: CgsI-00000000000 state: turned_in alternateLink: http://classroom.google.com/c/music-theory/a/first-assignment/submissions/student/my-submission AssignmentSubmissionUpdate: type: object properties: attachments: type: array items: $ref: '#/components/schemas/ClassAttachmentCreation' playback: type: array items: $ref: '#/components/schemas/AssignmentSubmissionPlayback' submit: type: boolean description: If `true`, the submission will be marked as done draftGrade: type: number nullable: true minimum: 0 maximum: 10000 description: Optional grade. If unset, no grade was set. This value is only visible by the teacher, and we will be set to `grade` once the teacher returns the submission grade: type: number nullable: true minimum: 0 maximum: 10000 description: Optional grade. If unset, no grade was set. exercisesIds: type: array nullable: true items: type: string description: The ids of exercises when they need to be in a specific order return: type: boolean description: If `true`, the submission will be marked as done description: Assignment Submission creation example: attachments: - type: flat score: 58c4955a226ffff257211a8d title: Hello - Student submit: true AssignmentSubmissionComment: description: Feedback comment added to an assignment submission type: object properties: id: type: string description: The comment unique identifier user: type: string description: The author unique identifier submission: type: string description: The submission unique identifier date: type: string description: The date when the comment was posted format: date-time modificationDate: type: string description: The date of the last comment modification format: date-time comment: type: string description: The comment text unread: type: boolean description: True if the comment is unread by the current user AssignmentSubmissionCommentCreation: description: Creation of a assignment submission comment required: - comment type: object properties: comment: type: string description: The comment text AssignmentSubmissionPlayback: type: object description: Playback used by a student for an assignment submission. required: - score - nbPlayAttempt properties: score: type: string description: The score unique identifier nbPlayAttempt: type: number description: Number of times the score was played AssignmentSubmissionHistory: description: History item of the submission type: object required: - date - users properties: date: description: The date when the submission was changed type: string format: date-time classroom: description: The classroom unique identifier where the submission was changed type: string assignment: description: The assignment unique identifier where the submission was changed type: string submission: description: The submission unique identifier type: string users: description: The user(s) unique identifier(s) who made the change type: array items: type: string source: description: The source of the change if the change was made by a third-party software type: string enum: - lti - googleClassroom - microsoftGraph state: $ref: '#/components/schemas/AssignmentSubmissionHistoryState' draftGrade: type: number description: The numerator of the grade at this time in the submission grade history grade: type: number description: The numerator of the grade at this time in the submission grade history maxPoints: type: number description: The denominator of the grade at this time in the submission grade history comment: type: string description: The comment that is made to this submission dueDate: type: string description: The due date of this assignment format: date-time attachment: type: object properties: score: type: string description: The score identifier that changed revision: type: string description: The revision identifier that changed title: type: string description: The title of the score that changed ClassAssignment: allOf: - $ref: '#/components/schemas/Assignment' - type: object required: - state - creationDate - submissions properties: creator: type: string description: | The User unique identifier of the creator of this assignment state: type: string description: State of the assignment enum: - draft - active - archived classroom: type: string description: The unique identifier of the class where this assignment was posted creationDate: type: string description: The creation date of this assignment format: date-time scheduledDate: type: string description: | The publication (scheduled) date of the assignment. If this one is specified, the assignment will only be listed to the teachers of the class. format: date-time dueDate: type: string description: | The due date of this assignment, late submissions will be marked as paste due. format: date-time assigneeMode: type: string description: Possible modes of assigning assignments enum: - everyone - selected assignedStudents: type: array items: type: string description: Identifiers for the students that have access to the assignment assignedGroups: type: array items: $ref: '#/components/schemas/AssignmentGroup' description: Groups that have access to the assignment (for shared writing assignments) submissions: type: array items: $ref: '#/components/schemas/AssignmentSubmission' googleClassroom: $ref: '#/components/schemas/GoogleClassroomCoursework' microsoftGraph: $ref: '#/components/schemas/MicrosoftGraphAssignment' mfc: type: object description: A MusicFirst Classroom assignment properties: id: type: string description: Unique identifier of the course on MusicFirst Task alternateLink: type: string description: Link to MusicFirst Classroom task canvas: type: object description: A Canvas LMS assignment properties: id: type: string description: Unique identifier of the course on Canvas assignment alternateLink: type: string description: Link to Canvas assignment lti: type: object description: An LTI assignment properties: id: type: string description: Resource ID in the LMS issue: type: string description: Detected issue for this assignment example: id: 636a724a89a6eaa0a54c3900 title: My first assignment description: Get started with Flat state: active creator: 5832bf149995c4024bd6de7d classroom: 58c4725345cd836264f0b29e maxPoints: 100 attachments: - type: flat score: '0000000000000000' - type: link url: https://flat.io/developers - type: video url: https://www.youtube.com/watch?v=SNbRUiBZ4Uw title: Flat - The online collaborative music notation software description: Discover Flat on https://flat.io html: thumbnailUrl: https://i.ytimg.com/vi/SNbRUiBZ4Uw/maxresdefault.jpg thumbnailHeight: 1052 thumbnailWidth: 1868 authorName: Flat authorUrl: https://www.youtube.com/channel/UCEUIbEP9Rba_g0r4eeGhmXw googleClassroom: id: '1235665432' alternateLink: http://classroom.google.com/c/music-theory/a/first-assignment/detail lti: id: '12345' canvas: id: '12345' alternateLink: https://canvas.instructure.com/courses/00000/assignments/12345 submissions: - id: 58c4955c226ffff257211a90 classroom: 58c4725345cd836264f0b29e assignment: 58c49068524c03ec576ca43c creator: 559eb5c7f0d4d5e46d03781d attachments: - type: flat score: 58c4955a226ffff257211a8d title: Hello - Student googleClassroom: id: CgsI-00000000000 state: turned_in alternateLink: http://classroom.google.com/c/music-theory/a/first-assignment/submissions/student/my-submission ClassAssignmentUpdate: type: object allOf: - $ref: '#/components/schemas/AssignmentUpdate' - type: object properties: state: type: string description: State of the assignment enum: - draft - active dueDate: type: string nullable: true description: | The due date of this assignment, late submissions will be marked as paste due. If not set, the assignment won't have a due date. format: date-time scheduledDate: type: string nullable: true description: | The publication (scheduled) date of the assignment. If this one is specified, the assignment will only be listed to the teachers of the class. format: date-time googleClassroom: type: object description: Google Classroom options for this assignment properties: topicId: type: string nullable: true description: Identifier of the topic where the assignment is created microsoftGraph: type: object description: Microsoft Graph options for this assignment properties: categories: description: List of categories this assignment belongs to type: array nullable: true items: type: string assigneeMode: type: string description: Possible modes of assigning assignments enum: - everyone - selected assignedStudents: type: array items: type: string description: Identifiers for the students that have access to the assignment submissionStudentsMode: $ref: '#/components/schemas/AssignmentSubmissionStudentsMode' classGroupIds: $ref: '#/components/schemas/ClassGroupIdsToApplyToAssignment' description: Assignment creation details example: title: First assignment description: Get started with Flat maxPoints: 100 attachments: - type: flat score: '0000000000000000' - type: link url: https://flat.io/developers ApiAccessToken: type: object properties: id: type: string description: Unique identifier of this private token name: type: string description: Name of the personal access token token: type: string description: | The token. This token will only be returned once, then only the first 4 characters will be returned. issuedDate: type: string description: | The date then this token was issued format: date-time expirationDate: type: string description: | The date then this token will expire format: date-time scopes: type: array description: | The list of scopes associated to the token items: $ref: '#/components/schemas/AppScopes' description: An API access token example: id: '0000000000000000' name: API Access Token name token: '00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000' scopes: - account.public_profile - account.education_profile - collections.readonly ClassRoles: type: string description: User's Class Role (for Edu users only) enum: - teacher - student ClassCreation: required: - name type: object properties: name: maxLength: 255 type: string description: The name of the new class section: maxLength: 255 type: string description: The section of the new class level: $ref: '#/components/schemas/ClassGradeLevel' skillsFocused: $ref: '#/components/schemas/EduSkillsFocused' size: type: number minimum: 0 nullable: true description: Number of students in the classroom description: Creation of a classroom example: name: Music Theory Course section: Music Theory 101 ClassUpdate: type: object properties: name: maxLength: 255 type: string description: The name of the class section: maxLength: 255 type: string description: The section of the class level: $ref: '#/components/schemas/ClassGradeLevel' skillsFocused: $ref: '#/components/schemas/EduSkillsFocused' size: type: number minimum: 0 nullable: true description: Number of students in the classroom description: Update of a classroom example: name: Music Theory Course section: Music Theory 101 ClassDetails: type: object required: - id - name - state - creationDate properties: id: type: string description: The unique identifier of the class state: $ref: '#/components/schemas/ClassState' name: type: string description: The name of the class section: type: string description: The section of the class description: type: string description: An optionnal description for this class organization: type: string description: The unique identifier of the Organization owning this class owner: type: string description: The unique identifier of the User owning this class creationDate: type: string description: The date when the class was create format: date-time modificationDate: type: string description: The date when the class was last modified format: date-time enrollmentCode: type: string description: | [Teachers only] The enrollment code that can be used by the students to join the class theme: type: string description: The theme identifier using in Flat User Interface assignmentsCount: type: number description: The number of assignments created in the class studentsGroup: $ref: '#/components/schemas/GroupDetails' teachersGroup: $ref: '#/components/schemas/GroupDetails' issues: type: object description: Detected issues for this class properties: sync: type: array description: Synchronization issues for the class items: type: object description: A sync issue properties: id: type: string description: The account user identifier email: type: string description: The email address of the user concerned by this sync issue reason: type: string enum: - otherOrgnanization - productMigration - disabledAccount description: The reason why the account cannot be synced googleClassroom: type: object properties: id: type: string description: The course identifier on Google Classroom alternateLink: type: string description: Absolute link to this course in the Classroom web UI description: Google Classroom course-related information googleDrive: type: object properties: teacherFolderId: type: string description: | [Teachers only] The Drive directory identifier of the teachers' folder teacherFolderAlternateLink: type: string description: | [Teachers only] The Drive URL of the teachers' folder description: Google Drive course-related information provided by Google Classroom microsoftGraph: type: object properties: id: type: string description: The course identifier on Microsoft Graph lti: description: Info about LTI context (1.1 and 1.3) type: object properties: contextId: type: string description: Unique context identifier provided contextTitle: type: string description: Context title contextLabel: type: string description: Context label hasNrpsService: type: boolean description: If true, the class has been synchronized with the LTI 1.3 NRPS 2.0 service canvas: type: object properties: id: type: string description: Unique identifier of the course on Canvas domain: type: string description: Canvas instance domain (e.g. "canvas.instructure.com") description: Meta information provided by Canvs LMS mfc: type: object properties: id: type: string description: Unique identifier of the course on MusicFirst Classroom alternateLink: type: string description: Link to MusicFirst Classroom class description: Meta information provided by Canvs LMS clever: type: object properties: id: type: string description: Clever section unique identifier creationDate: type: string description: The creation date of the section on clever format: date-time modificationDate: type: string description: The last modification date of the section on clever format: date-time subject: type: string description: Normalized subject of the course enum: - english/language arts - math - science - social studies - language - homeroom/advisory - interventions/online learning - technology and engineering - PE and health - arts and music - other termName: type: string description: Name of the term when this course happens termStartDate: type: string description: Beginning date of the term format: date-time termEndDate: type: string description: End date of the term format: date-time description: Clever.com section-related information level: $ref: '#/components/schemas/ClassGradeLevel' skillsFocused: $ref: '#/components/schemas/EduSkillsFocused' size: type: number nullable: true description: Number of students in the classroom description: A classroom example: id: '100000000000000000000001' state: active name: Music Theory 101 section: Music Theory 101 organization: '100000000000000000000002' owner: '100000000000000000000003' enrollmentCode: jm447ear theme: blue-8 assignmentsCount: 10 googleClassroom: id: '00000000' alternateLink: http://classroom.google.com/c/music-theory microsoftGraph: id: 00000000-0000-0000-0000-000000000000 googleDrive: teacherFolderAlternateLink: https://drive.google.com/drive/folders/0B-0000000000000000 teacherFolderId: 0B-0000000000000000 lti: contextId: '042' contextLabel: MUSIC contextTitle: Music Theory 101 canvas: id: '000000000' ClassAttachmentCreation: type: object properties: type: type: string description: | The type of the attachment posted: * `rich`, `photo`, `video` are attachment types that are automatically resolved from a `link` attachment. * A `flat` attachment is a score document where the unique identifier will be specified in the `score` property. Its sharing mode will be provided in the `sharingMode` property. enum: - rich - photo - video - link - flat - googleDrive - worksheet score: type: string description: | A unique Flat score identifier. The user creating the assignment must at least have read access to the document. If the user has admin rights, new group permissions will be automatically added for the teachers and students of the class. worksheet: type: string description: An unique worksheet identifier revision: type: string description: An unique revision identifier of a score partUuid: type: string description: The UUID of the instrument part selected for this attachment (for performance submissions) sharingMode: $ref: '#/components/schemas/MediaScoreSharingMode' lockScoreTemplate: type: boolean description: To be used with a score attached in `sharingMode` `copy` (score used as template). If true, students won't be able to change the original notes of the template. url: type: string description: The URL of the attachment. googleDriveFileId: type: string description: The ID of the Google Drive File teacherOnly: type: boolean description: Flag indicating if this attachment should only be visible to teachers default: false description: | Attachment creation for an assignment or stream post. This attachment must contain a `score` or an `url`, all the details of this one will be resolved and returned as `ClassAttachment` once the assignment or stream post is created. example: type: flat score: '000000000000000001' sharingMode: copy ClassGradeLevel: type: string description: Class grade level enum: - elementary - middle - high - university - other EduResourceUseInClass: description: Use an education resource in class type: object required: - classroom properties: classroom: type: string description: The destination classroom where the resource will be copied. assignment: type: string description: An optional destination assignment where the original assignement will be copied. Must be a draft. MicrosoftGraphAssignment: type: object description: A Microsoft Teams assignment properties: id: type: string description: Identifier of the assignment assigned by Microsoft Teams state: type: string description: | State of the assignment on Microsoft Teams. * `draft`: Assignment is in draft mode * `scheduled`: Assignment is scheduled to be published at a future date * `published`: Assignment has been published to students * `assigned`: Assignment has been assigned (legacy status) * `inactive`: Assignment is inactive enum: - draft - scheduled - published - assigned - inactive alternateLink: type: string description: Absolute link to this assignment in the Microsoft Teams web UI assignDateTime: type: string format: date-time description: | The date when the assignment will become active on Microsoft Teams. If set to a future date, the assignment will have status `scheduled` and won't be visible to students until this date. categories: type: array description: List of categories where this assignment is published under items: type: string description: A Microsoft Teams assignment category ID assignToType: type: string description: | Recipient configuration for this assignment on Microsoft Teams. * `class`: Assignment is visible to all students in the class * `individual`: Assignment is visible only to specific assigned students enum: - class - individual assignedStudentsMsIds: type: array description: | When assignToType is 'individual', array of Microsoft Azure user IDs of students assigned to this assignment. These are the students who can see and submit to this assignment on Teams. items: type: string example: id: 8e460d32-d2d4-46b3-8e1a-9b7677a48fda state: scheduled alternateLink: https://teams.microsoft.com/l/entity assignDateTime: 2025-10-20T09:00:00Z categories: - 0a012acd-6e78-4cd0-89a9-80d296e48f82 GoogleClassroomCoursework: type: object properties: id: type: string description: Identifier of the coursework assigned by Classroom state: type: string description: State of the coursework alternateLink: type: string description: Absolute link to this coursework in the Classroom web UI topicId: type: string nullable: true description: Identifier of the topic where the assignment is created description: A coursework on Google Classroom example: id: '1235665432' state: draft alternateLink: http://classroom.google.com/c/music-theory/a/first-assignment/detail GoogleClassroomSubmission: type: object required: - id - state - alternateLink properties: id: type: string description: Identifier of the coursework submission assigned by Classroom state: type: string description: State of the submission on Google Classroom alternateLink: type: string description: Absolute link to this coursework in the Classroom web UI description: A coursework submission on Google Classroom example: id: CgsI-00000000000 state: turned_in alternateLink: http://classroom.google.com/c/music-theory/a/first-assignment/submissions/student/my-submission ClassState: type: string description: The state of a classroom enum: - active - inactive - archived - deleted Collection: type: object required: - id - title - htmlUrl - type - privacy - creationDate - capabilities - contents properties: id: type: string description: Unique identifier of the collection title: type: string description: The title of the collection htmlUrl: type: string description: The url where the collection can be viewed in a web browser format: url type: $ref: '#/components/schemas/CollectionType' labelKey: type: string description: | Product-specific translation key for the collection type. Only set for specific collection types: * For `regular` type: `playlist` (Flat) or `collection` (Flat for Education) * For `collaborations` type: `collaboration` (Flat) or `shared-scores` (Flat for Education) Not set for other collection types. privacy: $ref: '#/components/schemas/CollectionPrivacy' sharingKey: type: string description: The private sharing key of the collection (available when the `privacy` mode is set to `privateLink`) app: $ref: '#/components/schemas/CollectionApp' creationDate: type: string description: The date when the collection was created format: date-time modificationDate: type: string description: The date when the collection was last modified format: date-time user: $ref: '#/components/schemas/UserPublicSummary' organization: type: string description: | If the score has been created in an organization, the identifier of this organization. rights: $ref: '#/components/schemas/ResourceRights' collaborators: type: array description: The list of the collaborators of the collection items: $ref: '#/components/schemas/ResourceCollaborator' isPinned: type: boolean description: Whether the collection is pinned by the owner contents: type: object description: The contents of the collection required: - scoresCount properties: scoresCount: type: integer description: The number of scores in the collection capabilities: type: object required: - canEdit - canShare - canDelete - canAddScores - canDeleteScores properties: canEdit: type: boolean description: | Whether the current user can modify the metadata for the collection canShare: type: boolean description: | Whether the current user can modify the sharing settings for the collection canDelete: type: boolean description: | Whether the current user can delete the collection canAddScores: type: boolean description: | Whether the current user can add scores to the collection If this collection has the `type` `trash`, this property will be set to `false`. Use `DELETE /v2/scores/{score}` to trash a score. canDeleteScores: type: boolean description: | Whether the current user can delete scores from the collection If this collection has the `type` `trash`, this property will be set to `false`. Use `POST /v2/scores/{score}/untrash` to restore a score. description: Capabilities the current user has on this collection. Each capability corresponds to a fine-grained action that a user may take. collections: type: array description: The List of parent collections, which includes all the collections this score is included. Please note that you might not have access to all of them. items: type: string description: Collection of scores CollectionCreation: type: object properties: title: maxLength: 300 minLength: 1 type: string description: The title of the collection privacy: $ref: '#/components/schemas/CollectionPrivacy' example: title: Jazz scores privacy: private CollectionModification: type: object properties: title: maxLength: 300 minLength: 1 type: string description: The title of the collection privacy: $ref: '#/components/schemas/CollectionPrivacy' description: Edit the collection metadata CollectionType: type: string description: | Type of the collection. The type will influence the capabilitied available on the collections and how this collection is/can be populated. - `root`: **Deprecated.** Previously the root collection of the user. The `allScores` virtual collection should be used instead. - `regular`: A regular collection created by the user. This collection can be deleted and modified by the user. - `app`: An automatically created collection containing the scores created by an app (e.g. Music Snippet) - `trash`: An automatically created collection containing the trashed scores. Virtual collections: - `allScores`: All the scores contained in the user account - `collaborations`: All shared scores by the user or someone else - `likes`: Liked scores enum: - root - regular - app - trash - allScores - collaborations - likes CollectionPrivacy: type: string default: private description: | The collection main privacy mode. - `private`: The collection is private and can only be accessed, modified, and administered by specified collaborators. enum: - private CollectionApp: type: object description: For App collections, the details of the app that created the collection properties: id: type: string description: The app unique identifier name: type: string description: The name of the app logo: type: string description: The app logo url FlatLocalesString: type: string description: | The user language. Input values will be automatically normalized to a supported locale code. Unknown locales will default to `en`. Current supported locales include: `da`, `de`, `en`, `en-GB`, `es`, `fi`, `fil`, `fr`, `fr-CA`, `hi`, `id`, `it`, `ja`, `ja-HIRA`, `ko`, `ms`, `nb`, `nl`, `pl`, `pt`, `pt-BR`, `ro`, `ru`, `sv`, `tr`, `zh-Hans`, `zh-HK`, `zh-TW` default: en ScoreTrackCreationResponse: type: object required: - track properties: track: $ref: '#/components/schemas/ScoreTrack' description: Response for track creation including optional upload information AssignmentCopyResponse: allOf: - $ref: '#/components/schemas/Assignment' - type: object properties: resource: type: string description: If this assignment is stored as a resource in the Flat for Education Resource Library, the unique identifier of the resource. FlatErrorResponse: description: An API Error response type: object required: - code - message properties: code: type: string description: A corresponding code for this error message: type: string description: A printable message for this error id: type: string description: An unique error identifier generated for the request param: type: string description: The related parameter that caused the error example: code: CLIENT_ERROR message: Invalid request id: '123456789' EduSkillsFocused: type: array description: Specific skills that will be focused in classroom items: type: string enum: - notation - sight-reading - performance-instrumental - ear-training - music-theory - composition - jazz-ensemble - music-technology - other EduLibrary: description: A Flat for Education Library type: object required: - id - name - type - visibility properties: id: type: string description: | Unique identifier of the library. This one can be used to list the underlying resources using `GET /v2/eduResources?parent={library-id}` name: type: string description: Name of the lirbary type: type: string description: Type of the library enum: - myResources - organizationResources - flatEduContent visibility: description: Visibility of the library type: string enum: - private - organization - public example: id: root name: My resources visibility: private EduResourcePrivacy: type: string description: | The Education resource privacy mode. default: private enum: - private - organizationPublic - public EduResource: description: A Flat for Education resource contained in a resources library type: object required: - id - type - title - capabilities properties: id: type: string description: Resource unique identifier creator: type: string description: The User identifier of the resource creator type: $ref: '#/components/schemas/EduResourceType' privacy: $ref: '#/components/schemas/EduResourcePrivacy' tags: type: array description: Specific attributes for the resource (e.g. sample resources with custom design) items: type: string parent: type: string description: Identifier of the parent resource, e.g. a folder or root title: type: string description: Title of the resource sharingDescription: type: string description: Sharing description of this resource sharingDescriptionHtml: type: string description: | HTML version of sharing description with rich text formatting. Supports safe HTML tags: p, br, strong, b, em, i, u, a. creationDate: type: string format: date-time description: The date when the resource was created updateDate: type: string format: date-time description: The date when the resource was updated resource: oneOf: - $ref: '#/components/schemas/Assignment' - $ref: '#/components/schemas/EduResourceFolder' capabilities: description: Capabilities available for this resource type: object properties: canEdit: type: boolean description: | Whether the current user can modify this resource canAddResources: type: boolean description: | Whether the current user can add resources within this resource (e.g. `assignment` inside a `folder`) canAddFolders: type: boolean description: | Whether the current user can add folders within this resource (e.g. `folder` inside `root`) canChangePrivacy: type: boolean description: | Whether the current user can change the privacy of this resource (e.g. to share as `organizationPublic` or unshare it with `private`) subjects: $ref: '#/components/schemas/EduResourceSubjects' grades: $ref: '#/components/schemas/EduResourceGrades' EduResourceCreation: description: Creation of an education resource type: object required: - type - title properties: type: $ref: '#/components/schemas/EduResourceType' title: type: string description: Title of the resource maxLength: 1000 minLength: 1 parent: type: string default: root description: Identifier of the parent resource where the new one will created, e.g. a folder id or `root` sharingDescription: type: string description: Sharing description of the resource maxLength: 400 sharingDescriptionHtml: type: string description: | HTML version of sharing description with rich text formatting. Supports safe HTML tags: p, br, strong, b, em, i, u, a. maxLength: 10000 resource: $ref: '#/components/schemas/EduResourceAssignmentCreation' EduResourceAssignmentCreation: description: | Assignment-specific creation options. Only applicable when creating a resource with `type: assignment`. If `type` is not provided, defaults to `none`. type: object properties: type: $ref: '#/components/schemas/AssignmentType' EduResourceUpdate: description: Update of an education resource type: object properties: title: type: string description: Title of the resource maxLength: 1000 minLength: 1 sharingDescription: type: string description: Sharing description of the resource maxLength: 400 sharingDescriptionHtml: type: string description: | HTML version of sharing description with rich text formatting. Supports safe HTML tags: p, br, strong, b, em, i, u, a. maxLength: 10000 privacy: $ref: '#/components/schemas/EduResourcePrivacy' subjects: $ref: '#/components/schemas/EduResourceSubjects' grades: $ref: '#/components/schemas/EduResourceGrades' EduResourceType: description: Type of an education resource type: string enum: - assignment - folder EduResourceFolder: description: Education resources folder type: object properties: title: type: string description: Title of the folder assignmentsTypes: description: The assignment type of the resources that are included in the folder, type: array items: $ref: '#/components/schemas/AssignmentType' resourcesCount: description: The number of resources inside the folder type: number EduResourceMove: description: Move an education resource type: object required: - destination properties: destination: type: string description: | Unique identifier of the destination of the folder where to move this resource. This can also be `root` to move the resource at the root of the user resource library. EduResourceCopy: description: Copy an education resource type: object required: - destination properties: destination: type: string description: | Unique identifier of the destination of the folder where to copy this resource. This can also be `root` to copy the resource at the root of the user resource library. EduResourceLtiLink: description: LTI Link details for the class type: object required: - ltiUrl properties: ltiUrl: type: string description: An URL that can be used to launch LTI with this resource in a classroom. EduResourceSubjects: description: The subjects of this resource, or the subjects of the resources included in the folder type: array items: $ref: '#/components/schemas/TeachingTheme' EduResourceGrades: description: The grades of this resource, or the grades of the resources included in the folder. type: array items: $ref: '#/components/schemas/Grade' GroupCreation: type: object properties: type: type: string enum: - classStudentsSubGroup description: Type of group (currently only classStudentsSubGroup is supported) classroom: type: string description: Classroom ID name: type: string description: | Name of the group (optional - auto-generated if not provided). **Special names:** * `edu:testing-students`: Creates a group tagged for test student accounts. The display name will be localized (e.g., "Test Students") and the group will be tagged with `edu:testing-students`. members: type: array description: Array of student IDs to add to the group items: type: string required: - type - classroom Group: type: object properties: id: type: string description: The unique identifier of the group name: type: string description: The display name of the group type: $ref: '#/components/schemas/GroupType' usersCount: type: number description: The number of users in this group readOnly: type: boolean description: | `True` if the group is set in read-only organization: type: string description: | If the group is related to an organization, this field will contain the unique identifier of the organization creationDate: type: string description: The creation date of the group format: date-time description: A group of users example: id: '0000000000000000000000043' name: 5th grade type: classTeachers userCount: 24 readOnly: true organization: '0000000000000000000000042' GroupDetails: type: object required: - id - name - type - creationDate - usersCount - readOnly - tags properties: id: type: string description: The unique identifier of the group name: type: string description: The displayable name of the group type: $ref: '#/components/schemas/GroupType' organization: type: string description: The unique identifier of the Organization owning the group classroom: type: string description: The unique identifier of the classroom owning the group. Only available for groups of type 'classromStudentsSubGroup' or 'assignmentStudentsSubGroup' assignment: type: string description: The unique identifier of the assignment owning the group. Only available for groups of type 'assignmentStudentsSubGroup'. parent: type: string description: The unique identifier of the parent class group. Only available for groups of type 'assignmentStudentsSubGroup'. May be null if the parent class group was deleted. creationDate: type: string description: The date when the group was create format: date-time usersCount: type: number description: The number of students in this group readOnly: type: boolean description: | `true` if the properties and members of this group are in in read-only tags: type: array description: | Tags for categorizing groups. * `edu:testing-students`: Marks this group as containing test student accounts items: type: string description: The details of a group example: id: 58c4955c226ffff257211a00 name: 5th Grade - Teachers type: classTeachers organization: '0000000000000000000000042' usersCount: 2 readOnly: false GroupType: type: string description: | The type of the group: * `generic`: A group created by a Flat user * `classTeachers`: A group created automaticaly by Flat that contains the teachers of a class * `classStudents`: A group created automaticaly by Flat that contains the studnets of a class * `classStudentsSubGroup`: Manually created sub-group of students of a class. * `assignmentStudentsSubGroup`: Manually created Sub-group of students of a class, in relation to a specific assignment. enum: - generic - classTeachers - classStudents - classStudentsSubGroup - assignmentStudentsSubGroup LtiCredentialsCreation: required: - lms - name type: object properties: name: maxLength: 300 type: string description: Name of the couple of credentials lms: $ref: '#/components/schemas/LmsName' description: Creation of a couple of LTI 1.x OAuth credentials example: name: My couple of credentials for Canvas lms: canvas LtiCredentials: type: object properties: id: type: string description: The unique identifier of this couple of credentials name: type: string description: Name of the couple of credentials lms: $ref: '#/components/schemas/LmsName' organization: type: string description: The unique identifier of the Organization associated to these credentials creator: type: string description: Unique identifier of the user who created these credentials creationDate: type: string description: The creation date of thse credentials format: date-time lastUsage: type: string description: The last time these credentials were used format: date-time consumerKey: type: string description: OAuth 1 Consumer Key consumerSecret: type: string description: OAuth 1 Consumer Secret enableEmailMatching: type: boolean default: true description: | Enable email-based user matching during LTI authentication. When true (default): If a user with the same email exists in the organization, they will be matched and logged in instead of creating a new account. When false: Email matching is disabled. Only LTI ID matching is used, which means multiple LTI users can share the same email address and have separate Flat accounts. This is useful for cases like siblings sharing a parent email in the LMS. description: A couple of LTI 1.x OAuth credentials example: id: 59368be5c66caf895ee02387 name: My couple of credentials for Canvas lms: canvas organization: 5832c801a4bedc05f4fb4993 creator: 5832bf149995c4024bd6de7d consumerKey: 200082F5-FAFD-4C6E-BB19-7DAB5D6264D4 consumerSecret: ABCDE1234 enableEmailMatching: true LtiConfiguration: description: LTI configuration details (unified 1.1 and 1.3) oneOf: - $ref: '#/components/schemas/LtiConfiguration1p1' - $ref: '#/components/schemas/LtiConfiguration1p3' discriminator: propertyName: ltiVersion mapping: 1p1: '#/components/schemas/LtiConfiguration1p1' 1p3: '#/components/schemas/LtiConfiguration1p3' LtiConfigurationBase: type: object properties: id: type: string description: Configuration ID ltiVersion: type: string enum: - 1p1 - 1p3 description: LTI version organizationId: type: string description: Organization ID organizationName: type: string description: Organization name creatorId: type: string description: ID of the user who created this configuration creationDate: type: string format: date-time description: Configuration creation date lastUsedDate: type: string format: date-time nullable: true description: Last time this configuration was used status: type: string description: Configuration status indicator enum: - ready-to-use - in-use - incomplete-setup required: - id - ltiVersion - creationDate LtiConfiguration1p1: allOf: - $ref: '#/components/schemas/LtiConfigurationBase' - type: object properties: ltiVersion: type: string enum: - 1p1 description: LTI version (1.1) consumerKey: type: string description: LTI 1.1 consumer key consumerSecret: type: string description: LTI 1.1 consumer secret (only included for admins) lms: type: string description: LMS type name: type: string description: Configuration name tool: type: object description: Platform/tool product information properties: product: type: string description: Product family code (e.g., canvas, moodle, schoology) version: type: string description: Platform version string instanceName: type: string description: Instance display name instanceGuid: type: string description: Unique instance identifier instanceContact: type: string description: Contact email or handle for the instance instanceDomain: type: string description: Instance root domain LtiConfiguration1p3: allOf: - $ref: '#/components/schemas/LtiConfigurationBase' - type: object properties: ltiVersion: type: string enum: - 1p3 description: LTI version (1.3) oneOf: - $ref: '#/components/schemas/LtiConfiguration1p3Manual' - $ref: '#/components/schemas/LtiConfiguration1p3Deployment' - $ref: '#/components/schemas/LtiConfiguration1p3Dynamic' discriminator: propertyName: mode mapping: 1p3-manual: '#/components/schemas/LtiConfiguration1p3Manual' 1p3-deployment: '#/components/schemas/LtiConfiguration1p3Deployment' 1p3-dynamic: '#/components/schemas/LtiConfiguration1p3Dynamic' LtiConfiguration1p3Base: type: object properties: mode: type: string enum: - 1p3-manual - 1p3-deployment - 1p3-dynamic description: LTI 1.3 configuration mode platformIss: type: string description: Platform issuer URL platformName: type: string description: Platform display name clientId: type: string description: OAuth2 client_id allocated by the platform deploymentId: type: string description: Deployment ID linking the tool to a tenant/class (varies by platform) accessTokenUrl: type: string format: url description: OAuth2 token endpoint (for AGS/NRPS) authorizationUrl: type: string format: url description: OIDC authorization/login endpoint jwksUrl: type: string format: url description: Platform JWKS endpoint (public keys) deploymentMode: type: string enum: - single - multi description: Deployment mode (single for organization-specific, multi for shared parent platforms) supportedServices: type: object description: LTI services support information properties: ags: type: object description: Assignment and Grade Services support properties: available: type: boolean description: Whether AGS claims were detected in launches from this platform version: type: string description: AGS version supported (e.g., "2.0") enabled: type: boolean description: Whether we have AGS enabled for this platform lineitemsUrl: type: string description: Base URL for line items operations as provided by the platform nrps: type: object description: Names and Role Provisioning Services support properties: available: type: boolean description: Whether NRPS claims were detected in launches from this platform version: type: string description: NRPS version supported (e.g., "2.0") enabled: type: boolean description: Whether we have NRPS enabled for this platform deepLinking: type: object description: Deep Linking support properties: available: type: boolean description: Whether Deep Linking claims were detected in launches from this platform version: type: string description: Deep Linking version supported (e.g., "2.0") tool: type: object description: Platform/tool product information properties: product: type: string description: Product family code (e.g., canvas, moodle, schoology) version: type: string description: Platform version string instanceName: type: string description: Instance name (e.g., 'My University Canvas') instanceGuid: type: string description: Unique instance identifier instanceContact: type: string description: Contact email or handle for the instance instanceDomain: type: string description: Instance root domain publicKeysetUrl: type: string description: Public keyset URL for the platform to retrieve Flat's public keys initiateLoginUrl: type: string description: URL for the platform to initiate LTI login redirectUris: type: array items: type: string description: Redirect URI for LTI launches description: Allowed redirect URIs for LTI launches enableEmailMatching: type: boolean default: true description: | Enable email-based user matching during LTI authentication. When true (default): If a user with the same email exists in the organization, they will be matched and logged in instead of creating a new account. When false: Email matching is disabled. Only LTI ID matching is used, which means multiple LTI users can share the same email address and have separate Flat accounts. This is useful for cases like siblings sharing a parent email in the LMS. LtiConfiguration1p3Manual: allOf: - $ref: '#/components/schemas/LtiConfiguration1p3Base' - type: object properties: mode: type: string enum: - 1p3-manual description: Manual LTI 1.3 configuration mode LtiConfiguration1p3Deployment: allOf: - $ref: '#/components/schemas/LtiConfiguration1p3Base' - type: object properties: mode: type: string enum: - 1p3-deployment description: Deployment-based LTI 1.3 configuration mode parentId: type: string description: Parent configuration ID (for deployment-based configs) deploymentKey: type: string description: Deployment key (e.g., schoology, classlink) deploymentBreakdownBy: type: string description: Custom claim used for tenant identification (parent platforms only, read-only) deploymentBreakdownId: type: string description: Value of the custom claim that identifies this specific tenant (child platforms only) required: - deploymentId LtiConfiguration1p3Dynamic: allOf: - $ref: '#/components/schemas/LtiConfiguration1p3Base' - type: object properties: mode: type: string enum: - 1p3-dynamic description: Dynamic registration LTI 1.3 configuration mode registrationToken: type: string description: Only included for admins registrationUrl: type: string format: url description: Dynamic registration URL (only included for admins when available) registrationTokenUsed: type: boolean description: Whether dynamic registration token has been used registrationCompletionDate: type: string format: date-time nullable: true description: Date when dynamic registration completed (null when not completed) LtiConfigurationCreate: description: Request to create a new LTI configuration (unified 1.1 and 1.3) oneOf: - $ref: '#/components/schemas/LtiConfigurationCreate1p1' - $ref: '#/components/schemas/LtiConfigurationCreate1p3Dynamic' - $ref: '#/components/schemas/LtiConfigurationCreate1p3Deployment' - $ref: '#/components/schemas/LtiConfigurationCreate1p3Manual' discriminator: propertyName: mode mapping: 1p1-manual: '#/components/schemas/LtiConfigurationCreate1p1' 1p3-dynamic: '#/components/schemas/LtiConfigurationCreate1p3Dynamic' 1p3-deployment: '#/components/schemas/LtiConfigurationCreate1p3Deployment' 1p3-manual: '#/components/schemas/LtiConfigurationCreate1p3Manual' LtiConfigurationCreate1p1: type: object required: - mode description: LTI 1.1 manual configuration creation properties: mode: type: string enum: - 1p1-manual description: LTI 1.1 manual creation mode name: type: string description: Display name for LTI 1.1 credentials lms: type: string description: LMS identifier for LTI 1.1 credentials LtiConfigurationCreate1p3Dynamic: type: object required: - mode description: LTI 1.3 dynamic registration configuration creation properties: mode: type: string enum: - 1p3-dynamic description: LTI 1.3 dynamic registration mode platformInfo: type: object description: Optional platform information for dynamic registration properties: name: type: string description: Platform display name url: type: string description: Optional platform homepage or admin URL for reference locale: type: string description: Optional locale code for registration URL. Input values will be automatically normalized to a supported locale code. LtiConfigurationCreate1p3Deployment: type: object required: - mode - deploymentType - deploymentId description: LTI 1.3 deployment-based configuration creation properties: mode: type: string enum: - 1p3-deployment description: LTI 1.3 deployment-based creation mode deploymentType: type: string description: Parent platform key (e.g., canvas, blackboard, schoology, classlink) deploymentId: type: string description: Deployment identifier provided by the platform clientId: type: string description: OAuth2 client_id for the tenant; required for ClassLink deployments deploymentBreakdownId: type: string description: Value of the custom claim that identifies this specific tenant (for multi-tenant platforms like Schoology) LtiConfigurationCreate1p3Manual: type: object required: - mode description: LTI 1.3 manual configuration creation properties: mode: type: string enum: - 1p3-manual description: LTI 1.3 manual creation mode platformIss: type: string description: Platform issuer URL platformName: type: string description: Platform display name clientId: type: string description: OAuth2 client_id allocated by the platform deploymentId: type: string description: Deployment identifier provided by the platform accessTokenUrl: type: string format: url description: Platform access token endpoint URL authorizationUrl: type: string format: url description: Platform OIDC authorization endpoint URL jwksUrl: type: string format: url description: Platform JWKS endpoint URL for public keys enableEmailMatching: type: boolean description: Enable email-based user matching during LTI authentication LtiConfigurationUpdate: description: Update an existing LTI 1.3 configuration (deployment clone or standalone) anyOf: - $ref: '#/components/schemas/LtiConfigurationUpdateDeployment' - $ref: '#/components/schemas/LtiConfigurationUpdateStandalone' LtiConfigurationUpdateDeployment: type: object description: Update fields allowed for deployment-based configurations properties: deploymentId: type: string description: Deployment identifier provided by the platform deploymentBreakdownId: type: string description: Specific tenant identifier for multi-tenant platforms enableEmailMatching: type: boolean description: Enable email-based user matching during LTI authentication LtiConfigurationUpdateStandalone: type: object description: Update fields allowed for standalone (manual/dynamic) configurations properties: deploymentId: type: string description: Deployment identifier provided by the platform platformIss: type: string description: Platform issuer URL platformName: type: string description: Platform display name clientId: type: string description: OAuth2 client_id allocated by the platform accessTokenUrl: type: string format: url description: Platform access token endpoint URL authorizationUrl: type: string format: url description: Platform OIDC authorization endpoint URL jwksUrl: type: string format: url description: Platform JWKS endpoint URL for public keys enableEmailMatching: type: boolean description: Enable email-based user matching during LTI authentication MicrosoftGraphSubmission: type: object description: A Microsoft Teams submission required: - id - state properties: id: type: string description: Identifier of the submission assigned by Microsoft Teams state: type: string description: State of the submission example: id: 8e460d32-d2d4-46b3-8e1a-9b7677a48fda state: returned TutteoProduct: description: | A Tutteo product. * `flat`: [Flat](https://flat.io) - Music notation software for individual users * `flatEdu`: [Flat for Education](https://flat.io/edu) - Music notation software for schools and educators * `msnippet`: [Music Snippet](https://musicsnippet.com) - Embeddable music snippets for websites * `embed`: [Flat Embed](https://flat.io/developers/embed) - Embeddable music notation editor type: string default: flat enum: - flat - flatEdu - msnippet - embed LicenseMode: type: string description: Mode of the license enum: - credit - site LicenseSources: type: string description: Source of the license default: order enum: - order - trial - voucher - distributor - subscription - appStore - playStore - musicfirst ResourceRights: type: object required: - aclRead - aclWrite - aclAdmin properties: aclRead: type: boolean default: false description: | `True` if the current user can read the current document aclWrite: type: boolean default: false description: | `True` if the current user can modify the current document. If this is a right of a Collection, the capabilities of the associated user can be lower than this permission, check out the `capabilities` property as the end-user to have the complete possibilities with the collection. aclAdmin: type: boolean default: false description: | `True` if the current user can manage the current document (i.e. share, delete) If this is a right of a Collection, the capabilities of the associated user can be lower than this permission, check out the `capabilities` property as the end-user to have the complete possibilities with the collection. isCollaborator: type: boolean default: false description: | `True` if the current user is a collaborator of the current document (direct or via group). collaboratorType: type: string enum: - owner - user - group description: | The type of the collaborator for the resource description: The rights of the current user on a score or collection example: aclRead: true aclWrite: true aclAdmin: true isCollaborator: true ResourceCollaborator: description: | A collaborator of a score. The `userEmail` and `group` are only available if the requesting user is a collaborator of the related score (in this case these permissions will eventualy not be listed and exposed publicly). allOf: - $ref: '#/components/schemas/ResourceRights' - type: object properties: id: type: string description: The unique identifier of the permission date: type: string format: date-time description: The date when the permission was added score: type: string description: If this object is a permission of a score, this property will contain the unique identifier of the score collection: type: string description: If this object is a permission of a collection, this property will contain the unique identifier of the collection user: $ref: '#/components/schemas/UserPublic' group: $ref: '#/components/schemas/Group' userEmail: type: string description: | If the collaborator is not a user of Flat yet, this field will contain their email. invited: type: boolean description: | If this property is `true`, this is still a pending invitation ResourceCollaboratorCreation: type: object properties: user: type: string description: The unique identifier of a Flat user group: type: string description: The unique identifier of a Flat group userEmail: type: string description: | Fill this field to invite an individual user by email. userToken: type: string description: | Token received in an invitation to join the score. aclRead: type: boolean description: | `True` if the related user can read the score. (probably true if the user has a permission on the document). default: true aclWrite: type: boolean description: | `True` if the related user can modify the score. default: false aclAdmin: type: boolean description: | `True` if the related user can can manage the current document, i.e. changing the document permissions and deleting the document default: false description: Add a collaborator to a resource. example: userEmail: jdoe@flat.io aclRead: true aclWrite: true aclAdmin: false LmsName: type: string description: LMS name enum: - canvas - moodle - schoology - blackboard - desire2learn - sakai - schoolbox - other MediaAttachment: type: object required: - type properties: type: type: string description: | The type of the assignment resolved: * `rich`, `photo`, `video` are automatically resolved as `link` * A `flat` attachment is a score document where the unique identifier will be specified in the `score` property. Its sharing mode will be provided in the `sharingMode` property. enum: - rich - photo - video - link - flat - googleDrive - worksheet score: type: string description: An unique Flat score identifier revision: type: string description: An unique revision identifier of a score worksheet: type: string description: An unique worksheet identifier dedicated: type: boolean description: True if the resource is dedicated for the assignment (for scores and worksheets), meaning on the user-side this one is stored in the assignment track: type: string description: A unique track identifier partUuid: type: string description: The UUID of the instrument part selected for this attachment (for performance submissions) sharingMode: $ref: '#/components/schemas/MediaScoreSharingMode' lockScoreTemplate: type: boolean description: To be used with a score attached in `sharingMode` `copy` (score used as template). If true, students won't be able to change the original notes of the template. title: type: string description: The resolved title of the attachment description: type: string description: The resolved description of the attachment html: type: string description: | If the attachment type is `rich` or `video`, the HTML code of the media to display htmlWidth: type: number description: If the `html` is available, the width of the widget htmlHeight: type: number description: If the `html` is available, the height of the widget url: type: string description: The url of the attachment thumbnailUrl: type: string description: | If the attachment type is `rich`, `video`, `photo` or `link`, a displayable thumbnail for this attachment thumbnailWidth: type: integer description: | If the `thumbnailUrl` is available, the width of the thumbnail thumbnailHeight: type: integer description: | If the `thumbnailUrl` is available, the width of the thumbnail authorName: type: string description: The resolved author name of the attachment authorUrl: type: string description: The resolved author url of the attachment iconUrl: type: string description: The URL of the icon mimeType: type: string description: The mine type of the file googleDriveFileId: type: string description: The ID of the Google Drive File teacherOnly: type: boolean description: | If true, this attachment is only visible to teachers. When students view the assignment, attachments with this flag will be filtered out. default: false description: | Media attachment. The API will automatically resolve the details, oEmbed, and media available if possible and return them in this object example: type: video url: https://www.youtube.com/watch?v=SNbRUiBZ4Uw title: Flat - The online collaborative music notation software description: Discover Flat on https://flat.io html: thumbnailUrl: https://i.ytimg.com/vi/SNbRUiBZ4Uw/maxresdefault.jpg thumbnailHeight: 1052 thumbnailWidth: 1868 authorName: Flat authorUrl: https://www.youtube.com/channel/UCEUIbEP9Rba_g0r4eeGhmXw TeachingTheme: type: string description: Teaching theme enum: - composition - music-theory - general-music - band - choir - orchestra - jazz-ensemble - music-technology - other Grade: type: string description: Class grade of the resource enum: - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' - '11' - '12' - university OrganizationRoles: type: string description: User's Organization Role (for Edu users only) enum: - admin - accountAdmin - teacher - user OrganizationInvitationCreation: type: object properties: email: type: string description: The email address you want to send the invitation to organizationRole: type: string description: User's Organization Role default: teacher enum: - admin - teacher - accountAdmin description: The parameters to create an organization invitation example: email: edu@flat.io organizationRole: teacher OrganizationInvitation: type: object required: - organization - organizationRole - customCode - allowMultipleUse properties: id: type: string description: The invitation unique identifier creationDate: type: string description: The creation date of the invitation format: date-time organization: type: string description: The unique identifier of the Organization owning this class organizationRole: $ref: '#/components/schemas/OrganizationRoles' customCode: type: string nullable: true description: Enrollment code to use when joining this organization email: type: string description: The email address this invitation was sent to invitedBy: type: string description: The unique identifier of the User who created this invitation htmlUrl: type: string description: URL to join the organization using this invitation allowMultipleUse: type: boolean description: | If true, the invitation can be used multiple times. If false, the invitation can only be used once. usedBy: type: array description: List of users who used this invitation items: type: string description: Details of an invitation to join an organization example: customCode: code email: edu@flat.io id: 59590bab53b1af260610000 invitedBy: 55b8d8f395c8db031ed00000 organization: 55df29a6694e4a3953100000 htmlUrl: https://school.flat.io/organization/enroll?enrollcode=code organizationRole: teacher ScoreSummary: type: object required: - id - title - privacy - user - htmlUrl properties: id: type: string description: The unique identifier of the score sharingKey: type: string description: The private sharing key of the score (available when the `privacy` mode is set to `privateLink`) title: type: string description: The title of the score privacy: $ref: '#/components/schemas/ScorePrivacy' user: $ref: '#/components/schemas/UserPublic' htmlUrl: type: string description: The url where the score can be viewed in a web browser format: url description: A summary of the score details example: id: '000000000000000000000000' title: My score privacy: private user: id: '000000000000000000000001' username: flat name: Flat Team printableName: Flat Team picture: https://flat.io/img/logo_flat.svg htmlUrl: https://flat.io/score/000000000000000000000000 ScoreLicense: type: string nullable: true description: | License of the creation. Read more about the Creative Commons licenses on https://creativecommons.org/licenses/ enum: - copyright - cc0 - cc-by - cc-by-sa - cc-by-nd - cc-by-nc - cc-by-nc-sa - cc-by-nc-nd - null ScoreCreationType: type: string nullable: true description: The type of creation (an orginal, an arrangement) enum: - original - arrangement - other - null ScoreDetails: description: The score and all its details allOf: - $ref: '#/components/schemas/ScoreSummary' - type: object required: - creationDate - collaborators - instruments - instrumentsNames - samples - editHtmlUrl properties: editHtmlUrl: type: string description: The url where the score can be edited in a web browser format: url subtitle: type: string description: Subtitle of the score lyricist: type: string description: Lyricist of the score arranger: type: string description: Arranger of the score composer: type: string description: Composer of the score description: type: string description: Description of the creation tags: type: array description: Tags describing the score items: pattern: ^[a-zA-Z0-9]{1,30}$ type: string creationType: $ref: '#/components/schemas/ScoreCreationType' license: $ref: '#/components/schemas/ScoreLicense' licenseText: type: string description: Additional license text written on the exported/printed score durationTime: type: number description: In seconds, an approximative duration of the score numberMeasures: type: integer description: The number of measures in the score mainTempoQpm: type: number description: The main tempo of the score (in QPM) mainKeySignature: type: number description: The main key signature of the score (expressed between -7 and 7). rights: $ref: '#/components/schemas/ResourceRights' collaborators: type: array description: The list of the collaborators of the score items: $ref: '#/components/schemas/ResourceCollaborator' creationDate: type: string description: The date when the score was created format: date-time modificationDate: type: string description: The date of the last revision of the score format: date-time publicationDate: type: string description: The date when the score was published on Flat format: date-time scheduledDeletionDate: type: string description: | The date when the score will be definitively deleted. This date can be in the past if the score will be deleted at the next deletion batch, in this case you can display something like "Deleted shortly". Schedule: * For all paying users, the scores will be definitively deleted after 90 days. * For free users, the scores are no longer available after 24 hours, an can be restored with a paying account up to 90 days. format: date-time highlightedDate: type: string description: The date when the score was highlighted (featured) on our community format: date-time organization: type: string description: | If the score has been created in an organization, the identifier of this organization. This property is especially used with the score privacy `organizationPublic`. parentScore: type: string description: | If the score has been forked, the unique identifier of the parent score. instruments: type: array items: type: string description: | An array of the instrument identifiers used in the last version of the score. This is mainly used to display a list of the instruments in the Flat's UI or instruments icons. The format of the strings is `{instrument-group}.{instrument-id}`. instrumentsNames: type: array items: type: string description: | An array of the instrument names used in the last version of the score. This list is localized and ready-to-display and will match the indexes from the `instruments` list. samples: type: array items: type: string description: | An array of the audio samples identifiers used the different score parts. The format of the strings is `{instrument-group}.{sample-id}`. googleDriveFileId: type: string description: | If the user uses Google Drive and the score exists on Google Drive, this field will contain the unique identifier of the Flat score on Google Drive. You can access the document using the url: `https://drive.google.com/open?id={googleDriveFileId}` likes: $ref: '#/components/schemas/ScoreLikesCounts' comments: $ref: '#/components/schemas/ScoreCommentsCounts' views: $ref: '#/components/schemas/ScoreViewsCounts' plays: $ref: '#/components/schemas/ScorePlaysCounts' collections: type: array description: The List of parent collections, which includes all the collections this score is included. Please note that you might not have access to all of them. items: type: string me: type: object description: Information about the authenticated user and this score required: - isLiked - isInLibrary properties: isLiked: type: boolean description: True if the current user likes this score isInLibrary: type: boolean description: True if the score is stored in one of the user's collections ScorePrivacy: type: string default: private description: | The score main privacy mode. - `public`: The score is public on the Internet. This one can be accessible at the url `https://flat.io/score/{score}` and can be modified and administred by specified collaborators users. - `private`: The score is private and can be only accessed, modified and administred by specified collaborators users. - `privateLink`: The score is private but can be accessed using a private link `htmlUrl` or the private key in the property `sharingKey`. - `organizationPublic`: _Available only with [Flat for Education](https://flat.io/edu)._ The score is public in the organization: users of the same organization can access to this one. The score can be modified and administred by specified collaborators users. The score can also be individually shared to a set of users or groups using the different collaborators API methods. When a file is synchronized from an external source (e.g. Google Drive) and the sharing options are changed on the source, Flat will chose the best privacy mode for the file. When using a [Flat for Education](https://flat.io/edu) account, some of the modes may not be available if disabled by an administrator of the organization (e.g. by default the `public` mode is not available). enum: - public - private - organizationPublic - privateLink ScoreTrack: type: object required: - id - state - score - creator - default - type - creationDate - modificationDate - purpose properties: id: type: string description: The unique identifier of the score track title: type: string description: Title of the track score: type: string description: The unique identifier of the score creator: type: string description: The unique identifier of the track creator creationDate: type: string description: The creation date of the track format: date-time modificationDate: type: string description: The modification date of the track format: date-time default: type: boolean description: True if the track should be used as default audio source state: $ref: '#/components/schemas/ScoreTrackState' type: $ref: '#/components/schemas/ScoreTrackType' purpose: $ref: '#/components/schemas/ScoreTrackPurpose' url: type: string description: The URL of the track mediaId: type: string description: | The unique identifier of the track when hosted on an external service. For example, if the url is `https://www.youtube.com/watch?v=dQw4w9WgXcQ`, `mediaId` will be `dQw4w9WgXcQ` synchronizationPoints: type: array items: $ref: '#/components/schemas/ScoreTrackPoint' description: An audio track for a score ScoreTrackCreation: type: object properties: title: type: string description: Title of the track default: type: boolean description: True if the track should be used as default audio source state: $ref: '#/components/schemas/ScoreTrackState' purpose: $ref: '#/components/schemas/ScoreTrackPurpose' url: type: string description: The URL of the track synchronizationPoints: type: array items: $ref: '#/components/schemas/ScoreTrackPoint' description: | Creation of a new track. This one must contain the URL of the track or the corresponding file example: title: Rick Astley - Never Gonna Give You Up url: https://www.youtube.com/watch?v=dQw4w9WgXcQ default: true state: draft synchronizationPoints: - type: measure time: 0 measureUuid: 5132a788-69e6-d0c6-84ec-4bd858658d7c - type: end time: 213 ScoreTrackUpdate: type: object properties: title: type: string description: Title of the track default: type: boolean description: True if the track should be used as default audio source state: $ref: '#/components/schemas/ScoreTrackState' purpose: $ref: '#/components/schemas/ScoreTrackPurpose' synchronizationPoints: type: array items: $ref: '#/components/schemas/ScoreTrackPoint' description: | Update an existing track. example: title: Rick Astley - Never Gonna Give You Up url: https://www.youtube.com/watch?v=dQw4w9WgXcQ default: true state: draft synchronizationPoints: - type: measure time: 0 measureUuid: 5132a788-69e6-d0c6-84ec-4bd858658d7c - type: end time: 213 ScoreTrackPoint: required: - time - type type: object properties: type: type: string description: The type of the synchronization point. If the type is `measure`, the measure uuid must be present in `measureUuid` enum: - measure - end measureUuid: type: string description: The measure unique identifier format: uuid time: type: number description: The corresponding time in seconds description: A track synchronization point example: type: measure time: 0 measureUuid: 5132a788-69e6-d0c6-84ec-4bd858658d7c ScoreTrackType: type: string description: The type of an audio track enum: - audio - soundcloud - youtube - vimeo ScoreTrackPurpose: type: string description: The purpose of the audio track default: common enum: - common - performanceSubmission ScoreTrackState: type: string description: State of the track default: draft enum: - draft - completed - deleted ScoreLikesCounts: type: object properties: total: type: number description: The total number of likes of the score weekly: type: number description: The number of new likes during the last week monthly: type: number description: The number of new likes during the last month yearly: type: number description: The number of new likes during the last year description: | A computed version of the weekly, monthly, yearly and total number of likes for a score example: total: 500 weekly: 10 monthly: 30 yearly: 120 ScoreCommentsCounts: type: object properties: total: type: number description: The total number of comments added to the score unique: type: number description: The unique (1/user) number of comments added to the score weekly: type: number description: The weekly unique number of comments added to the score monthly: type: number description: The monthly unique number of comments added to the score yearly: type: number description: The yearly unique number of comments added to the score description: | A computed version of the total, unique, weekly, monthly and yearly number of comments added on the documents (this doesn't include inline comments). example: total: 500 unique: 35 weekly: 10 monthly: 30 yearly: 200 ScoreViewsCounts: type: object properties: total: type: number description: The total number of views of the score weekly: type: number description: The weekly number of views of the score monthly: type: number description: The monthly number of views of the score yearly: type: number description: The yearly number of views of the score description: | A computed version of the total, weekly, monthly, and yearly number of views of the score example: total: 42 weekly: 10 monthly: 30 yearly: 365 ScorePlaysCounts: type: object properties: total: type: number description: The total number of plays of the score weekly: type: number description: The weekly number of plays of the score monthly: type: number description: The monthly number of plays of the score yearly: type: number description: The yearly number of plays of the score description: | A computed version of the total, weekly, monthly, and yearly number of plays of the score example: total: 42 weekly: 10 monthly: 30 yearly: 400 ScoreRevisionStatistics: type: object properties: additions: type: number description: The number of additions operations in the last revision deletions: type: number description: The number of deletions operations in the last revision startDate: type: string format: date-time description: The date of the first action included in this revision endDate: type: string format: date-time description: The date of the latest action included in this revision description: | The statistics related to the score revision (additions and deletions) example: additions: 24 deletions: 5 ScoreSource: type: object properties: googleDrive: type: string description: | If the score is a file on Google Drive, this field property must contain its identifier. To use this method, the Drive file must be public or the Flat Drive App must have access to the file. example: googleDrive: 0B-0000000000000001 ScoreCreation: oneOf: - $ref: '#/components/schemas/ScoreCreationBuilderData' - $ref: '#/components/schemas/ScoreCreationFileImport' - $ref: '#/components/schemas/ScoreCreationGoogleDriveImport' ScoreCreationCommon: type: object properties: title: type: string description: | The title of the new score. If the title is too long, the API may trim this one. If this title is not specified, the API will try to (in this order): - Use the title contained in the file (e.g. [`movement-title`](https://usermanuals.musicxml.com/MusicXML/Content/EL-MusicXML-movement-title.htm) or [`credit-words`](https://usermanuals.musicxml.com/MusicXML/Content/EL-MusicXML-credit-words.htm) for [MusicXML](http://www.musicxml.com/) files). - Use the name of the file for files from a specified `source` (e.g. Google Drive) or the one in the `filename` property - Set a default title (e.g. "New Music Score") privacy: $ref: '#/components/schemas/ScorePrivacy' collection: type: string description: | Unique identifier of a collection where the score will be created. If no collection identifier is provided, the score will not be added to any collection and will only be visible in the `allScores` virtual collection. googleDriveFolder: type: string description: | If the user uses Google Drive and this properties is specified, the file will be created in this directory. The currently user creating the file must be granted to write in this directory. ScoreCreationFileImport: allOf: - $ref: '#/components/schemas/ScoreCreationCommon' - type: object required: - data properties: filename: type: string description: If this is an imported file, its filename data: type: string description: | The data of the score file. See the `POST /scores` endpoint description for the full list of supported formats. Binary payloads (e.g. compressed MusicXML, MIDI, Guitar Pro) can be encoded in Base64, in this case the `dataEncoding` property must match the encoding used for the API request. dataEncoding: type: string description: The optional encoding of the score data. This property must match the encoding used for the `data` property. enum: - base64 supportsTasks: type: boolean description: | Set this to `true` if the client supports asynchronous task flows. When importing a score that requires OMR processing (e.g., a PDF), the API will return a 202 Accepted response along with a task reference. The client can then check the task status using the endpoint `GET /v2/tasks/{task}`. description: A newly created score from an imported file example: title: My new score privacy: private data: ...[Your actual file will be provided in this property]... ScoreCreationGoogleDriveImport: allOf: - $ref: '#/components/schemas/ScoreCreationCommon' - type: object required: - source properties: source: $ref: '#/components/schemas/ScoreSource' description: A newly created score from a file from Google Drive example: title: My new score privacy: private source: googleDrive: 0B-0000000000000001 ScoreCreationBuilderData: allOf: - $ref: '#/components/schemas/ScoreCreationCommon' - type: object required: - title - builderData properties: builderData: type: object required: - scoreData properties: scoreData: required: - instruments type: object properties: useTabStaff: type: boolean description: true if the TAB staff is displayed with fretted instruments useChordGrid: type: boolean description: true if the chord grid must be displayed with fretted instruments fifths: type: number description: The key signature of the score (expressed between -7 and 7). Major C is used when the value is not provided. nbBeats: type: number description: The number of beats in the measure beatType: type: number description: The duration of a beat in the measure instruments: type: array description: | The list of instruments to add to the score. See https://prod.flat-cdn.com/fixtures/instruments_en.json for the possible values for `group` and `instrument`. items: required: - group - instrument type: object properties: group: type: string description: The of the instrument group (e.g. `keyboards`, `brass`) instrument: type: string description: The identifier of the instrument (e.g. `piano`, `trumpet`) longName: type: string description: The full name of the instrument shortName: type: string description: The abbreviation of the name of the instrument hasQuarterTone: type: boolean description: True if the part can use quarter tone (prevent the part to have a TAB/chord grid) layoutData: type: object description: Control the appearance of the score. If missing, default values are used. properties: notesSpacingCoeff: type: number description: A float value >= 1 that controls the spacing between notes. lengthUnit: description: The unit to use for layout customizations type: string default: cm enum: - cm - inch pageHeight: type: number description: The height of the page in chosen unit (`lengthUnit`). pageWidth: type: number description: The width of the page in chosen unit (`lengthUnit`). pageMarginTop: type: number description: The top margin of the page in chosen unit (`lengthUnit`). pageMarginBottom: type: number description: The bottom margin of the page in chosen unit (`lengthUnit`). pageMarginLeft: type: number description: The left margin of the page in chosen unit (`lengthUnit`). pageMarginRight: type: number description: The right margin of the page in chosen unit (`lengthUnit`). example: title: Violin and Piano privacy: private builderData: scoreData: fifths: 8 nbBeats: 2 beatType: 4 instruments: - group: strings instrument: hq-violin - group: strings instrument: hq-grand-piano shortName: Pno. longName: Super Piano layoutData: notesSpacingCoeff: 2 lengthUnit: cm pageHeight: 29.7 pageWidth: 21 pageMarginTop: 1.5 pageMarginBottom: 1.5 pageMarginLeft: 2.5 pageMarginRight: 2.5 ScoreFork: type: object properties: collection: type: string nullable: true description: | Unique identifier of a collection where the score will be copied. If no collection identifier is provided, a virtual collection is used, or `null` is provided, the score won't be added to any collection and will only be visible in the `allScores` virtual collection. googleDriveDisabled: type: boolean default: false description: | If set to `true`, the API won't create the score on Google Drive keepOriginalTitle: type: boolean description: | Option to keep the original title of the score (i.e. don't prepend it with "Copy of ", or add the student name in assignment usage). description: Options to fork the score ScoreModification: type: object properties: title: type: string description: The title of the score subtitle: type: string nullable: true description: The subtitle of the score composer: type: string nullable: true description: The composer of the score lyricist: type: string nullable: true description: The lyricist of the score arranger: type: string nullable: true description: The arranger of the score privacy: $ref: '#/components/schemas/ScorePrivacy' sharingKey: pattern: ^[a-f0-9]{128}$ type: string description: When using the `privacy` mode `privateLink`, this property can be used to set a custom sharing key, otherwise a new key will be generated. description: type: string maxLength: 2000 nullable: true description: Description of the creation tags: type: array description: Tags describing the score items: type: string creationType: $ref: '#/components/schemas/ScoreCreationType' license: $ref: '#/components/schemas/ScoreLicense' licenseText: type: string nullable: true description: The rights info written on the score description: Edit the score metadata example: privacy: private ScoreRevision: type: object required: - id - score - date properties: id: type: string description: The unique identifier of the revision. user: type: string description: The user identifier who created the revision score: type: string description: The score identifier collaborators: type: array items: type: string description: | The list of user identifier or collaborators who worked on this revision. This is list is built from the history of the revision specified during the creation of the revision. date: type: string description: The date when this revision was created format: date-time event: type: string description: The last event (action id) of the revision description: type: string description: A description associated to the revision autosave: type: boolean description: | True if this revision was automatically generated by Flat and not on purpose by the user. statistics: $ref: '#/components/schemas/ScoreRevisionStatistics' description: A score revision metadata example: user: '000000000000000000000020' collaborators: - '000000000000000000000010' - '000000000000000000000020' description: New revision autosave: true ScoreRevisionCreation: required: - data type: object properties: data: type: string description: | The data of the score file. It must be a MusicXML 3 file (`vnd.recordare.musicxml` or `vnd.recordare.musicxml+xml`), a MIDI file (`audio/midi`) or a Flat.json (aka Adagio.json) file. Binary payloads (`vnd.recordare.musicxml` and `audio/midi`) can be encoded in Base64, in this case the `dataEncoding` property must match the encoding used for the API request. example: dataEncoding: type: string description: The optional encoding of the score data. This property must match the encoding used for the `data` property. enum: - base64 autosave: type: boolean description: | Must be set to `true` if the revision was created automatically. description: type: string description: A description associated to the revision description: A new created revision example: data: history: - id: b278ad43-2e99-4e60-a782-ac119b294ab8 userId: '000000000000000000000010' fnc: action.AddMeasure args: previousUuid: 888cb742-2110-a050-ba71-28300ba6d61f measureUuid: 0be9f739-3213-f312-bb0a-00ad0c787ef7 autosave: true description: New revision ScoreCommentContext: required: - measureUuids - partUuid - startDpq - startTimePos - stopDpq - stopTimePos type: object properties: partUuid: type: string description: The unique identifier (UUID) of the score part staffIdx: type: number description: (Deprecated, use `staffUuid`) The identififer of the staff deprecated: true staffUuid: type: string description: The unique identififer (UUID) of the staff measureUuids: type: array description: The list of measure UUIds items: type: string startTimePos: type: number stopTimePos: type: number startDpq: type: number stopDpq: type: number description: | The context of the comment (for inline/contextualized comments). A context will include all the information related to the location of the comment (i.e. score parts, range of measure, time position). example: partUuid: 91982db7-2e6d-285e-7a19-76b4bd005b8b staffUuid: 9395d8f3-f42b-47b6-8c5d-6ba704961ec0 measureUuids: - e6a6a60b-8710-f819-9a49-e907b19c6f1f - da83d93c-e3a6-3c73-1bbe-15e5131d6437 - 056ec5eb-9213-df56-6ae8-d9b99673dc48 startDpq: 1 stopDpq: 1 startTimePos: 2 stopTimePos: 3 ScoreCommentCreation: required: - comment type: object properties: revision: type: string description: | The unique identifier of the revision of the score where the comment was added. If this property is unspecified or contains "last", the API will automatically take the last revision created. comment: type: string description: | The comment text that can includes mentions using the following format: `@[id:username]`. rawComment: type: string description: | A raw version of the comment, that can be displayed without the mentions. If you use mentions, this property must be set. mentions: type: array description: The list of user identifiers mentioned in this comment items: type: string replyTo: type: string description: | When the comment is a reply to another comment, the unique identifier of the parent comment context: $ref: '#/components/schemas/ScoreCommentContext' description: Creation of a comment example: revision: '000000000000000000000010' comment: '@[000000000000000000000000:flat] Great work!' rawComment: '@flat: Great work!' mentions: - '000000000000000000000000' replyTo: '000000000000000000000000' context: partUuid: 91982db7-2e6d-285e-7a19-76b4bd005b8b staffUuid: 9395d8f3-f42b-47b6-8c5d-6ba704961ec0 measureUuids: - e6a6a60b-8710-f819-9a49-e907b19c6f1f - da83d93c-e3a6-3c73-1bbe-15e5131d6437 - 056ec5eb-9213-df56-6ae8-d9b99673dc48 startDpq: 1 stopDpq: 1 startTimePos: 2 stopTimePos: 3 ScoreCommentUpdate: type: object properties: revision: type: string description: | The unique identifier of the revision of the score where the comment was added. If this property is unspecified or contains "last", the API will automatically take the last revision created. comment: maxLength: 10000 minLength: 1 type: string description: | The comment text that can includes mentions using the following format: `@[id:username]`. rawComment: maxLength: 10000 minLength: 1 type: string description: | A raw version of the comment, that can be displayed without the mentions. If you use mentions, this property must be set. context: $ref: '#/components/schemas/ScoreCommentContext' description: Update of a comment example: revision: '000000000000000000000011' comment: '@[000000000000000000000000:flat] Great work!' rawComment: '@flat: Great work!' mentions: - '000000000000000000000000' replyTo: '000000000000000000000000' context: partUuid: 91982db7-2e6d-285e-7a19-76b4bd005b8b staffUuid: 9395d8f3-f42b-47b6-8c5d-6ba704961ec0 measureUuids: - e6a6a60b-8710-f819-9a49-e907b19c6f1f - da83d93c-e3a6-3c73-1bbe-15e5131d6437 - 056ec5eb-9213-df56-6ae8-d9b99673dc48 startDpq: 1 stopDpq: 1 startTimePos: 2 stopTimePos: 3 ScoreComment: type: object required: - id - type - user - score - comment - rawComment - date properties: id: type: string description: The comment unique identifier type: type: string description: The type of the comment enum: - document - inline user: type: string description: The author unique identifier score: type: string description: The unique identifier of the score where the comment was posted revision: type: string description: The unique identifier of revision the comment was posted replyTo: type: string description: | When the comment is a reply to another comment, the unique identifier of the parent comment date: type: string description: The date when the comment was posted format: date-time modificationDate: type: string description: The date of the last comment modification format: date-time comment: type: string description: | The comment text that can includes mentions using the following format: `@[id:username]`. rawComment: type: string description: | A raw version of the comment, that can be displayed without parsing the mentions. context: $ref: '#/components/schemas/ScoreCommentContext' mentions: type: array description: The list of user identifier mentioned on the score items: type: string resolved: type: boolean description: | For inline comments, the comment can be marked as resolved and will be hidden in the future responses resolvedBy: type: string description: | If the user is marked as resolved, this will contain the unique identifier of the User who marked this comment as resolved moderation: type: object description: Information about the comment being moderated properties: hidden: type: boolean description: If true, this comment will be hidden from other users reason: type: string description: If the comment is hidden, the reason why this one has been moderated enum: - spam - inappropriate spam: type: boolean description: | `true if the message has been detected as spam and hidden from other users description: Comment added on a sheet music example: id: '000000000000000000000010' type: inline user: '000000000000000000000001' score: '000000000000000000000042' revision: '000000000000000000000011' replyTo: '000000000000000000000000' comment: '@[000000000000000000000000:flat] Great work!' rawComment: '@flat: Great work!' context: partUuid: 91982db7-2e6d-285e-7a19-76b4bd005b8b staffUuid: 9395d8f3-f42b-47b6-8c5d-6ba704961ec0 measureUuids: - e6a6a60b-8710-f819-9a49-e907b19c6f1f - da83d93c-e3a6-3c73-1bbe-15e5131d6437 - 056ec5eb-9213-df56-6ae8-d9b99673dc48 startDpq: 1 stopDpq: 1 startTimePos: 2 stopTimePos: 3 mentions: - '000000000000000000000000' resolved: true resolvedBy: '000000000000000000000000' spam: false MediaScoreSharingMode: type: string description: The sharing mode of the score for classes post and assignments default: read enum: - read - write - copy - performance TaskExportOptions: type: object properties: parts: type: array description: A list of parts to specifically export items: type: string description: | Options for the requested export example: parts: - 49b7d7c5-7490-4f76-9813-607f79e5b92b - 96b5066b-54ed-4c6b-b3fc-cb7281403a89 Task: type: object description: An asynchronous task required: - id - state properties: id: type: string description: Unique identifier of the task type: type: string description: | Type of the task: * `audio-export`: Exports a score to audio format (MP3, WAV) * `score-save`: Saves or updates a score document * `import-omr`: Processes a PDF through OMR (Optical Music Recognition) and imports it as a score state: type: string description: State of the Task enum: - created - blocked - doing - done - canceled - error format: type: string description: For files processing, the file format (e.g. `mp3`, `wav`) score: type: string description: The score unique identifier for tasks related to scores revision: type: string description: The score revision identifier for tasks related to scores progress: type: object description: Details about the task progression properties: percent: type: number description: Percent of the task progression text: type: string description: Text details of the task progress creationDate: type: string description: The creation date of the task format: date-time modificationDate: type: string description: The last modification date of the task format: date-time doneDate: type: string description: The date when the task has been completed format: date-time result: type: object description: Optional result information about this task properties: url: description: URL returned by the task worker type: string error: description: Error returned by task worker type: string errorHistory: type: array description: If any errors happened when processing this task, the list of errors identifiers items: type: string isCancellable: type: boolean description: | Whether the task can be canceled by the user. Only `true` when the task is in `created` state (waiting to be processed). readOnly: true children: type: array description: Child tasks for hierarchical task structures (e.g., conversion subtasks) items: $ref: '#/components/schemas/Task' UserBasics: type: object required: - id - type - product - username - picture properties: id: type: string description: The user unique identifier type: type: string description: The type of user account enum: - user - guest product: $ref: '#/components/schemas/TutteoProduct' username: type: string description: The user name (unique for the organization) printableName: type: string description: The name that can be directly printed (name, firstname & lastname, or username) firstname: type: string description: Firstname of the user (for education users) lastname: type: string description: Lastname of the user (for education users) name: type: string description: A displayable name for the user (for consumer users) picture: type: string nullable: true description: The URL of the picture to display badges: type: array description: | List of badges for the user profile: - `power` - `staff` - `composerOfTheMonth` - `ambassador` - `challenge` items: type: string description: Badge name example: id: '000000000000000000000001' username: flat name: Flat Team printableName: Flat Team picture: https://flat.io/img/logo_flat.svg badges: - power - staff UserPublicSummary: description: Public User details summary allOf: - $ref: '#/components/schemas/UserBasics' - type: object properties: organization: type: string description: Organization ID (for Edu users only) organizationRole: $ref: '#/components/schemas/OrganizationRoles' classRole: $ref: '#/components/schemas/ClassRoles' htmlUrl: type: string description: Link to user profile (for Indiv. users only) UserPublic: description: Public User details allOf: - $ref: '#/components/schemas/UserPublicSummary' - type: object properties: bio: type: string description: User's biography registrationDate: type: string description: Date the user signed up format: date-time likedScoresCount: type: integer description: Number of the scores liked by the user followersCount: type: integer description: Number of followers the user have followingCount: type: integer description: Number of people the user follow ownedPublicScoresCount: type: integer description: Number of public scores the user have allPublicScoresCount: type: integer description: Total number of public scores the user participates in (owned + joined) likesCount: type: integer description: Number of likes on the user published scores playsCount: type: integer description: Number of plays on the user published scores coverPicture: type: string description: Cover picture (backgroud) for the profile nullable: true profileTheme: type: string description: Theme (background) for the profile links: $ref: '#/components/schemas/UserCommunityProfileLinks' UserDetailsAdmin: description: User details (view for organization teacher / admin) allOf: - $ref: '#/components/schemas/UserPublicSummary' - type: object properties: email: type: string description: Email of the user format: email lastActivityDate: type: string description: Date of the last user activity format: date-time license: type: object properties: id: type: string description: ID of the current license expirationDate: type: string description: Date when the license expires format: date-time source: $ref: '#/components/schemas/LicenseSources' mode: $ref: '#/components/schemas/LicenseMode' active: type: boolean description: ID of the current license description: Current active license of the user groups: description: For Flat for Education accounts, list of Group identifiers the user is part of. type: array items: type: string description: Unique group identifier isEduTestingStudent: type: boolean description: | Indicates if the user account is marked as a testing student account. Testing students are typically excluded from certain educational integrations and workflows. This field helps API clients distinguish between regular students and testing accounts. UserCreation: required: - password - username type: object properties: username: maxLength: 30 minLength: 1 type: string description: Username of the new account firstname: maxLength: 60 type: string description: First name of the user lastname: maxLength: 60 type: string description: Last name of the user email: type: string description: Email of the new account format: email password: minLength: 6 maxLength: 1000 type: string description: Password of the new account format: password locale: description: User language. Input values will be automatically normalized to a supported locale code. type: string default: en role: description: Role of the new account type: string default: user enum: - user - teacher - admin description: User creation UserAdminUpdate: type: object properties: password: minLength: 6 maxLength: 1000 type: string description: Password of the account format: password organizationRole: $ref: '#/components/schemas/OrganizationRoles' username: maxLength: 30 minLength: 1 type: string description: Username of the account firstname: maxLength: 60 type: string description: First name of the user lastname: maxLength: 60 type: string description: Last name of the user email: type: string description: Email of the account format: email description: User update as an organization admin UserAzureDetails: type: object properties: oid: type: string description: User object identifier on Azure AD hd: type: string description: User tenant (domain name) preferredUsername: type: string description: User Preferred Username (UPN), i.e. the main email of the user UserDetails: description: User details allOf: - $ref: '#/components/schemas/UserPublic' - type: object properties: isEmailVerified: type: boolean description: Whether the user's email address has been verified azureDetails: $ref: '#/components/schemas/UserAzureDetails' privateProfile: type: boolean description: Tell either this user profile is private or not (individual accounts only) locale: $ref: '#/components/schemas/FlatLocalesString' groups: description: For Flat for Education accounts, list of Group identifiers the user is part of. type: array items: type: string description: Unique group identifier pictureFile: type: string nullable: true description: The ID of the user profile picture coverPictureFile: type: string nullable: true description: The ID of the user profile cover picture UserSigninLinkCreation: type: object properties: destinationPath: type: string description: Path to redirect to after signin default: / example: destinationPath: /class UserSigninLink: type: object properties: url: type: string description: URL to use to sign in to this account token: type: string description: Raw sign-in token, can be used to build custom URLs (e.g. deep links) expirationDate: type: string description: Date when the link expires format: date-time example: url: https://demo.flat.io/auth/signin-link/00000000-0000-0000-0000-000000000000?next=%2F token: 0 OrganizationUserAccessTokenCreation: required: - scopes type: object properties: scopes: type: array description: List of requested scopes for this credential items: $ref: '#/components/schemas/AppScopes' description: Creation of a delegated API access token for an organization user example: scopes: - account.public_profile - account.education_profile - edu.classes.readonly UserCommunityProfileLinks: type: object description: Social networks links properties: spotifyUrl: type: string nullable: true description: Spotify Profile URL youtubeUrl: type: string nullable: true description: YouTube channel URL soundcloudUrl: type: string nullable: true description: SoundCloud Profile URL tiktokUrl: type: string nullable: true description: TikTok profile URL. For updates, also accepts TikTok usernames instagramUrl: type: string nullable: true description: Instagram profile URL. For updates, also accepts Instagram usernames websiteUrl: type: string nullable: true description: Personnal website URL parameters: limit: name: limit in: query description: This is the maximum number of objects that may be returned schema: maximum: 1000 minimum: 1 type: integer default: 50 next: name: next in: query description: | An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the `Link` header when requesting the API. These URLs will contain a `next` and `previous` cursor based on the available data. schema: type: string previous: name: previous in: query description: | An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the `Link` header when requesting the API. These URLs will contain a `next` and `previous` cursor based on the available data. schema: type: string eventProperties: name: eventProperties in: query description: | Optional analytics properties merged into XP tracking for this request. JSON-encoded string representing event properties. Example: - `?eventProperties={"context":"discover","screenLevel0":"home"}` schema: type: string example: '{"context":"discover","screenLevel0":"home","screenRoute":"/discover"}' sortDirection: name: direction in: query description: Sort direction schema: type: string enum: - asc - desc group: name: group in: path description: | Unique identifier of a Flat group required: true schema: type: string class: name: class in: path description: Unique identifier of the class required: true schema: type: string assignment: name: assignment in: path description: Unique identifier of the assignment required: true schema: type: string submission: name: submission in: path description: Unique identifier of the submission required: true schema: type: string post: name: post in: path description: Unique identifier of the post required: true schema: type: string comment: name: comment in: path description: Unique identifier of the comment required: true schema: type: string role: name: role in: query description: Filter users by role schema: type: array items: type: string enum: - user - teacher - admin - accountAdmin searchInputQuery: name: q in: query description: The query to search schema: type: string groupIds: name: group in: query description: Filter users by group schema: type: array items: type: string noActiveLicense: name: noActiveLicense in: query description: Filter users who don't have an active license schema: type: boolean testAccounts: name: testAccounts in: query description: | Filter users based on test account status. Test accounts are student accounts created for testing purposes by teachers. * `exclude`: Hide test accounts from results. * `only`: Show only test accounts. When omitted, all users are returned. schema: type: string enum: - exclude - only headers: X-Flat-Score-Revision: description: The unique identifier of the score revision schema: type: string X-Flat-Score-Revision-Date: description: The date of the score revision (ISO 8601) schema: type: string format: date-time