@datafire/flat

v6.0.0

Published

3 years ago

DataFire integration for Flat

Downloads

0High
0Medium
0Low

datafire

@datafire/flat

Client library for Flat

Installation and Usage

npm install --save @datafire/flat

let flat = require('@datafire/flat').create({
  access_token: "",
  refresh_token: "",
  client_id: "",
  client_secret: "",
  redirect_uri: ""
});

.then(data => {
  console.log(data);
});

Description

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:

Actions

oauthCallback

Exchange the code passed to your redirect URI for an access_token

flat.oauthCallback({
  "code": ""
}, context)

Input

input object
- code required string

Output

output object
- access_token string
- refresh_token string
- token_type string
- scope string
- expiration string

oauthRefresh

Exchange a refresh_token for an access_token

flat.oauthRefresh(null, context)

Input

This action has no parameters

Output

output object
- access_token string
- refresh_token string
- token_type string
- scope string
- expiration string

listClasses

List the classes available for the current user

flat.listClasses({}, context)

Input

input object
- state string (values: active, inactive, archived): Filter the classes by state

Output

output array
- items ClassDetails

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

flat.createClass({
  "body": {
    "name": ""
  }
}, context)

Input

input object
- body required ClassCreation

Output

output ClassDetails

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.

flat.enrollClass({
  "enrollmentCode": ""
}, context)

Input

input object
- enrollmentCode required string: The enrollment code, available to the teacher in ClassDetails

Output

output ClassDetails

getClass

Get the details of a single class

flat.getClass({
  "class": ""
}, context)

Input

input object
- class required string: Unique identifier of the class

Output

output ClassDetails

updateClass

Update the meta information of the class

flat.updateClass({
  "class": ""
}, context)

Input

input object
- class required string: Unique identifier of the class
- body ClassUpdate

Output

output ClassDetails

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.

flat.activateClass({
  "class": ""
}, context)

Input

input object
- class required string: Unique identifier of the class

Output

output ClassDetails

unarchiveClass

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

flat.unarchiveClass({
  "class": ""
}, context)

Input

input object
- class required string: Unique identifier of the class

Output

output ClassDetails

archiveClass

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

flat.archiveClass({
  "class": ""
}, context)

Input

input object
- class required string: Unique identifier of the class

Output

output ClassDetails

listAssignments

Assignments listing

flat.listAssignments({
  "class": ""
}, context)

Input

input object
- class required string: Unique identifier of the class

Output

output array
- items Assignment

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.

flat.createAssignment({
  "class": ""
}, context)

Input

input object
- class required string: Unique identifier of the class
- body AssignmentCreation

Output

output Assignment

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.

flat.copyAssignment({
  "class": "",
  "assignment": "",
  "body": {
    "classroom": ""
  }
}, context)

Input

input object
- class required string: Unique identifier of the class
- assignment required string: Unique identifier of the assignment
- body required AssignmentCopy

Output

output Assignment

getSubmissions

List the students' submissions

flat.getSubmissions({
  "class": "",
  "assignment": ""
}, context)

Input

input object
- class required string: Unique identifier of the class
- assignment required string: Unique identifier of the assignment

Output

output array
- items AssignmentSubmission

createSubmission

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.

Teachers can use PUT /classes/{class}/assignments/{assignment}/submissions/{submission} to update a submission by id.

flat.createSubmission({
  "class": "",
  "assignment": "",
  "body": {}
}, context)

Input

input object
- class required string: Unique identifier of the class
- assignment required string: Unique identifier of the assignment
- body required AssignmentSubmissionUpdate

Output

output AssignmentSubmission

getSubmission

Get a student submission

flat.getSubmission({
  "class": "",
  "assignment": "",
  "submission": ""
}, context)

Input

input object
- class required string: Unique identifier of the class
- assignment required string: Unique identifier of the assignment
- submission required string: Unique identifier of the submission

Output

output AssignmentSubmission

editSubmission

Use this method as a teacher to update the different submission and give feedback. Teachers can only set returnFeedback

flat.editSubmission({
  "class": "",
  "assignment": "",
  "submission": "",
  "body": {}
}, context)

Input

input object
- class required string: Unique identifier of the class
- assignment required string: Unique identifier of the assignment
- submission required string: Unique identifier of the submission
- body required AssignmentSubmissionUpdate

Output

output AssignmentSubmission

listClassStudentSubmissions

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

