openapi-directory/api/flat.io.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.0","info":{"contact":{"email":"developers@flat.io","name":"Flat","url":"https://flat.io/developers/docs/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:\n\n* Creating and importing new music scores using MusicXML, MIDI, Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar and MuseScore files\n* Browsing, updating, copying, exporting the user's scores (for example in MP3, WAV or MIDI)\n* Managing educational resources with Flat for Education: creating & updating the organization accounts, the classes, rosters and assignments.\n\nThe 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.\nThe [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/).\nThis API features Cross-Origin Resource Sharing (CORS) implemented in compliance with [W3C spec](https://www.w3.org/TR/cors/).\n\nYou 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).\n\nGetting Started and learn more:\n\n* [API Overview and interoduction](https://flat.io/developers/docs/api/)\n* [Authentication (Personal Access Tokens or OAuth2)](https://flat.io/developers/docs/api/authentication.html)\n* [SDKs](https://flat.io/developers/docs/api/sdks.html)\n* [Rate Limits](https://flat.io/developers/docs/api/rate-limits.html)\n* [Changelog](https://flat.io/developers/docs/api/changelog.html)\n","termsOfService":"https://flat.io/legal","title":"Flat","version":"2.7.0","x-apisguru-categories":["media","collaboration"],"x-logo":{"url":"https://flat.io/img/logo-flat.svg"},"x-origin":[{"format":"swagger","url":"https://raw.githubusercontent.com/FlatIO/api-reference/master/spec/swagger.yaml","version":"2.0"}],"x-providerName":"flat.io"},"tags":[{"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.\n","name":"Account","x-displayName":"Flat Account"},{"description":"Sheet music is the main API object type available for all Flat account.\nHere is a typical lifecycle for a music score document on Flat:\n  - 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).\n  - **List scores**:\n    - The **owned scores** can be listed using the [collections API methods](#tag/Collection), especially [`GET /collections/{collection}/scores`](#operation/listCollectionScores).\n    - The scores from a public account can be listed with [`GET /users/{user}/scores`](#operation/getUserScores).\n    - Scores shared with a specific group can be listed with [`GET /groups/{group}/scores`](#operation/getGroupScores).\n  - The metadata of a single score can be retrieved with [`GET /scores/{score}`](#operation/getScore).\n  - 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.\n  - 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)).\n","name":"Score","x-displayName":"Music scores"},{"description":"Collections let you organize your content in a Flat account. They work like a regular _folder_ with some specificities:\n  - Our design goal here is to create a system similar to a _book_ or a _playlist of songs_.\n  - Collections can't have children collections (except the `trash` and `sharedWithMe` that are special collections).\n  - 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.\n\nAll 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).\n\nAt 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.\n","name":"Collection","x-displayName":"Collections of music scores"},{"description":"Flat users","name":"User"},{"description":"Flat for Education organizations","name":"Organization"},{"description":"Flat for Education classes","name":"Class"},{"description":"Flat Groups","name":"Group"}],"paths":{"/classes":{"get":{"operationId":"listClasses","parameters":[{"description":"Filter the classes by state","in":"query","name":"state","schema":{"type":"string","enum":["active","inactive","archived"],"default":"active"}}],"responses":{"200":{"description":"The list of classes","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ClassDetails"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlatErrorResponse"}}}}},"security":[{"OAuth2":["edu.classes","edu.classes.readonly"]}],"summary":"List the classes available for the current user","tags":["Class"]},"post":{"description":"Classrooms on Flat allow you to create activities with assignments and post content to a specific group.\n\nWhen 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.\n\nIf the classsroom is synchronized with another application like Google Classroom, some of the meta information will automatically be updated.\n\nYou can add users to this class using `POST /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.\n","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"]}],"summary":"Create a new class","tags":["Class"]}},"/classes/enroll/{enrollmentCode}":{"post":{"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.\n\nFlat will automatically add the user to the corresponding class group based on this role in the organization.\n","operationId":"enrollClass","parameters":[{"description":"The enrollment code, available to the teacher in `ClassDetails`\n","in":"path","name":"enrollmentCode","required":true,"schema":{"type":"string"}}],"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"]}],"summary":"Join a class","tags":["Class"]}},"/classes/{class}":{"get":{"operationId":"getClass","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}}],"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"]}],"summary":"Get the details of a single class","tags":["Class"]},"put":{"description":"Update the meta information of the class\n","operationId":"updateClass","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassUpdate"}}},"description":"Details of the Class"},"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"]}],"summary":"Update the class","tags":["Class"]}},"/classes/{class}/activate":{"post":{"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.\n","operationId":"activateClass","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}}],"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"]}],"summary":"Activate the class","tags":["Class"]}},"/classes/{class}/archive":{"delete":{"description":"Mark the class as `active`. When this course is synchronized with another app, like Google Classroom, this state will be automatically be updated.\n","operationId":"unarchiveClass","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}}],"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"]}],"summary":"Unarchive the class","tags":["Class"]},"post":{"description":"Mark the class as `archived`. When this course is synchronized with another app, like Google Classroom, this state will be automatically be updated.\n","operationId":"archiveClass","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}}],"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"]}],"summary":"Archive the class","tags":["Class"]}},"/classes/{class}/assignments":{"get":{"operationId":"listAssignments","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of assignments for the class","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Assignment"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlatErrorResponse"}}}}},"security":[{"OAuth2":["edu.classes","edu.classes.readonly","edu.assignments","edu.assignments.readonly"]}],"summary":"Assignments listing","tags":["Class"]},"post":{"description":"Use this method as a teacher to create and post a new assignment to a class.\n\nIf the class is synchronized with Google Classroom, the assignment will be automatically posted to your Classroom course.\n","operationId":"createAssignment","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignmentCreation"}}}},"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"]}],"summary":"Assignment creation","tags":["Class"]}},"/classes/{class}/assignments/{assignment}/copy":{"post":{"description":"Copy an assignment to a specified class.\n\nIf the original assignment has a due date in the past, this new assingment will be created without a due date.\n\nIf the new class is synchronized with an external app (e.g. Google Classroom), the copied assignment will also be posted on the external app.\n","operationId":"copyAssignment","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}},{"description":"Unique identifier of the assignment","in":"path","name":"assignment","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignmentCopy"}}},"required":true},"responses":{"200":{"description":"The new created assingment","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"]}],"summary":"Copy an assignment","tags":["Class"]}},"/classes/{class}/assignments/{assignment}/submissions":{"get":{"operationId":"getSubmissions","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}},{"description":"Unique identifier of the assignment","in":"path","name":"assignment","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The submissions","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/AssignmentSubmission"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlatErrorResponse"}}}}},"security":[{"OAuth2":["edu.classes","edu.classes.readonly","edu.assignments","edu.assignments.readonly"]}],"summary":"List the students' submissions","tags":["Class"]},"put":{"description":"Use this method as a student to create, update and submit a submission related to an assignment. Students can only set `attachments`, `studentComment` and `submit`.\n\nTeachers can use `PUT /classes/{class}/assignments/{assignment}/submissions/{submission}` to update a submission by id.\n","operationId":"createSubmission","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}},{"description":"Unique identifier of the assignment","in":"path","name":"assignment","required":true,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/AssignmentSubmissionUpdate"},"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"]}],"summary":"Create or edit a submission","tags":["Class"]}},"/classes/{class}/assignments/{assignment}/submissions/{submission}":{"get":{"operationId":"getSubmission","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}},{"description":"Unique identifier of the assignment","in":"path","name":"assignment","required":true,"schema":{"type":"string"}},{"description":"Unique identifier of the submission","in":"path","name":"submission","required":true,"schema":{"type":"string"}}],"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"]}],"summary":"Get a student submission","tags":["Class"]},"put":{"description":"Use this method as a teacher to update the different submission and give feedback.\nTeachers can only set `returnFeedback`\n","operationId":"editSubmission","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}},{"description":"Unique identifier of the assignment","in":"path","name":"assignment","required":true,"schema":{"type":"string"}},{"description":"Unique identifier of the submission","in":"path","name":"submission","required":true,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/AssignmentSubmissionUpdate"},"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"]}],"summary":"Edit a submission","tags":["Class"]}},"/classes/{class}/students/{user}/submissions":{"get":{"description":"Use this method as a teacher to list all the assignment submissions sent by a student of the class\n","operationId":"listClassStudentSubmissions","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}},{"description":"Unique identifier of the user","in":"path","name":"user","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The list of submissions","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/AssignmentSubmission"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlatErrorResponse"}}}}},"security":[{"OAuth2":["edu.classes","edu.classes.readonly","edu.assignments","edu.assignments.readonly"]}],"summary":"List the submissions for a student","tags":["Class"]}},"/classes/{class}/users/{user}":{"delete":{"description":"This method can be used by a teacher to remove a user from the class, or by a student to leave the classroom.\n\nWarning: Removing a user from the class will remove the associated resources, including the submissions and feedback related to these submissions.\n","operationId":"deleteClassUser","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}},{"description":"Unique identifier of the user","in":"path","name":"user","required":true,"schema":{"type":"string"}}],"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"]}],"summary":"Remove a user from the class","tags":["Class"]},"put":{"description":"This method can be used by a teacher of the class to enroll another Flat user into the class.\n\nOnly users that are part of your Organization can be enrolled in a class of this same Organization.\n\nWhen enrolling a user in the class, Flat will automatically add this user to the corresponding Class group, based on this role in the Organization.\n","operationId":"addClassUser","parameters":[{"description":"Unique identifier of the class","in":"path","name":"class","required":true,"schema":{"type":"string"}},{"description":"Unique identifier of the user","in":"path","name":"user","required":true,"schema":{"type":"string"}}],"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"]}],"summary":"Add a user to the class","tags":["Class"]}},"/collections":{"get":{"description":"Use this method to list the user's collections contained in `parent` (by default in the `root` collection).\nIf no sort option is provided, the collections are sorted by `creationDate` `desc`.\n\nNote that this method will not include the `parent` collection in the listing.\nFor example, if you need the details of the `root` collection, you can use `GET /v2/collections/root`.\n","operationId":"listCollections","parameters":[{"description":"List the collection contained in this `parent` collection.\n\nThis option doesn't provide a complete multi-level collection support.\nWhen sharing a collection with someone, this one will have as `parent` `sharedWithMe`.\n","in":"query","name":"parent","schema":{"type":"string","default":"root"}},{"description":"Sort","in":"query","name":"sort","schema":{"type":"string","enum":["creationDate","title"]}},{"$ref":"#/components/parameters/sortDirection"},{"$ref":"#/components/parameters/limitDefault25Max100"},{"$ref":"#/components/parameters/next"},{"$ref":"#/components/parameters/previous"}],"responses":{"200":{"description":"List of collections","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Collection"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlatErrorResponse"}}}}},"security":[{"OAuth2":["collections","collections.readonly"]}],"summary":"List the collections","tags":["Collection"]},"post":{"description":"This method will create a new collection and add it to your `root` collection.\n","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"]}],"summary":"Create a new collection","tags":["Collection"]}},"/collections/{collection}":{"delete":{"description":"This method will schedule the deletion of the collection. Until deleted, the collection will be available in the `trash`.\n","operationId":"deleteCollection","parameters":[{"$ref":"#/components/parameters/collection"}],"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"]}],"summary":"Delete the collection","tags":["Collection"]},"get":{"operationId":"getCollection","parameters":[{"$ref":"#/components/parameters/collection"},{"$ref":"#/components/parameters/sharingKey"}],"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"]}],"summary":"Get collection details","tags":["Collection"]},"put":{"operationId":"editCollection","parameters":[{"$ref":"#/components/parameters/collection"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionModification"}}}},"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"]}],"summary":"Update a collection's metadata","tags":["Collection"]}},"/collections/{collection}/scores":{"get":{"description":"Use this method to list the scores contained in a collection.\nIf no sort option is provided, the scores are sorted by `modificationDate` `desc`.\n","operationId":"listCollectionScores","parameters":[{"$ref":"#/components/parameters/collection"},{"$ref":"#/components/parameters/sharingKey"},{"description":"Sort","in":"query","name":"sort","schema":{"type":"string","enum":["creationDate","modificationDate","title"]}},{"$ref":"#/components/parameters/sortDirection"},{"$ref":"#/components/parameters/limitDefault25Max100"},{"$ref":"#/components/parameters/next"},{"$ref":"#/components/parameters/previous"}],"responses":{"200":{"description":"List of scores","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ScoreDetails"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlatErrorResponse"}}}}},"security":[{"OAuth2":["collections"]}],"summary":"List the scores contained in a collection","tags":["Collection"]}},"/collections/{collection}/scores/{score}":{"delete":{"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.\nThis 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.\n","operationId":"deleteScoreFromCollection","parameters":[{"$ref":"#/components/parameters/collection"},{"$ref":"#/components/parameters/score"}],"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"]}],"summary":"Delete a score from the collection","tags":["Collection"]},"put":{"description":"This operation will add a score to a collection. The default behavior will make the score available across multiple collections.\nYou must have the capability `canAddScores` on the provided `collection` to perform the action.\n","operationId":"addScoreToCollection","parameters":[{"$ref":"#/components/parameters/collection"},{"$ref":"#/components/parameters/score"},{"$ref":"#/components/parameters/sharingKey"}],"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"]}],"summary":"Add a score to the collection","tags":["Collection"]}},"/collections/{collection}/untrash":{"post":{"description":"This method will restore the collection by removing it from the `trash` and add it back to the `root` collection.\n","operationId":"untrashCollection","parameters":[{"$ref":"#/components/parameters/collection"}],"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":["collections"]}],"summary":"Untrash a collection","tags":["Collection"]}},"/groups/{group}":{"get":{"operationId":"getGroupDetails","parameters":[{"$ref":"#/components/parameters/group"}],"responses":{"200":{"description":"The group details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupDetails"}}}},"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"]}],"summary":"Get group information","tags":["Group"]}},"/groups/{group}/scores":{"get":{"description":"Get the list of scores shared with a group.\n","operationId":"getGroupScores","parameters":[{"$ref":"#/components/parameters/group"},{"description":"Filter the score forked from the score id `parent`","in":"query","name":"parent","schema":{"type":"string"}}],"responses":{"200":{"description":"The group's scores","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ScoreDetails"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlatErrorResponse"}}}}},"security":[{"OAuth2":["scores","scores.readonly"]}],"summary":"List group's scores","tags":["Group","Score"]}},"/groups/{group}/users":{"get":{"operationId":"listGroupUsers","parameters":[{"$ref":"#/components/parameters/group"}],"responses":{"200":{"description":"The list of users member of the group","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/UserPublic"},"type":"array"}}}},"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"]}],"summary":"List group's users","tags":["Group"]}},"/me":{"get":{"description":"Get details about the current authenticated User.\n","operationId":"getAuthenticatedUser","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"]}],"summary":"Get current user profile","tags":["Account"]}},"/organizations/invitations":{"get":{"operationId":"listOrganizationInvitations","parameters":[{"description":"Filter users by role","in":"query","name":"role","schema":{"type":"string","enum":["user","teacher","admin"]}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/next"},{"$ref":"#/components/parameters/previous"}],"responses":{"200":{"description":"List of invitations","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/OrganizationInvitation"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlatErrorResponse"}}}}},"security":[{"OAuth2":["edu.admin","edu.admin.users","edu.admin.users.readonly"]}],"summary":"List the organization invitations","tags":["Organization"]},"post":{"description":"This method creates and sends invitation for teachers and admins.\n\nInvitations can only be used by new Flat users or users who are not part of the organization yet.\n\nIf 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.\n","operationId":"createOrganizationInvitation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationInvitationCreation"}}}},"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"]}],"summary":"Create a new invitation to join the organization","tags":["Organization"]}},"/organizations/invitations/{invitation}":{"delete":{"operationId":"removeOrganizationInvitation","parameters":[{"description":"Unique identifier of the invitation","in":"path","name":"invitation","required":true,"schema":{"type":"string"}}],"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"]}],"summary":"Remove an organization invitation","tags":["Organization"]}},"/organizations/lti/credentials":{"get":{"operationId":"listLtiCredentials","responses":{"200":{"description":"The list of LTI Credentials","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/LtiCredentials"},"type":"array"}}}},"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"]}],"summary":"List LTI 1.x credentials","tags":["Organization"]},"post":{"description":"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/).\n","operationId":"createLtiCredentials","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"]}],"summary":"Create a new couple of LTI 1.x credentials","tags":["Organization"]}},"/organizations/lti/credentials/{credentials}":{"delete":{"operationId":"revokeLtiCredentials","parameters":[{"description":"Credentials unique identifier\n","in":"path","name":"credentials","required":true,"schema":{"type":"string"}}],"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"}}}}},"security":[{"OAuth2":["edu.admin","edu.admin.lti"]}],"summary":"Revoke LTI 1.x credentials","tags":["Organization"]}},"/organizations/users":{"get":{"operationId":"listOrganizationUsers","parameters":[{"description":"Filter users by role","in":"query","name":"role","schema":{"type":"string","enum":["user","teacher","admin"]}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/next"},{"$ref":"#/components/parameters/previous"}],"responses":{"200":{"description":"List of users","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/UserDetailsAdmin"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlatErrorResponse"}}}}},"security":[{"OAuth2":["edu.admin","edu.admin.users","edu.admin.users.readonly"]}],"summary":"List the organization users","tags":["Organization"]},"post":{"operationId":"createOrganizationUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCreation"}}}},"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"]}],"summary":"Create a new user account","tags":["Organization"]}},"/organizations/users/{user}":{"delete":{"description":"This operation removes an account from Flat and its data, including:\n* The music scores created by this user (documents, history, comments, collaboration information)\n* Education related data (assignments and classroom information)\n","operationId":"removeOrganizationUser","parameters":[{"$ref":"#/components/parameters/organizationUser"},{"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.\nThis operation will remove the education-related data from the account.\nBefore 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.\n","in":"query","name":"convertToIndividual","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"]}],"summary":"Remove an account from Flat","tags":["Organization"]},"put":{"operationId":"updateOrganizationUser","parameters":[{"$ref":"#/components/parameters/organizationUser"}],"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"]}],"summary":"Update account information","tags":["Organization"]}},"/scores":{"post":{"description":"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.\n\nThis 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}`).\n\nThe currently authenticated user will be granted owner of the file and will be able to add other collaborators (users and groups).\n\nIf 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.\nIf 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.\nYou can check the adjusted privacy settings in the returned score `privacy`, and optionally adjust these settings if needed using `PUT /scores/{score}`.\n","operationId":"createScore","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreCreation"}}},"required":true},"responses":{"200":{"description":"Score created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreDetails"}}}},"400":{"description":"Bad score creation request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlatErrorResponse"}}}},"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":["scores"]}],"summary":"Create a new score","tags":["Score"]}},"/scores/{score}":{"delete":{"description":"This method can be used by the owner/admin (`aclAdmin` rights) of a score as well as regular collaborators.\n\nWhen called by an owner/admin, it will schedule the deletion of the score, its revisions, and complete history.\nThe score won't be accessible anymore after calling this method and the user's quota will directly be updated.\n\nWhen called by a regular collaborator (`aclRead` / `aclWrite`), the score will be unshared (i.e. removed from the account & own collections).\n","operationId":"deleteScore","parameters":[{"$ref":"#/components/parameters/score"}],"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"]}],"summary":"Delete a score","tags":["Score"]},"get":{"description":"Get the details of a score identified by the `score` parameter in the URL.\nThe currently authenticated user must have at least a read access to the document to use this API call.\n","operationId":"getScore","parameters":[{"$ref":"#/components/parameters/score"},{"$ref":"#/components/parameters/sharingKey"}],"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"]}],"summary":"Get a score's metadata","tags":["Score"]},"put":{"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.\n\nTo edit the file itself, create a new revision using the appropriate method (`POST /v2/scores/{score}/revisions/{revision}`).\n\nWhen editing the `title` of the score, the API metadata are updated directly when calling this method, unlike the data itself.\nThe title in the score data will be \"lazy\" updated at the next score save with the editor or our internal save.\n","operationId":"editScore","parameters":[{"$ref":"#/components/parameters/score"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreModification"}}}},"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"]}],"summary":"Edit a score's metadata","tags":["Score"]}},"/scores/{score}/collaborators":{"get":{"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.\n\nCollaborators can be a single user (the object `user` will be populated) or a group (the object `group` will be populated).\n","operationId":"getScoreCollaborators","parameters":[{"$ref":"#/components/parameters/score"},{"$ref":"#/components/parameters/sharingKey"}],"responses":{"200":{"description":"List of collaborators","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ResourceCollaborator"},"type":"array"}}}},"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"]}],"summary":"List the collaborators","tags":["Score"]},"post":{"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.\n- To add an existing Flat user to the resource, specify its unique identifier in the `user` property.\n- To invite an external user to the resource, specify its email in the `userEmail` property.\n- To add a Flat group to the resource, specify its unique identifier in the `group` property.\n- To update an existing collaborator, process the same request with different rights.\n","operationId":"addScoreCollaborator","parameters":[{"$ref":"#/components/parameters/score"}],"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","conte