Flat API
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: *…
Media & content#openapi#media#collaboration
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
The Flat API allows you to easily extend the abilities of the Flat Platform, 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 schema of this API follows the OpenAPI Initiative (OAI) specification, you can use and work with compatible Swagger tools.
This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec.
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.
Getting Started and learn more:
Endpoints 81
Account
- GETGet current user profile
/me?onlyId=falseGet details about the current authenticated User.
Score
- POSTCreate a new score
/scoresUse this API method to create a new music score in the current User account. You will need a MusicXML 3 (vnd.recordare.musicxml or… - GETGet a score's metadata
/scores/:score?sharingKey=stringGet 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… - PUTEdit a score's metadata
/scores/:scoreThis 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,… - DELETEDelete a score
/scores/:score?now=falseThis 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… - GETList the collaborators
/scores/:score/collaborators?sharingKey=stringThis 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… - POSTAdd a new collaborator
/scores/:score/collaboratorsShare 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… - GETGet a collaborator
/scores/:score/collaborators/:collaborator?sharingKey=stringGet the information about a collaborator (User or Group). - DELETEDelete a collaborator
/scores/:score/collaborators/:collaboratorRemove the specified collaborator from the score - GETList comments
/scores/:score/comments?sharingKey=string&type=document&sort=date&direction=ascThis method lists the different comments added on a music score (documents and inline) sorted by their post dates. - POSTPost a new comment
/scores/:score/comments?sharingKey=stringPost 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… - PUTUpdate an existing comment
/scores/:score/comments/:comment?sharingKey=string - DELETEDelete a comment
/scores/:score/comments/:comment?sharingKey=string - PUTMark the comment as resolved
/scores/:score/comments/:comment/resolved?sharingKey=string - DELETEMark the comment as unresolved
/scores/:score/comments/:comment/resolved?sharingKey=string - POSTFork a score
/scores/:score/fork?sharingKey=stringThis 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.… - GETList the revisions
/scores/:score/revisions?sharingKey=stringWhen 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… - POSTCreate a new revision
/scores/:score/revisionsUpdate a score by uploading a new revision for this one. - GETGet a score revision
/scores/:score/revisions/:revision?sharingKey=stringWhen 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. - GETGet a score revision data
/scores/:score/revisions/:revision/:format?sharingKey=string&parts=string&onlyCached=true&url=trueRetrieve the file corresponding to a score revision (the following formats are available): Flat JSON/Adagio JSON json, MusicXML mxl/xml, MP3 mp3, WAV wav,… - GETList submissions related to the score
/scores/:score/submissionsThis 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… - GETList the audio or video tracks linked to a score
/scores/:score/tracks?sharingKey=string&assignment=string&listAutoTrack=true - POSTAdd a new video or audio track to the score
/scores/:score/tracksUse 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… - GETRetrieve the details of an audio or video track linked to a score
/scores/:score/tracks/:track?sharingKey=string - PUTUpdate an audio or video track linked to a score
/scores/:score/tracks/:track - DELETERemove an audio or video track linked to the score
/scores/:score/tracks/:track - POSTUntrash a score
/scores/:score/untrashThis method will remove the score from the trash collection and from the deletion queue, and add it back to the original collections.
Collection
- GETList the collections
/collections?parent=root&sort=creationDate&direction=asc&limit=25&next=string&previous=stringUse 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… - POSTCreate a new collection
/collectionsThis method will create a new collection and add it to your root collection. - GETGet collection details
/collections/:collection?sharingKey=string - PUTUpdate a collection's metadata
/collections/:collection - DELETEDelete the collection
/collections/:collectionThis method will schedule the deletion of the collection. Until deleted, the collection will be available in the trash. - GETList the scores contained in a collection
/collections/:collection/scores?sharingKey=string&sort=creationDate&direction=asc&limit=25&next=string&previous=stringUse this method to list the scores contained in a collection. If no sort option is provided, the scores are sorted by modificationDate desc. - PUTAdd a score to the collection
/collections/:collection/scores/:score?sharingKey=stringThis operation will add a score to a collection. The default behavior will make the score available across multiple collections. You must have the capability… - DELETEDelete a score from the collection
/collections/:collection/scores/:score?sharingKey=stringThis method will delete a score from the collection. Unlike DELETE /scores/{score}, this score will not remove the score from your account, but only from the… - POSTUntrash a collection
/collections/:collection/untrashThis method will restore the collection by removing it from the trash and add it back to the root collection.
User
- GETGet a public user profile
/users/:userGet a public profile of a Flat User. - GETList liked scores
/users/:user/likes?ids=true - GETList user's scores
/users/:user/scores?parent=stringGet 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…
Organization
- GETList the organization invitations
/organizations/invitations?role=user&limit=50&next=string&previous=string - POSTCreate a new invitation to join the organization
/organizations/invitationsThis 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… - DELETERemove an organization invitation
/organizations/invitations/:invitation - GETList LTI 1.x credentials
/organizations/lti/credentials - POSTCreate a new couple of LTI 1.x credentials
/organizations/lti/credentialsFlat 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… - DELETERevoke LTI 1.x credentials
/organizations/lti/credentials/:credentials - GETList the organization users
/organizations/users?sort=string&direction=asc&next=string&previous=string&role=user&q=string&group=string&noActiveLicense=true&licenseExpirationDate=string&onlyIds=true&limit=25 - POSTCreate a new user account
/organizations/users - GETCount the organization users using the provided filters
/organizations/users/count?role=user&q=string&group=string&noActiveLicense=true - PUTUpdate account information
/organizations/users/:user - DELETERemove an account from Flat
/organizations/users/:user?convertToIndividual=trueThis operation removes an account from Flat and its data, including: * The music scores created by this user (documents, history, comments, collaboration…
Class
- GETList the classes available for the current user
/classes?state=active - POSTCreate a new class
/classesClassrooms on Flat allow you to create activities with assignments and post content to a specific group. When creating a class, Flat automatically creates two… - POSTJoin a class
/classes/enroll/:enrollmentCodeUse 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… - GETGet the details of a single class
/classes/:class - PUTUpdate the class
/classes/:classUpdate the meta information of the class - POSTActivate the class
/classes/:class/activateMark 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. - POSTArchive the class
/classes/:class/archiveMark the class as archived. When this course is synchronized with another app, like Google Classroom, this state will be automatically be updated. - DELETEUnarchive the class
/classes/:class/archiveMark the class as active. When this course is synchronized with another app, like Google Classroom, this state will be automatically be updated. - GETAssignments listing
/classes/:class/assignments - POSTAssignment creation
/classes/:class/assignmentsUse 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… - POSTArchive the assignment
/classes/:class/assignments/:assignment/archiveArchive the assignment - DELETEUnarchive the assignment.
/classes/:class/assignments/:assignment/archiveMark the assignment as active. - POSTCopy an assignment
/classes/:class/assignments/:assignment/copyCopy 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… - GETList the students' submissions
/classes/:class/assignments/:assignment/submissions - PUTCreate or edit a submission
/classes/:class/assignments/:assignment/submissionsUse 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… - GETCSV Grades exports
/classes/:class/assignments/:assignment/submissions/csvExport list of submissions grades to a CSV file - GETExcel Grades exports
/classes/:class/assignments/:assignment/submissions/excelExport list of submissions grades to an Excel file - GETGet a student submission
/classes/:class/assignments/:assignment/submissions/:submission - PUTEdit a submission
/classes/:class/assignments/:assignment/submissions/:submissionUse this method as a teacher to update the different submission and give feedback. Teachers can only set return, draftGrade and grade - DELETEDelete a submission
/classes/:class/assignments/:assignment/submissions/:submissionUse this method as a teacher to delete a submission and allow student to start over the assignment - GETList the feedback comments of a submission
/classes/:class/assignments/:assignment/submissions/:submission/comments - POSTAdd a feedback comment to a submission
/classes/:class/assignments/:assignment/submissions/:submission/comments - PUTUpdate a feedback comment to a submission
/classes/:class/assignments/:assignment/submissions/:submission/comments/:comment - DELETEDelete a feedback comment to a submission
/classes/:class/assignments/:assignment/submissions/:submission/comments/:comment - GETGet the history of the submission
/classes/:class/assignments/:assignment/submissions/:submission/historyFor teachers only. Returns a detailed history of the submission. This currently includes state and grade histories. - GETList the submissions for a student
/classes/:class/students/:user/submissionsUse this method as a teacher to list all the assignment submissions sent by a student of the class - PUTAdd a user to the class
/classes/:class/users/:userThis 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… - DELETERemove a user from the class
/classes/:class/users/:userThis 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…
Group
- GETGet group information
/groups/:group - GETList group's scores
/groups/:group/scores?parent=stringGet the list of scores shared with a group. - GETList group's users
/groups/:group/users?source=googleClassroom
API details
- Base URL
https://api.flat.io/v2- Authentication
- OAuth 2.0 (authorization code flow) with 18 scopes
- Operations
- 81 operations on 51 pathsGET 34POST 20DELETE 15PUT 12
- Main resources
- Class 30Score 29Organization 11Collection 9Group 3User 3Account 1
- Response formats
application/jsonapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheettext/csvapplication/vnd.recordare.musicxml- Description format
- OpenAPI 3.0.2, API version
2.13.0 - Links
- OpenAPI document · Terms of service · Support
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the Flat API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Flat API collection, without the publisher's secrets.
- Add your credentialsThis API uses OAuth 2.0 (authorization code flow) with 18 scopes. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get current user profile” (GET /me?onlyId=false), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Flat API?
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: *… It is listed under Media & content and has 81 endpoints.
Who publishes the Flat API?
It is listed from Flat's public API description (an OpenAPI document), not published by Flat on Swastik Codes. Anyone who controls flat.io can claim the profile by adding a DNS TXT record.
What is the base URL of the Flat API?
Requests go to https://api.flat.io/v2. Endpoint paths are added to this base URL.
How do I authenticate with the Flat API?
With OAuth 2.0 (authorization code flow) with 18 scopes.
How many endpoints does the Flat API have?
81 operations on 51 paths (34 GET, 20 POST, 15 DELETE, 12 PUT). The largest groups are Class, Score, Organization, Collection.
Is forking the Flat API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.