flat.listClassStudentSubmissions({
  "class": "",
  "user": ""
}, context)

Input

input object
- class required string: Unique identifier of the class
- user required string: Unique identifier of the user

Output

output array
- items AssignmentSubmission

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.

flat.deleteClassUser({
  "class": "",
  "user": ""
}, context)

Input

input object
- class required string: Unique identifier of the class
- user required string: Unique identifier of the user

Output

Output schema unknown

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.

flat.addClassUser({
  "class": "",
  "user": ""
}, context)

Input

input object
- class required string: Unique identifier of the class
- user required string: Unique identifier of the user

Output

Output schema unknown

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.

flat.listCollections({}, context)

Input

input object
- parent string: List the collection contained in this parent collection.
- sort string (values: creationDate, title): Sort
- direction string (values: asc, desc): Sort direction
- limit integer: This is the maximum number of objects that may be returned
- next string: An opaque string cursor to fetch the next page of data.
- previous string: An opaque string cursor to fetch the previous page of data.

Output

output array
- items Collection

createCollection

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

flat.createCollection({
  "body": {
    "title": ""
  }
}, context)

Input

input object
- body required CollectionCreation

Output

output Collection

deleteCollection

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

flat.deleteCollection({
  "collection": ""
}, context)

Input

input object
- collection required string: Unique identifier of the collection.

Output

Output schema unknown

getCollection

Get collection details

flat.getCollection({
  "collection": ""
}, context)

Input

input object
- collection required string: Unique identifier of the collection.
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

output Collection

editCollection

Update a collection's metadata

flat.editCollection({
  "collection": ""
}, context)

Input

input object
- collection required string: Unique identifier of the collection.
- body CollectionModification

Output

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

flat.listCollectionScores({
  "collection": ""
}, context)

Input

input object
- collection required string: Unique identifier of the collection.
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.
- sort string (values: creationDate, modificationDate, title): Sort
- direction string (values: asc, desc): Sort direction
- limit integer: This is the maximum number of objects that may be returned
- next string: An opaque string cursor to fetch the next page of data.
- previous string: An opaque string cursor to fetch the previous page of data.

Output

output array
- items ScoreDetails

deleteScoreFromCollection

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

flat.deleteScoreFromCollection({
  "collection": "",
  "score": ""
}, context)

Input

input object
- collection required string: Unique identifier of the collection.
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).

Output

Output schema unknown

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.

flat.addScoreToCollection({
  "collection": "",
  "score": ""
}, context)

Input

input object
- collection required string: Unique identifier of the collection.
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

output ScoreDetails

untrashCollection

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

flat.untrashCollection({
  "collection": ""
}, context)

Input

input object
- collection required string: Unique identifier of the collection.

Output

Output schema unknown

getGroupDetails

Get group information

flat.getGroupDetails({
  "group": ""
}, context)

Input

input object
- group required string: Unique identifier of a Flat group

Output

output GroupDetails

getGroupScores

Get the list of scores shared with a group.

flat.getGroupScores({
  "group": ""
}, context)

Input

input object
- group required string: Unique identifier of a Flat group
- parent string: Filter the score forked from the score id parent

Output

output array
- items ScoreDetails

listGroupUsers

List group's users

flat.listGroupUsers({
  "group": ""
}, context)

Input

input object
- group required string: Unique identifier of a Flat group

Output

output array
- items UserPublic

getAuthenticatedUser

Get details about the current authenticated User.

flat.getAuthenticatedUser(null, context)

Input

This action has no parameters

Output

output UserDetails

listOrganizationInvitations

List the organization invitations

flat.listOrganizationInvitations({}, context)

Input

input object
- role string (values: user, teacher, admin): Filter users by role
- limit integer: This is the maximum number of objects that may be returned
- next string: An opaque string cursor to fetch the next page of data.
- previous string: An opaque string cursor to fetch the previous page of data.

Output

output array
- items OrganizationInvitation

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.

flat.createOrganizationInvitation({}, context)

Input

input object
- body OrganizationInvitationCreation

Output

output OrganizationInvitation

removeOrganizationInvitation

Remove an organization invitation

flat.removeOrganizationInvitation({
  "invitation": ""
}, context)

Input

input object
- invitation required string: Unique identifier of the invitation

Output

Output schema unknown

listLtiCredentials

List LTI 1.x credentials

flat.listLtiCredentials(null, context)

Input

