Flat

Activate the class

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.

Add a feedback comment to a submission

Add a new collaborator

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.

Add a new video or audio track to the score

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.

Add a score to the collection

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.

Add a user to the class

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.

Archive the assignment

Archive the assignment

Archive the class

Mark the class as `archived`. When this course is synchronized with another app, like Google Classroom, this state will be automatically be updated.

Assignment creation

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.

Assignments listing

Copy an assignment

Copy an assignment to a specified class. If the original assignment has a due date in the past, this new assingment will be created without a due date. If the new class is synchronized with an external app (e.g. Google Classroom), the copied assignment will also be posted on the external app.

Count the organization users using the provided filters

Create a new class

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.

Create a new collection

This method will create a new collection and add it to your `root` collection.

Create a new couple of LTI 1.x credentials

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

Create a new invitation to join the organization

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.

Create a new revision

Update a score by uploading a new revision for this one.

Create a new score

Use this API method to **create a new music score in the current User account**. You will need a MusicXML 3 (`vnd.recordare.musicxml` or `vnd.recordare.musicxml+xml`), a MIDI (`audio/midi`), Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar, or MuseScore file to create the new Flat document. 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. This can be the `root` collection or a different collection based on the user's settings or API authentication method. 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}`.

Create a new user account

Create or edit a submission

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.

Delete a collaborator

Remove the specified collaborator from the score

Delete a comment

Delete a feedback comment to a submission

Delete a score

This method can be used by the owner/admin (`aclAdmin` rights) of a score as well as regular collaborators. 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 regular collaborator (`aclRead` / `aclWrite`), the score will be unshared (i.e. removed from the account & own collections).

Delete a score from the collection

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.

Delete a submission

Use this method as a teacher to delete a submission and allow student to start over the assignment

Delete the collection

This method will schedule the deletion of the collection. Until deleted, the collection will be available in the `trash`.

Edit a score's metadata

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.

Edit a submission

Use this method as a teacher to update the different submission and give feedback. Teachers can only set `return`, `draftGrade` and `grade`

Fork a score

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.

Get a collaborator

Get the information about a collaborator (User or Group).

Get a public user profile

Get a public profile of a Flat User.

Get a score revision

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.

Get a score revision data

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`, a tumbnail of the first page `thumbnail.png` or auto sync points `synchronizationPoints`.

Get a score's metadata

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.

Get a student submission

Get collection details

Get current user profile

Get details about the current authenticated User.

Get group information

Get the details of a single class

Get the history of the submission

For teachers only. Returns a detailed history of the submission. This currently includes state and grade histories.

Join a class

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.

List comments

This method lists the different comments added on a music score (documents and inline) sorted by their post dates.

List group's scores

Get the list of scores shared with a group.

List group's users

List liked scores

List LTI 1.x credentials

List submissions related to the score

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.

List the audio or video tracks linked to a score

List the classes available for the current user

List the collaborators

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

List the collections

Use this method to list the user's collections contained in `parent` (by default in the `root` collection). If no sort option is provided, the collections are sorted by `creationDate` `desc`. Note that this method will not include the `parent` collection in the listing. For example, if you need the details of the `root` collection, you can use `GET /v2/collections/root`.

List the feedback comments of a submission

List the organization invitations

List the organization users

List the revisions

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.

List the scores contained in a collection

Use this method to list the scores contained in a collection. If no sort option is provided, the scores are sorted by `modificationDate` `desc`.

List the students' submissions

List the submissions for a student

Use this method as a teacher to list all the assignment submissions sent by a student of the class

List user's scores

Get the list of public scores owned by a User. **DEPRECATED**: Please note that the current behavior will be deprecrated on **2019-01-01**. This method will no longer list private and shared scores, but only public scores of a Flat account. If you want to access to private scores, please use the [Collections API](#tag/Collection) instead.

Mark the comment as resolved

Mark the comment as unresolved

Post a new comment

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

Remove a user from the class

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.

Remove an account from Flat

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)

Remove an audio or video track linked to the score

Remove an organization invitation

Retrieve the details of an audio or video track linked to a score

Revoke LTI 1.x credentials

Unarchive the assignment.

Mark the assignment as `active`.

Unarchive the class

Mark the class as `active`. When this course is synchronized with another app, like Google Classroom, this state will be automatically be updated.

Untrash a collection

This method will restore the collection by removing it from the `trash` and add it back to the `root` collection.

Untrash a score

This method will remove the score from the `trash` collection and from the deletion queue, and add it back to the original collections.

Update a collection's metadata

Update a feedback comment to a submission

Update account information

Update an audio or video track linked to a score

Update an existing comment

Update the class

Update the meta information of the class