Flat API

OpenAPI apis-guru mediacollaboration

The Flat API allows you to easily extend the abilities of the , with a wide range of use cases including the following:

Creating and importing new music scores using MusicXML, MIDI, Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar and MuseScore files
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 of this API follows the , you can use and work with . This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with .

You can use your favorite HTTP/REST library for your programming language to use Flat's API. This specification and reference is .

Getting Started and learn more:

Homepage: https://api.apis.guru/v2/specs/flat.io/2.13.0.json
Provider: flat.io
OpenAPI version: 3.0.2
Spec (JSON): https://api.apis.guru/v2/specs/flat.io/2.13.0/openapi.json
Spec (YAML): https://api.apis.guru/v2/specs/flat.io/2.13.0/openapi.yaml

Tools (83)

Extracted live via the executor SDK.

account.getAuthenticatedUser

Get details about the current authenticated User.
class.activateClass

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

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

Archive the assignment
class.archiveClass

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

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

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

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

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

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

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

Delete a feedback comment to a submission
class.editSubmission

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

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

Export list of submissions grades to a CSV file
class.exportSubmissionsReviewsAsExcel

Export list of submissions grades to an Excel file
class.getClass

Get the details of a single class
class.getSubmission

Get a student submission
class.getSubmissionComments

List the feedback comments of a submission
class.getSubmissionHistory

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

List the students' submissions
class.listAssignments

Assignments listing
class.listClasses

List the classes available for the current user
class.listClassStudentSubmissions

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

Add a feedback comment to a submission
class.unarchiveAssignment

Mark the assignment as active.
class.unarchiveClass

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

Update the meta information of the class
class.updateSubmissionComment

Update a feedback comment to a submission
collection.addScoreToCollection

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

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

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

This method will delete a score from the collection. Unlike , 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.
collection.editCollection

Update a collection's metadata
collection.getCollection

Get collection details
collection.listCollections

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

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

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

Get group information
group.getGroupScores

Get the list of scores shared with a group.
group.listGroupUsers

List group's users
organization.countOrgaUsers

Count the organization users using the provided filters
organization.createLtiCredentials

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

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

Create a new user account
organization.listLtiCredentials

List LTI 1.x credentials
organization.listOrganizationInvitations

List the organization invitations
organization.listOrganizationUsers

List the organization users
organization.removeOrganizationInvitation

Remove an organization invitation
organization.removeOrganizationUser
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)
organization.revokeLtiCredentials

Revoke LTI 1.x credentials
organization.updateOrganizationUser

Update account information
score.addScoreCollaborator
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.
score.addScoreTrack

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

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}.
score.createScoreRevision

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

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

Delete a comment
score.deleteScoreTrack

Remove an audio or video track linked to the score
score.editScore

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

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 account, the inline and contextualized comments will be accessible in the child document.
score.getScore

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

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

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

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

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

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

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

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

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

List the audio or video tracks linked to a score
score.markScoreCommentResolved

Mark the comment as resolved
score.markScoreCommentUnresolved

Mark the comment as unresolved
score.postScoreComment

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

Remove the specified collaborator from the score
score.untrashScore

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

Update an existing comment
score.updateScoreTrack

Update an audio or video track linked to a score
user.gerUserLikes

List liked scores
user.getUser

Get a public profile of a Flat User.
user.getUserScores

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 instead.
openapi.previewSpec

Preview an OpenAPI document before adding it as a source
openapi.addSource

Add an OpenAPI source and register its operations as tools