This action has no parameters

Output

output array
- items LtiCredentials

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 Developer Documentation.

flat.createLtiCredentials({
  "body": {
    "name": "",
    "lms": ""
  }
}, context)

Input

input object
- body required LtiCredentialsCreation

Output

output LtiCredentials

revokeLtiCredentials

Revoke LTI 1.x credentials

flat.revokeLtiCredentials({
  "credentials": ""
}, context)

Input

input object
- credentials required string: Credentials unique identifier

Output

Output schema unknown

listOrganizationUsers

List the organization users

flat.listOrganizationUsers({}, context)

Input

input object
- role string (values: user, teacher, admin): Filter users by role
- limit integer: This is the maximum number of objects that may be returned
- next string: An opaque string cursor to fetch the next page of data.
- previous string: An opaque string cursor to fetch the previous page of data.

Output

output array
- items UserDetailsAdmin

createOrganizationUser

Create a new user account

flat.createOrganizationUser({}, context)

Input

input object
- body UserCreation

Output

output UserDetailsAdmin

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)

flat.removeOrganizationUser({
  "user": ""
}, context)

Input

input object
- user required string: Unique identifier of the Flat account
- convertToIndividual boolean: If true, the account will be only removed from the organization and converted into an individual account on our public website, https://flat.io.

Output

Output schema unknown

updateOrganizationUser

Update account information

flat.updateOrganizationUser({
  "user": "",
  "body": {}
}, context)

Input

input object
- user required string: Unique identifier of the Flat account
- body required UserAdminUpdate

Output

output UserDetailsAdmin

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

flat.createScore({
  "body": {
    "privacy": ""
  }
}, context)

Input

input object
- body required ScoreCreation

Output

output ScoreDetails

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

flat.deleteScore({
  "score": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).

Output

Output schema unknown

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.

flat.getScore({
  "score": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

output ScoreDetails

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

flat.editScore({
  "score": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- body ScoreModification

Output

output ScoreDetails

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

flat.getScoreCollaborators({
  "score": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

output array
- items ResourceCollaborator

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.

flat.addScoreCollaborator({
  "score": "",
  "body": {}
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- body required ResourceCollaboratorCreation

Output

output ResourceCollaborator

removeScoreCollaborator

Remove the specified collaborator from the score

flat.removeScoreCollaborator({
  "score": "",
  "collaborator": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- collaborator required string: Unique identifier of a collaborator permission, or unique identifier of a User, or unique identifier of a Group

Output

Output schema unknown

getScoreCollaborator

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

flat.getScoreCollaborator({
  "score": "",
  "collaborator": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- collaborator required string: Unique identifier of a collaborator permission, or unique identifier of a User, or unique identifier of a Group
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

output ResourceCollaborator

getScoreComments

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

flat.getScoreComments({
  "score": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.
- type string (values: document, inline): Filter the comments by type
- sort string (values: date): Sort
- direction string (values: asc, desc): Sort direction

Output

output array
- items ScoreComment

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.

flat.postScoreComment({
  "score": "",
  "body": {
    "comment": ""
  }
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.
- body required ScoreCommentCreation

Output

output ScoreComment

deleteScoreComment

Delete a comment

flat.deleteScoreComment({
  "score": "",
  "comment": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- comment required string: Unique identifier of a sheet music comment
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

Output schema unknown

updateScoreComment

Update an existing comment

flat.updateScoreComment({
  "score": "",
  "comment": "",
  "body": {}
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- comment required string: Unique identifier of a sheet music comment
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.
- body required ScoreCommentUpdate

Output

output ScoreComment

markScoreCommentUnresolved

Mark the comment as unresolved

flat.markScoreCommentUnresolved({
  "score": "",
  "comment": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- comment required string: Unique identifier of a sheet music comment
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

Output schema unknown

markScoreCommentResolved

Mark the comment as resolved

flat.markScoreCommentResolved({
  "score": "",
  "comment": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- comment required string: Unique identifier of a sheet music comment
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

Output schema unknown

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

flat.forkScore({
  "score": "",
  "body": {}
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.
- body required ScoreFork

Output

output ScoreDetails

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.

flat.getScoreRevisions({
  "score": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

output array
- items ScoreRevision

createScoreRevision

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

flat.createScoreRevision({
  "score": "",
  "body": {
    "data": ""
  }
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- body required ScoreRevisionCreation

Output

output ScoreRevision

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.

flat.getScoreRevision({
  "score": "",
  "revision": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- revision required string: Unique identifier of a score revision. You can use last to fetch the information related to the last version created.
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

output ScoreRevision

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, or a tumbnail of the first page thumbnail.png).

flat.getScoreRevisionData({
  "score": "",
  "revision": "",
  "format": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- revision required string: Unique identifier of a score revision. You can use last to fetch the information related to the last version created.
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.
- parts string: An optional a set of parts to be exported. This parameter must be
- format required string (values: json, mxl, xml, mp3, wav, midi, thumbnail.png): The format of the file you will retrieve
- onlyCached boolean: Only return files already generated and cached in Flat's production

Output

output string

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.

flat.getScoreSubmissions({
  "score": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).

Output

output array
- items AssignmentSubmission

listScoreTracks

List the audio or video tracks linked to a score

flat.listScoreTracks({
  "score": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

output array
- items ScoreTrack

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.

flat.addScoreTrack({
  "score": "",
  "body": {}
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- body required ScoreTrackCreation

Output

output ScoreTrack

deleteScoreTrack

Remove an audio or video track linked to the score

flat.deleteScoreTrack({
  "score": "",
  "track": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- track required string: Unique identifier of a score audio track

Output

Output schema unknown

getScoreTrack

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

flat.getScoreTrack({
  "score": "",
  "track": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- track required string: Unique identifier of a score audio track
- sharingKey string: This sharing key must be specified to access to a score or collection with a privacy mode set to privateLink and the current user is not a collaborator of the document.

Output

output ScoreTrack

updateScoreTrack

Update an audio or video track linked to a score

flat.updateScoreTrack({
  "score": "",
  "track": "",
  "body": {}
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).
- track required string: Unique identifier of a score audio track
- body required ScoreTrackUpdate

Output

output ScoreTrack

untrashScore

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

flat.untrashScore({
  "score": ""
}, context)

Input

input object
- score required string: Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. ScoreDetails.id) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with drive- (e.g. drive-0B000000000).

Output

Output schema unknown

getUser

Get a public profile of a Flat User.

flat.getUser({
  "user": ""
}, context)

Input

input object
- user required string: This route parameter is the unique identifier of the user. You can specify an email instead of an unique identifier. If you are executing this request authenticated, you can use me as a value instead of the current User unique identifier to work on the current authenticated user.

Output

output UserPublic

gerUserLikes

List liked scores

flat.gerUserLikes({
  "user": ""
}, context)

Input

input object
- user required string: Unique identifier of a Flat user. If you authenticated, you can use me to refer to the current user.
- ids boolean: Return only the identifiers of the scores

Output

output array
- items ScoreDetails

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 Collections API instead.

flat.getUserScores({
  "user": ""
}, context)

Input

input object
- user required string: Unique identifier of a Flat user. If you authenticated, you can use me to refer to the current user.
- parent string: Filter the score forked from the score id parent

Output

output array
- items ScoreDetails

Definitions

Assignment

Assignment object: Assignment details
- attachments array
  - items MediaAttachment
- classroom string: The unique identifier of the class where this assignment was posted
- creationDate string: The creation date of this assignment
- creator string: The User unique identifier of the creator of this assignment
- description string: Description and content of the assignment
- dueDate string: The due date of this assignment, late submissions will be marked as
- googleClassroom GoogleClassroomCoursework
- scheduledDate string: The publication (scheduled) date of the assignment.
- state string (values: draft, active, archived): State of the assignment
- submissions array
  - items AssignmentSubmission
- title string: Title of the assignment

AssignmentCopy

AssignmentCopy object: Assignment copy operation
- classroom required string: The destination classroom where the assignment will be copied

AssignmentCreation

AssignmentCreation object: Assignment creation details
- attachments array
  - items ClassAttachmentCreation
- description string: Description and content of the assignment
- dueDate string: The due date of this assignment, late submissions will be marked as paste due. If not set, the assignment won't have a due date.
- scheduledDate string: The publication (scheduled) date of the assignment.
- title string: Title of the assignment

AssignmentSubmission

AssignmentSubmission object: Assignment Submission
- assignment string: Unique identifier of the assignment
- attachments array
  - items MediaAttachment
- classroom string: Unique identifier of the classroom where the assignment was posted
- creationDate string: The date when the submission was created
- creator string: The User identifier of the student who created the submission
- googleClassroom GoogleClassroomSubmission
- id string: Unique identifier of the submission
- returnCreator string: The User unique identifier of the teacher who returned the submission
- returnDate string: The date when the teacher returned the work
- returnFeedback string: The feedback associated with the return
- state string (values: created, turnedIn, returned): State of the submission
- studentComment string: An optionnal comment sent by the student when submitting his work
- submissionDate string: The date when the student submitted his work

AssignmentSubmissionUpdate

AssignmentSubmissionUpdate object: Assignment Submission creation
- attachments array
  - items ClassAttachmentCreation
- returnFeedback string: The feedback associated with the return
- studentComment string: An optionnal comment sent by the student when submitting his work
- submit boolean: If true, the submission will be marked as done

ClassAttachmentCreation

ClassAttachmentCreation object: Attachment creation for an assignment or stream post.
- score string: A unique Flat score identifier. The user creating the assignment must at least have read access to the document. If the user has admin rights, new group permissions will be automatically added for the
- type string (values: flat, link, exercise): The type of the attachment posted
- url string: The URL of the attachment.

ClassCreation

ClassCreation object: Creation of a classroom
- name required string: The name of the new class
- section string: The section of the new class

ClassDetails

ClassDetails object: A classroom
- assignmentsCount number: The number of assignments created in the class
- canvas object: Meta information provided by Canvs LMS
  - domain string: Canvas instance domain (e.g. "canvas.instructure.com")
  - id string: Unique identifier of the course on Canvas
- clever object: Clever.com section-related information
  - creationDate string: The creation date of the section on clever
  - id string: Clever section unique identifier
  - modificationDate string: The last modification date of the section on clever
  - subject string (values: english/language arts, math, science, social studies, language, homeroom/advisory, interventions/online learning, technology and engineering, PE and health, arts and music, other): Normalized subject of the course
  - termEndDate string: End date of the term
  - termName string: Name of the term when this course happens
  - termStartDate string: Beginning date of the term
- creationDate string: The date when the class was create
- description string: An optionnal description for this class
- enrollmentCode string: [Teachers only] The enrollment code that can be used by the students to join the class
- googleClassroom object: Google Classroom course-related information
  - alternateLink string: Absolute link to this course in the Classroom web UI
  - id string: The course identifier on Google Classroom
  - name string: The name of the course on Google Classroom
  - section string: The section of the course on Google Classroom
- googleDrive object: Google Drive course-related information provided by Google Classroom
  - teacherFolderAlternateLink string: [Teachers only] The Drive URL of the teachers' folder
  - teacherFolderId string: [Teachers only] The Drive directory identifier of the teachers' folder
- id string: The unique identifier of the class
- lti object: Meta information provided by the LTI consumer
  - contextId string: Unique context identifier provided
  - contextLabel string: Context label
  - contextTitle string: Context title
- name string: The name of the class
- organization string: The unique identifier of the Organization owning this class
- owner string: The unique identifier of the User owning this class
- section string: The section of the class
- state ClassState
- studentsGroup GroupDetails
- teachersGroup GroupDetails
- theme string: The theme identifier using in Flat User Interface

ClassRoles

ClassRoles string (values: teacher, student): User's Class Role (for Edu users only)

ClassState

ClassState string (values: active, inactive, archived): The state of a classroom

ClassUpdate

ClassUpdate object: Update of a classroom
- name string: The name of the class
- section string: The section of the class

Collection

Collection object: Collection of scores
- app string: If this directory is dedicated to an app, the unique idenfier of this app
- capabilities object: Capabilities the current user has on this collection. Each capability corresponds to a fine-grained action that a user may take.
  - canAddScores boolean: Whether the current user can add scores to the collection
  - canDelete boolean: Whether the current user can delete the collection
  - canDeleteScores boolean: Whether the current user can delete scores from the collection
  - canEdit boolean: Whether the current user can modify the metadata for the collection
  - canShare boolean: Whether the current user can modify the sharing settings for the collection
- collaborators array: The list of the collaborators of the collection
  - items ResourceCollaborator
- collections array: The List of parent collections, which includes all the collections this score is included. Please note that you might not have access to all of them.
  - items string
- creationDate string: The date when the collection was created
- htmlUrl string: The url where the collection can be viewed in a web browser
- id string: Unique identifier of the collection
- privacy CollectionPrivacy
- rights ResourceRights
- sharingKey string: The private sharing key of the collection (available when the privacy mode is set to privateLink)
- title string: The title of the collection
- type CollectionType
- user UserPublicSummary

CollectionCreation

CollectionCreation object
- title required string: The title of the collection

CollectionModification

CollectionModification object: Edit the collection metadata
- title string: The title of the collection

CollectionPrivacy

CollectionPrivacy string (values: private): The collection main privacy mode.

CollectionType

CollectionType string (values: root, regular, sharedWithMe, sharedWithGroup, trash): Type of the collection.

FlatErrorResponse

FlatErrorResponse object
- code string: A corresponding code for this error
- id string: An unique error identifier generated for the request
- message string: A printable message for this message
- param string: The related parameter that caused the error

FlatLocales

FlatLocales string (values: en, es, fr, de, it, ja, ko, nl, pl, pt, ro, ru, tr, zh-Hans): The user language

GoogleClassroomCoursework

GoogleClassroomCoursework object: A coursework on Google Classroom
- alternateLink string: Absolute link to this coursework in the Classroom web UI
- id string: Identifier of the coursework assigned by Classroom
- state string: State of the coursework

GoogleClassroomSubmission

GoogleClassroomSubmission object: A coursework submission on Google Classroom
- alternateLink string: Absolute link to this coursework in the Classroom web UI
- id string: Identifier of the coursework submission assigned by Classroom
- state string: State of the submission on Google Classroom

Group

Group object: A group of users
- creationDate string: The creation date of the group
- id string: The unique identifier of the group
- name string: The display name of the group
- organization string: If the group is related to an organization, this field will contain
- readOnly boolean: True if the group is set in read-only
- type string (values: generic, classTeachers, classStudents): The type of the group:
- usersCount number: The number of users in this group

GroupDetails

GroupDetails object: The details of a group
- creationDate string: The date when the group was create
- id string: The unique identifier of the group
- name string: The displayable name of the group
- organization string: The unique identifier of the Organization owning the group
- readOnly boolean: true if the properties and members of this group are in in read-only
- type GroupType
- usersCount number: The number of students in this group

GroupType

GroupType string (values: generic, classTeachers, classStudents): The type of the group

LicenseMode

LicenseMode string (values: credit, site): Mode of the license

LicenseSources

LicenseSources string (values: order, trial, voucher, distributor, subscription, appStore): Source of the license

LmsName

LmsName string (values: canvas, moodle, schoology, blackboard, desire2learn, sakai, schoolbox, other): LMS name

LtiCredentials

LtiCredentials object: A couple of LTI 1.x OAuth credentials
- consumerKey string: OAuth 1 Consumer Key
- consumerSecret string: OAuth 1 Consumer Secret
- creationDate string: The creation date of thse credentials
- creator string: Unique identifier of the user who created these credentials
- id string: The unique identifier of this couple of credentials
- lastUsage string: The last time these credentials were used
- lms LmsName
- name string: Name of the couple of credentials
- organization string: The unique identifier of the Organization associated to these credentials

LtiCredentialsCreation

LtiCredentialsCreation object: Creation of a couple of LTI 1.x OAuth credentials
- lms required LmsName
- name required string: Name of the couple of credentials

MediaAttachment

MediaAttachment object: Media attachment. The API will automatically resolve the details, oEmbed,
- authorName string: The resolved author name of the attachment
- authorUrl string: The resolved author url of the attachment
- correct boolean: If the attachment is an exercise question, this state will describe if it is correct or not.For exercise assignments only.
- description string: The resolved description of the attachment
- html string: If the attachment type is rich or video, the HTML code of the
- htmlHeight string: If the html is available, the height of the widget
- htmlWidth string: If the html is available, the width of the widget
- revision string: An unique revision identifier of a score
- score string: An unique Flat score identifier
- sharingMode MediaScoreSharingMode
- thumbnailHeight string: If the thumbnailUrl is available, the width of the thumbnail
- thumbnailUrl string: If the attachment type is rich, video, photo or link, a
- thumbnailWidth string: If the thumbnailUrl is available, the width of the thumbnail
- title string: The resolved title of the attachment
- type string (values: rich, photo, video, link, flat, exercise): The type of the assignment resolved:
- url string: The url of the attachment

MediaScoreSharingMode

MediaScoreSharingMode string (values: read, write, copy): The sharing mode of the score for classes post and assignments

OrganizationInvitation

OrganizationInvitation object: Details of an invitation to join an organization
- customCode string: Enrollment code to use when joining this organization
- email string: The email address this invitation was sent to
- id string: The invitation unique identifier
- invitedBy string: The unique identifier of the User who created this invitation
- organization string: The unique identifier of the Organization owning this class
- organizationRole OrganizationRoles
- usedBy string: The unique identifier of the User who used this invitation

OrganizationInvitationCreation

OrganizationInvitationCreation object: The parameters to create an organization invitation
- email string: The email address you want to send the invitation to
- organizationRole OrganizationRoles

OrganizationRoles

OrganizationRoles string (values: admin, billing, teacher, user): User's Organization Role (for Edu users only)

ResourceCollaborator

ResourceCollaborator: A collaborator of a score. The userEmail and group are only available if the requesting user is a collaborator of the related score (in this case these permissions will eventualy not be listed and exposed publicly).
- aclAdmin boolean: True if the current user can manage the current document (i.e. share, delete)
- aclRead boolean: True if the current user can read the current document
- aclWrite boolean: True if the current user can modify the current document.
- isCollaborator boolean: True if the current user is a collaborator of the current document (direct or via group).
- collection string: If this object is a permission of a collection, this property will contain the unique identifier of the collection
- group Group
- id string: The unique identifier of the permission
- score string: If this object is a permission of a score, this property will contain the unique identifier of the score
- user UserPublic
- userEmail string: If the collaborator is not a user of Flat yet, this field will contain his email.

ResourceCollaboratorCreation

ResourceCollaboratorCreation object: Add a collaborator to a resource.
- aclAdmin boolean: True if the related user can can manage the current document, i.e. changing the document permissions and deleting the document
- aclRead boolean: True if the related user can read the score. (probably true if the user has a permission on the document).
- aclWrite boolean: True if the related user can modify the score.
- group string: The unique identifier of a Flat group
- user string: The unique identifier of a Flat user
- userEmail string: Fill this field to invite an individual user by email.
- userToken string: Token received in an invitation to join the score.

ResourceRights

ResourceRights object: The rights of the current user on a score or collection
- aclAdmin boolean: True if the current user can manage the current document (i.e. share, delete)
- aclRead boolean: True if the current user can read the current document
- aclWrite boolean: True if the current user can modify the current document.
- isCollaborator boolean: True if the current user is a collaborator of the current document (direct or via group).

ScoreComment

ScoreComment object: Comment added on a sheet music
- comment string: The comment text that can includes mentions using the following
- context ScoreCommentContext
- date string: The date when the comment was posted
- id string: The comment unique identifier
- mentions array: The list of user identifier mentioned on the score
  - items string
- modificationDate string: The date of the last comment modification
- rawComment string: A raw version of the comment, that can be displayed without parsing
- replyTo string: When the comment is a reply to another comment, the unique identifier of the parent comment
- resolved boolean: For inline comments, the comment can be marked as resolved and will be hidden in the future responses
- resolvedBy string: If the user is marked as resolved, this will contain the unique identifier of the User who marked this comment as resolved
- revision string: The unique identifier of revision the comment was posted
- score string: The unique identifier of the score where the comment was posted
- spam boolean: `true if the message has been detected as spam and hidden from other users
- type string (values: document, inline): The type of the comment
- user string: The author unique identifier

ScoreCommentContext

ScoreCommentContext object: The context of the comment (for inline/contextualized comments). A context will include all the information related to the location of the comment (i.e. score parts, range of measure, time position).
- measureUuids required array: The list of measure UUIds
  - items string
- partUuid required string: The

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@datafire/flat

Installation and Usage

Description

Actions

oauthCallback

Input

Output

oauthRefresh

Input

Output

listClasses

Input

Output

createClass

Input

Output

enrollClass

Input

Output

getClass

Input

Output

updateClass

Input

Output

activateClass

Input

Output

unarchiveClass

Input

Output

archiveClass

Input

Output

listAssignments

Input

Output

createAssignment

Input

Output

copyAssignment

Input

Output

getSubmissions

Input

Output

createSubmission

Input

Output

getSubmission

Input

Output

editSubmission

Input

Output

listClassStudentSubmissions

Input

Output

deleteClassUser

Input

Output

addClassUser

Input

Output

listCollections

Input

Output

createCollection

Input

Output

deleteCollection

Input

Output

getCollection