logo
redocly logoAPI docs by Redocly

Flat API (2.21.0)

Download OpenAPI specification:Download

Flat: developers@flat.io URL: https://flat.io/developers/docs/api/ Terms of Service

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:

Accounts

These API endpoints are related to the Flat account you are currently using. When using an OAuth2 access token, you can use GET /me to get information about the account.

Get current user account

Get details about the current authenticated User.

Authorizations:
OAuth2
query Parameters
onlyId
boolean
Default: false

Only return the user id

Responses

Request samples 

from pprint import pprint
import os

import flat_api
from flat_api.rest import ApiException

configuration = flat_api.Configuration()
configuration.access_token = os.environ['FLAT_ACCESS_TOKEN']
flat_api_client = flat_api.ApiClient(configuration)
try:
    pprint(flat_api.AccountApi(flat_api_client).get_authenticated_user())
except ApiException as e:
    print(e)

Response samples

Content type
application/json
{
  • "id": "000000000000000000000001",
  • "username": "flat",
  • "name": "Flat Team",
  • "printableName": "Flat Team",
  • "picture": "https://flat.io/img/logo_flat.svg",
  • "badges": [
    ],
  • "organization": "string",
  • "organizationRole": "admin",
  • "classRole": "teacher",
  • "htmlUrl": "string",
  • "bio": "string",
  • "registrationDate": "2019-08-24T14:15:22Z",
  • "likedScoresCount": 0,
  • "followersCount": 0,
  • "followingCount": 0,
  • "ownedPublicScoresCount": 0,
  • "likesCount": 0,
  • "playsCount": 0,
  • "coverPicture": "string",
  • "profileTheme": "string",
  • "instruments": [
    ],
  • "links": {
    },
  • "azureDetails": {
    },
  • "privateProfile": true,
  • "locale": "en",
  • "groups": [
    ],
  • "pictureFile": "string",
  • "coverPictureFile": "string"
}

Music scores

Sheet music is the main API object type available for all Flat account. Here is a typical lifecycle for a music score document on Flat:

Create a new score

Use this API method to create a new music score in the current User account. This API endpoints provides 3 ways to create scores:

  • ScoreCreationBuilderData : Create a blank score by providing the list of instruments to use. You can optionally customize the initial key signature, time signature, enable TABs, Chord grids, as well as the page layout.
  • ScoreCreationFileImport: Import an existing MusicXML 3 file (vnd.recordare.musicxml or vnd.recordare.musicxml+xml), a MIDI file (audio/midi), Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar, or MuseScore file to create the new Flat document.
  • ScoreCreationGoogleDriveImport: Import an existing Google Drive file from the connected Google Drive account.

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. When using an OAuth2 access token or a personal token, the score will be automatically added to your dedicated app collection in the account (/v2/collections/app).

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

Authorizations:
OAuth2
Request Body schema: application/json
required
One of
title
required
string

The title of the new score. If the title is too long, the API may trim this one.

If this title is not specified, the API will try to (in this order):

  • Use the title contained in the file (e.g. movement-title or credit-words for MusicXML files).
  • Use the name of the file for files from a specified source (e.g. Google Drive) or the one in the filename property
  • Set a default title (e.g. "New Music Score")
privacy
string (ScorePrivacy)
Default: "private"
Enum: "public" "private" "organizationPublic" "privateLink"

The score main privacy mode.

  • public: The score is public on the Internet. This one can be accessible at the url https://flat.io/score/{score} and can be modified and administred by specified collaborators users.
  • private: The score is private and can be only accessed, modified and administred by specified collaborators users.
  • privateLink: The score is private but can be accessed using a private link htmlUrl or the private key in the property sharingKey.
  • organizationPublic: Available only with Flat for Education. The score is public in the organization: users of the same organization can access to this one. The score can be modified and administred by specified collaborators users.

The score can also be individually shared to a set of users or groups using the different collaborators API methods.

When a file is synchronized from an external source (e.g. Google Drive) and the sharing options are changed on the source, Flat will chose the best privacy mode for the file.

When using a Flat for Education account, some of the modes may not be available if disabled by an administrator of the organization (e.g. by default the public mode is not available).

collection
string

Unique identifier of a collection where the score will be created. If no collection identifier is provided, the score will be stored in the root directory.

googleDriveFolder
string

If the user uses Google Drive and this properties is specified, the file will be created in this directory. The currently user creating the file must be granted to write in this directory.

required
object

Responses

Request samples

Content type
application/json
Example
{
  • "title": "Violin and Piano",
  • "privacy": "private",
  • "builderData": {
    }
}

Response samples

Content type
application/json
{
  • "id": "000000000000000000000000",
  • "title": "My score",
  • "privacy": "private",
  • "user": {},
  • "htmlUrl": "https://flat.io/score/000000000000000000000000",
  • "editHtmlUrl": "string",
  • "subtitle": "string",
  • "lyricist": "string",
  • "arranger": "string",
  • "composer": "string",
  • "description": "string",
  • "tags": [
    ],
  • "creationType": "original",
  • "license": "copyright",
  • "licenseText": "string",
  • "durationTime": 0,
  • "numberMeasures": 0,
  • "mainTempoQpm": 0,
  • "mainKeySignature": 0,
  • "rights": {
    },
  • "collaborators": [
    ],
  • "creationDate": "2019-08-24T14:15:22Z",
  • "modificationDate": "2019-08-24T14:15:22Z",
  • "publicationDate": "2019-08-24T14:15:22Z",
  • "scheduledDeletionDate": "2019-08-24T14:15:22Z",
  • "highlightedDate": "2019-08-24T14:15:22Z",
  • "organization": "string",
  • "parentScore": "string",
  • "instruments": [
    ],
  • "instrumentsNames": [
    ],
  • "samples": [
    ],
  • "googleDriveFileId": "string",
  • "likes": {
    },
  • "comments": {
    },
  • "views": {
    },
  • "plays": {
    },
  • "collections": [
    ]
}

Get a score's metadata

Get the details of a score identified by the score parameter in the URL. The currently authenticated user must have at least a read access to the document to use this API call.

Authorizations:
OAuth2
path Parameters
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).

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

Responses

Response samples

Content type
application/json
{
  • "id": "000000000000000000000000",
  • "title": "My score",
  • "privacy": "private",
  • "user": {},
  • "htmlUrl": "https://flat.io/score/000000000000000000000000",
  • "editHtmlUrl": "string",
  • "subtitle": "string",
  • "lyricist": "string",
  • "arranger": "string",
  • "composer": "string",
  • "description": "string",
  • "tags": [
    ],
  • "creationType": "original",
  • "license": "copyright",
  • "licenseText": "string",
  • "durationTime": 0,
  • "numberMeasures": 0,
  • "mainTempoQpm": 0,
  • "mainKeySignature": 0,
  • "rights": {
    },
  • "collaborators": [
    ],
  • "creationDate": "2019-08-24T14:15:22Z",
  • "modificationDate": "2019-08-24T14:15:22Z",
  • "publicationDate": "2019-08-24T14:15:22Z",
  • "scheduledDeletionDate": "2019-08-24T14:15:22Z",
  • "highlightedDate": "2019-08-24T14:15:22Z",
  • "organization": "string",
  • "parentScore": "string",
  • "instruments": [
    ],
  • "instrumentsNames": [
    ],
  • "samples": [
    ],
  • "googleDriveFileId": "string",
  • "likes": {
    },
  • "comments": {
    },
  • "views": {
    },
  • "plays": {
    },
  • "collections": [
    ]
}

Edit a score's metadata

This API method allows you to change the metadata of a score document (e.g. its title or privacy), all the properties are optional.

To edit the file itself, create a new revision using the appropriate method (POST /v2/scores/{score}/revisions/{revision}).

When editing the title, subtitle, composer, lyricist, arranger or licenseText, the metadatas will be instantly be updated, and a real-time action will be pushed to update the document lazily. This pending document modification will be automatically be saved as a new version by either a connected client or our internal versioning service.

Authorizations:
OAuth2
path Parameters
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).

Request Body schema: application/json
required
title
string

The title of the score

subtitle
string or null

The subtitle of the score

composer
string or null

The composer of the score

lyricist
string or null

The lyricist of the score

arranger
string or null

The arranger of the score

privacy
string (ScorePrivacy)
Default: "private"
Enum: "public" "private" "organizationPublic" "privateLink"

The score main privacy mode.

  • public: The score is public on the Internet. This one can be accessible at the url https://flat.io/score/{score} and can be modified and administred by specified collaborators users.
  • private: The score is private and can be only accessed, modified and administred by specified collaborators users.
  • privateLink: The score is private but can be accessed using a private link htmlUrl or the private key in the property sharingKey.
  • organizationPublic: Available only with Flat for Education. The score is public in the organization: users of the same organization can access to this one. The score can be modified and administred by specified collaborators users.

The score can also be individually shared to a set of users or groups using the different collaborators API methods.

When a file is synchronized from an external source (e.g. Google Drive) and the sharing options are changed on the source, Flat will chose the best privacy mode for the file.

When using a Flat for Education account, some of the modes may not be available if disabled by an administrator of the organization (e.g. by default the public mode is not available).

sharingKey
string^[a-f0-9]{128}$

When using the privacy mode privateLink, this property can be used to set a custom sharing key, otherwise a new key will be generated.

description
string or null <= 2000 characters

Description of the creation

tags
Array of strings

Tags describing the score

creationType
string or null (ScoreCreationType)
Enum: "original" "arrangement" "other" null

The type of creation (an orginal, an arrangement)

license
string or null (ScoreLicense)
Enum: "copyright" "cc0" "cc-by" "cc-by-sa" "cc-by-nd" "cc-by-nc" "cc-by-nc-sa" "cc-by-nc-nd" null

License of the creation. Read more about the Creative Commons licenses on https://creativecommons.org/licenses/

licenseText
string or null

The rights info written on the score

Responses

Request samples

Content type
application/json
{
  • "privacy": "private"
}

Response samples

Content type
application/json
{
  • "id": "000000000000000000000000",
  • "title": "My score",
  • "privacy": "private",
  • "user": {},
  • "htmlUrl": "https://flat.io/score/000000000000000000000000",
  • "editHtmlUrl": "string",
  • "subtitle": "string",
  • "lyricist": "string",
  • "arranger": "string",
  • "composer": "string",
  • "description": "string",
  • "tags": [
    ],
  • "creationType": "original",
  • "license": "copyright",
  • "licenseText": "string",
  • "durationTime": 0,
  • "numberMeasures": 0,
  • "mainTempoQpm": 0,
  • "mainKeySignature": 0,
  • "rights": {
    },
  • "collaborators": [
    ],
  • "creationDate": "2019-08-24T14:15:22Z",
  • "modificationDate": "2019-08-24T14:15:22Z",
  • "publicationDate": "2019-08-24T14:15:22Z",
  • "scheduledDeletionDate": "2019-08-24T14:15:22Z",
  • "highlightedDate": "2019-08-24T14:15:22Z",
  • "organization": "string",
  • "parentScore": "string",
  • "instruments": [
    ],
  • "instrumentsNames": [
    ],
  • "samples": [
    ],
  • "googleDriveFileId": "string",
  • "likes": {
    },
  • "comments": {
    },
  • "views": {
    },
  • "plays": {
    },
  • "collections": [
    ]
}

Delete a score

This method can be used by anyone that has at least read access to the document:

  • 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 collaborator, the score will be unshared (i.e. removed from the account & own collections).
  • When called by another user that has the score in its collections, the score will be removed from all the user collections.
Authorizations:
OAuth2
path Parameters
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).

query Parameters
now
boolean
Default: false

If true, the score deletion will be scheduled to be done ASAP

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

Untrash a score

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

Authorizations:
OAuth2
path Parameters
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).

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

List submissions related to the score

This API call will list the different assignments submissions where the score is attached. This method can be used by anyone that are part of the organization and have at least read access to the document.

Authorizations:
OAuth2
path Parameters
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).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Fork a score

This API call will make a copy of the last revision of the specified score and create a new score. The copy of the score will have a privacy set to private.

When using a Flat for Education account, the inline and contextualized comments will be accessible in the child document.

Authorizations:
OAuth2
path Parameters
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).

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

Request Body schema: application/json
required
collection
string or null
Default: "root"

Unique identifier of a collection where the score will be copied. If no collection identifier is provided, the score will be stored in the root directory. If null is provided, the score won't be added to any collections

googleDriveDisabled
boolean
Default: false

If set to true, the API won't create the score on Google Drive

keepOriginalTitle
boolean

Option to keep the original title of the score (i.e. don't prepend it with "Copy of ", or add the student name in assignment usage).

Responses

Request samples

Content type
application/json
{
  • "collection": "root",
  • "googleDriveDisabled": false,
  • "keepOriginalTitle": true
}

Response samples

Content type
application/json
{
  • "id": "000000000000000000000000",
  • "title": "My score",
  • "privacy": "private",
  • "user": {},
  • "htmlUrl": "https://flat.io/score/000000000000000000000000",
  • "editHtmlUrl": "string",
  • "subtitle": "string",
  • "lyricist": "string",
  • "arranger": "string",
  • "composer": "string",
  • "description": "string",
  • "tags": [
    ],
  • "creationType": "original",
  • "license": "copyright",
  • "licenseText": "string",
  • "durationTime": 0,
  • "numberMeasures": 0,
  • "mainTempoQpm": 0,
  • "mainKeySignature": 0,
  • "rights": {
    },
  • "collaborators": [
    ],
  • "creationDate": "2019-08-24T14:15:22Z",
  • "modificationDate": "2019-08-24T14:15:22Z",
  • "publicationDate": "2019-08-24T14:15:22Z",
  • "scheduledDeletionDate": "2019-08-24T14:15:22Z",
  • "highlightedDate": "2019-08-24T14:15:22Z",
  • "organization": "string",
  • "parentScore": "string",
  • "instruments": [
    ],
  • "instrumentsNames": [
    ],
  • "samples": [
    ],
  • "googleDriveFileId": "string",
  • "likes": {
    },
  • "comments": {
    },
  • "views": {
    },
  • "plays": {
    },
  • "collections": [
    ]
}

List the collaborators

This API call will list the different collaborators of a score and their rights on the document. The returned list will at least contain the owner of the document.

Collaborators can be a single user (the object user will be populated) or a group (the object group will be populated).

Authorizations:
OAuth2
path Parameters
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).

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a new collaborator

Share a score with a single user or a group. This API call allows to add, invite and update the collaborators of a resource.

  • To add an existing Flat user to the resource, specify its unique identifier in the user property.
  • To invite an external user to the resource, specify its email in the userEmail property.
  • To add a Flat group to the resource, specify its unique identifier in the group property.
  • To update an existing collaborator, process the same request with different rights.
Authorizations:
OAuth2
path Parameters
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).

Request Body schema: application/json
required
user
string

The unique identifier of a Flat user

group
string

The unique identifier of a Flat group

userEmail
string

Fill this field to invite an individual user by email.

userToken
string

Token received in an invitation to join the score.

aclRead
boolean
Default: true

True if the related user can read the score. (probably true if the user has a permission on the document).

aclWrite
boolean
Default: false

True if the related user can modify the score.

aclAdmin
boolean
Default: false

True if the related user can can manage the current document, i.e. changing the document permissions and deleting the document

Responses

Request samples

Content type
application/json
{
  • "userEmail": "jdoe@flat.io",
  • "aclRead": true,
  • "aclWrite": true,
  • "aclAdmin": false
}

Response samples

Content type
application/json
{
  • "aclRead": true,
  • "aclWrite": true,
  • "aclAdmin": true,
  • "isCollaborator": true,
  • "id": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "score": "string",
  • "collection": "string",
  • "user": {
    },
  • "group": {
    },
  • "userEmail": "string",
  • "invited": true
}

Get a collaborator

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

Authorizations:
OAuth2
path Parameters
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

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

Responses

Response samples

Content type
application/json
{
  • "aclRead": true,
  • "aclWrite": true,
  • "aclAdmin": true,
  • "isCollaborator": true,
  • "id": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "score": "string",
  • "collection": "string",
  • "user": {
    },
  • "group": {
    },
  • "userEmail": "string",
  • "invited": true
}

Delete a collaborator

Remove the specified collaborator from the score

Authorizations:
OAuth2
path Parameters
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

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

List the audio or video tracks linked to a score

Authorizations:
OAuth2
path Parameters
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).

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

assignment
string

An assignment id with which all the tracks returned will be related to

listAutoTrack
boolean

If true, and if available, return last automatically synchronized Flat's mp3 export as an additional track

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a new video or audio track to the score

Use this method to add new track to the score. This track can then be played on flat.io or in an embedded score. This API method support medias hosted on SoundCloud, YouTube and Vimeo.

Authorizations:
OAuth2
path Parameters
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).

Request Body schema: application/json
required
title
string

Title of the track

default
boolean

True if the track should be used as default audio source

state
string (ScoreTrackState)
Default: "draft"
Enum: "draft" "completed" "deleted"

State of the track

purpose
string (ScoreTrackPurpose)
Default: "common"
Enum: "common" "performanceSubmission"

The purpose of the audio track

url
string

The URL of the track

Array of objects (ScoreTrackPoint)

Responses

Request samples

Content type
application/json
{
  • "title": "Rick Astley - Never Gonna Give You Up",
  • "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  • "default": true,
  • "state": "draft",
  • "synchronizationPoints": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "59ecb20e563736b1e1f75dce",
  • "title": "Rick Astley - Never Gonna Give You Up",
  • "type": "youtube",
  • "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  • "mediaId": "dQw4w9WgXcQ",
  • "creationDate": "2017-10-22T14:58:22.753000Z",
  • "modificationDate": "2017-10-22T14:58:33.424000Z",
  • "default": true,
  • "state": "completed",
  • "creator": "5815d4b53269d90d2c80b71c",
  • "score": "59a29d96f35a6411d7508bdd",
  • "synchronizationPoints": [
    ]
}

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

Authorizations:
OAuth2
path Parameters
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

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

Responses

Response samples

Content type
application/json
{
  • "id": "59ecb20e563736b1e1f75dce",
  • "title": "Rick Astley - Never Gonna Give You Up",
  • "type": "youtube",
  • "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  • "mediaId": "dQw4w9WgXcQ",
  • "creationDate": "2017-10-22T14:58:22.753000Z",
  • "modificationDate": "2017-10-22T14:58:33.424000Z",
  • "default": true,
  • "state": "completed",
  • "creator": "5815d4b53269d90d2c80b71c",
  • "score": "59a29d96f35a6411d7508bdd",
  • "synchronizationPoints": [
    ]
}

Update an audio or video track linked to a score

Authorizations:
OAuth2
path Parameters
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

Request Body schema: application/json
required
title
string

Title of the track

default
boolean

True if the track should be used as default audio source

state
string (ScoreTrackState)
Default: "draft"
Enum: "draft" "completed" "deleted"

State of the track

purpose
string (ScoreTrackPurpose)
Default: "common"
Enum: "common" "performanceSubmission"

The purpose of the audio track

Array of objects (ScoreTrackPoint)

Responses

Request samples

Content type
application/json
{
  • "title": "Rick Astley - Never Gonna Give You Up",
  • "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  • "default": true,
  • "state": "draft",
  • "synchronizationPoints": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "59ecb20e563736b1e1f75dce",
  • "title": "Rick Astley - Never Gonna Give You Up",
  • "type": "youtube",
  • "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  • "mediaId": "dQw4w9WgXcQ",
  • "creationDate": "2017-10-22T14:58:22.753000Z",
  • "modificationDate": "2017-10-22T14:58:33.424000Z",
  • "default": true,
  • "state": "completed",
  • "creator": "5815d4b53269d90d2c80b71c",
  • "score": "59a29d96f35a6411d7508bdd",
  • "synchronizationPoints": [
    ]
}

Remove an audio or video track linked to the score

Authorizations:
OAuth2
path Parameters
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

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

List comments

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

Authorizations:
OAuth2
path Parameters
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).

query Parameters
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
Enum: "document" "inline"

Filter the comments by type

sort
string
Value: "date"

Sort

direction
string
Enum: "asc" "desc"

Sort direction

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Post a new comment

Post a document or a contextualized comment on a document.

Please note that this method includes an anti-spam system for public scores. We don't guarantee that your comments will be accepted and displayed to end-user. Comments are be blocked by returning a 403 HTTP error and hidden from other users when the spam property is true.

Authorizations:
OAuth2
path Parameters
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).

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

Request Body schema: application/json
required
revision
string

The unique indentifier of the revision of the score where the comment was added. If this property is unspecified or contains "last", the API will automatically take the last revision created.

comment
required
string

The comment text that can includes mentions using the following format: @[id:username].

rawComment
string

A raw version of the comment, that can be displayed without the mentions. If you use mentions, this property must be set.

mentions
Array of strings

The list of user identifiers mentioned in this comment

replyTo
string

When the comment is a reply to another comment, the unique identifier of the parent comment

object (ScoreCommentContext)

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

Responses

Request samples

Content type
application/json
{
  • "revision": "000000000000000000000010",
  • "comment": "@[000000000000000000000000:flat] Great work!",
  • "rawComment": "@flat: Great work!",
  • "mentions": [
    ],
  • "replyTo": "000000000000000000000000",
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "id": "000000000000000000000010",
  • "type": "inline",
  • "user": "000000000000000000000001",
  • "score": "000000000000000000000042",
  • "revision": "000000000000000000000011",
  • "replyTo": "000000000000000000000000",
  • "date": "2017-01-26T20:29:10.622000Z",
  • "modificationDate": "2017-01-26T21:29:10.622000Z",
  • "comment": "@[000000000000000000000000:flat] Great work!",
  • "rawComment": "@flat: Great work!",
  • "context": {
    },
  • "mentions": [
    ],
  • "resolved": true,
  • "resolvedBy": "000000000000000000000000",
  • "spam": false
}

Update an existing comment

Authorizations:
OAuth2
path Parameters
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

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

Request Body schema: application/json
required
revision
string

The unique indentifier of the revision of the score where the comment was added. If this property is unspecified or contains "last", the API will automatically take the last revision created.

comment
string [ 1 .. 10000 ] characters

The comment text that can includes mentions using the following format: @[id:username].

rawComment
string [ 1 .. 10000 ] characters

A raw version of the comment, that can be displayed without the mentions. If you use mentions, this property must be set.

object (ScoreCommentContext)

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

Responses

Request samples

Content type
application/json
{
  • "revision": "000000000000000000000011",
  • "comment": "@[000000000000000000000000:flat] Great work!",
  • "rawComment": "@flat: Great work!",
  • "mentions": [
    ],
  • "replyTo": "000000000000000000000000",
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "id": "000000000000000000000010",
  • "type": "inline",
  • "user": "000000000000000000000001",
  • "score": "000000000000000000000042",
  • "revision": "000000000000000000000011",
  • "replyTo": "000000000000000000000000",
  • "date": "2017-01-26T20:29:10.622000Z",
  • "modificationDate": "2017-01-26T21:29:10.622000Z",
  • "comment": "@[000000000000000000000000:flat] Great work!",
  • "rawComment": "@flat: Great work!",
  • "context": {
    },
  • "mentions": [
    ],
  • "resolved": true,
  • "resolvedBy": "000000000000000000000000",
  • "spam": false
}

Delete a comment

Authorizations:
OAuth2
path Parameters
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

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

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

Mark the comment as resolved

Authorizations:
OAuth2
path Parameters
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

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

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

Mark the comment as unresolved

Authorizations:
OAuth2
path Parameters
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

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

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

List the revisions

When creating a score or saving a new version of a score, a revision is created in our storage. This method allows you to list all of them, sorted by last modification.

Depending the plan of the account, this list can be trunked to the few last revisions.

Authorizations:
OAuth2
path Parameters
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).

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new revision

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

Authorizations:
OAuth2
path Parameters
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).

Request Body schema: application/json
required
data
required
string

The data of the score file. It must be a MusicXML 3 file (vnd.recordare.musicxml or vnd.recordare.musicxml+xml), a MIDI file (audio/midi) or a Flat.json (aka Adagio.json) file. Binary payloads (vnd.recordare.musicxml and audio/midi) can be encoded in Base64, in this case the dataEncoding property must match the encoding used for the API request.

dataEncoding
string
Value: "base64"

The optional encoding of the score data. This property must match the encoding used for the data property.

autosave
boolean

Must be set to true if the revision was created automatically.

description
string

A description associated to the revision

Responses

Request samples

Content type
application/json
{
  • "data": "<score-partwise version=\"3.0\"></score-partwise>",
  • "history": [
    ],
  • "autosave": true,
  • "description": "New revision"
}

Response samples

Content type
application/json
{
  • "user": "000000000000000000000020",
  • "collaborators": [
    ],
  • "description": "New revision",
  • "creationDate": "2017-01-26T20:29:10.622000Z",
  • "autosave": true
}

Get a score revision

When creating a score or saving a new version of a score, a revision is created in our storage. This method allows you to get a specific revision metadata.

Authorizations:
OAuth2
path Parameters
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.

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

Responses

Response samples

Content type
application/json
{
  • "user": "000000000000000000000020",
  • "collaborators": [
    ],
  • "description": "New revision",
  • "creationDate": "2017-01-26T20:29:10.622000Z",
  • "autosave": true
}

Get a score revision data

Retrieve the file corresponding to a score revision (the following formats are available): Flat JSON/Adagio JSON json, MusicXML mxl/xml, MP3 mp3, WAV wav, MIDI midi, a tumbnail of the first page thumbnail.png or auto sync points synchronizationPoints.

Authorizations:
OAuth2
path Parameters
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.

format
required
string
Enum: "json" "mxl" "xml" "mp3" "wav" "midi" "thumbnail.png" "synchronizationPoints"

The format of the file you will retrieve

query Parameters
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 uuid to be exported. This parameter must be composed of parts uuids separated by commas. For example "59df645f-bb1c-f1b4-b573-d2afc4491f94,34ef645f-1aef-f3bc-1564-34cca4492b87".

defaultTrack
boolean

When format is mp3, this property is set to true and the score has a default ScoreTrack (mp3), this one will be returned instead of the playback file.

url
boolean

Returns a json with the url in it instead of redirecting

Responses

Response samples

Content type
"string"

Create a new score export task

Some of the exports of a score takes are longer to process than a simple API requests. Use this endpoint to launch a new export of one score hosted on Flat.

Authorizations:
OAuth2
path Parameters
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.

format
required
string
Enum: "mp3" "wav" "practicefirst"

The format of the file that will be generated or the target service name where the file will be exported

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

Request Body schema: application/json
optional
parts
Array of strings

A list of parts to specifically export

Responses

Request samples

Content type
application/json
{
  • "parts": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "state": "created",
  • "format": "string",
  • "score": "string",
  • "progress": {
    },
  • "creationDate": "2019-08-24T14:15:22Z",
  • "modificationDate": "2019-08-24T14:15:22Z",
  • "doneDate": "2019-08-24T14:15:22Z",
  • "result": {
    },
  • "errorHistory": [
    ]
}

List liked scores

Authorizations:
OAuth2
path Parameters
user
required
string

Unique identifier of a Flat user. If you authenticated, you can use me to refer to the current user.

query Parameters
next
string

An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

previous
string

An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

limit
integer [ 1 .. 100 ]
Default: 25

This is the maximum number of objects that may be returned

ids
boolean

Return only the identifiers of the scores

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List user's scores

Get the list of public scores owned by a User. If you want to access to private scores, please use the Collections API. For example GET /v2/collections/allScores/scores to list all recently updated scores.

Authorizations:
OAuth2
path Parameters
user
required
string

Unique identifier of a Flat user. If you authenticated, you can use me to refer to the current user.

query Parameters
paginate
boolean
Default: false

When set to true, the API will return a paginated result. When set to false or unset, the API will return all the scores. If this parameter is unset or false, then limit/sort/direction/next/previous will be ignored.

sort
string
Enum: "creationDate" "modificationDate" "title"

Sort

direction
string
Enum: "asc" "desc"

Sort direction

limit
integer [ 1 .. 100 ]
Default: 25

This is the maximum number of objects that may be returned

next
string

An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

previous
string

An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List group's scores

Get the list of scores shared with a group.

Authorizations:
OAuth2
path Parameters
group
required
string

Unique identifier of a Flat group

query Parameters
parent
string

Filter the score forked from the score id parent

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Collections of music scores

Collections let you organize your content in a Flat account. They work like a regular folder with some specificities:

  • Our design goal here is to create a system similar to a book or a playlist of songs.
  • Collections can't have children collections (except the trash and sharedWithMe that are special collections).
  • 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.

All 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 or retrieving the collection details.

By default, when using an OAuth2 access token or a personal token, all the new scores will be added to a dedicated app collection created in the user account. This collection has an alias app. For example, you can use GET /v2/collections/app/scores to list all the scores created by your app.

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

List the collections

Use this method to list the user's collections contained in parent (by default in the root collection). If no sort option is provided, the collections are sorted by creationDate desc.

Note that this method will not include the parent collection in the listing. For example, if you need the details of the root collection, you can use GET /v2/collections/root.

To fetch your app collection details, you can use GET /v2/collections/app.

Authorizations:
OAuth2
query Parameters
parent
string
Default: "root"

List the collection contained in this parent collection.

This option doesn't provide a complete multi-level collection support. When sharing a collection with someone, this one will have as parent sharedWithMe.

sort
string
Enum: "creationDate" "title"

Sort

direction
string
Enum: "asc" "desc"

Sort direction

limit
integer [ 1 .. 100 ]
Default: 25

This is the maximum number of objects that may be returned

next
string

An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

previous
string

An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new collection

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

Authorizations:
OAuth2
Request Body schema: application/json
required
title
string [ 1 .. 300 ] characters

The title of the collection

privacy
string (CollectionPrivacy)
Value: "private"

The collection main privacy mode.

  • private: The collection is private and can be only accessed, modified and administred by specified collaborators users.

Responses

Request samples

Content type
application/json
{
  • "title": "Jazz scores",
  • "privacy": "private"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "htmlUrl": "string",
  • "type": "root",
  • "privacy": "private",
  • "sharingKey": "string",
  • "app": {
    },
  • "creationDate": "2019-08-24T14:15:22Z",
  • "user": {
    },
  • "organization": "string",
  • "rights": {
    },
  • "collaborators": [
    ],
  • "contents": {
    },
  • "capabilities": {
    },
  • "collections": [
    ]
}

Get collection details

Authorizations:
OAuth2
path Parameters
collection
required
string

Unique identifier of the collection. The following aliases are supported:

  • root: The root collection of the account
  • app: Alias for the current app collection
  • sharedWithMe: Automatically contains new resources that have been shared individually
  • trash: Automatically contains resources that have been deleted
query Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "htmlUrl": "string",
  • "type": "root",
  • "privacy": "private",
  • "sharingKey": "string",
  • "app": {
    },
  • "creationDate": "2019-08-24T14:15:22Z",
  • "user": {
    },
  • "organization": "string",
  • "rights": {
    },
  • "collaborators": [
    ],
  • "contents": {
    },
  • "capabilities": {
    },
  • "collections": [
    ]
}

Update a collection's metadata

Authorizations:
OAuth2
path Parameters
collection
required
string

Unique identifier of the collection. The following aliases are supported:

  • root: The root collection of the account
  • app: Alias for the current app collection
  • sharedWithMe: Automatically contains new resources that have been shared individually
  • trash: Automatically contains resources that have been deleted
Request Body schema: application/json
required
title
string [ 1 .. 300 ] characters

The title of the collection

privacy
string (CollectionPrivacy)
Value: "private"

The collection main privacy mode.

  • private: The collection is private and can be only accessed, modified and administred by specified collaborators users.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "privacy": "private"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "htmlUrl": "string",
  • "type": "root",
  • "privacy": "private",
  • "sharingKey": "string",
  • "app": {
    },
  • "creationDate": "2019-08-24T14:15:22Z",
  • "user": {
    },
  • "organization": "string",
  • "rights": {
    },
  • "collaborators": [
    ],
  • "contents": {
    },
  • "capabilities": {
    },
  • "collections": [
    ]
}

Delete the collection

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

Authorizations:
OAuth2
path Parameters
collection
required
string

Unique identifier of the collection. The following aliases are supported:

  • root: The root collection of the account
  • app: Alias for the current app collection
  • sharedWithMe: Automatically contains new resources that have been shared individually
  • trash: Automatically contains resources that have been deleted

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

Untrash a collection

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

Authorizations:
OAuth2
path Parameters
collection
required
string

Unique identifier of the collection.

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

List the scores contained in a collection

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

For example, to list the scores contained in your app collection, you can use GET /v2/collections/app/scores.

Authorizations:
OAuth2
path Parameters
collection
required
string

Unique identifier of the collection. The following aliases are supported:

  • root: The root collection of the account
  • app: Alias for the current app collection
  • sharedWithMe: Automatically contains new resources that have been shared individually
  • trash: Automatically contains resources that have been deleted
query Parameters
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
Enum: "creationDate" "modificationDate" "title"

Sort

direction
string
Enum: "asc" "desc"

Sort direction

limit
integer [ 1 .. 100 ]
Default: 25

This is the maximum number of objects that may be returned

next
string

An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

previous
string

An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a score to the collection

This operation will add a score to a collection. The default behavior will make the score available across multiple collections. You must have the capability canAddScores on the provided collection to perform the action.

Authorizations:
OAuth2
path Parameters
collection
required
string

Unique identifier of the collection. The following aliases are supported:

  • root: The root collection of the account
  • app: Alias for the current app collection
  • sharedWithMe: Automatically contains new resources that have been shared individually
  • trash: Automatically contains resources that have been deleted
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).

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

Responses

Response samples

Content type
application/json
{
  • "id": "000000000000000000000000",
  • "title": "My score",
  • "privacy": "private",
  • "user": {},
  • "htmlUrl": "https://flat.io/score/000000000000000000000000",
  • "editHtmlUrl": "string",
  • "subtitle": "string",
  • "lyricist": "string",
  • "arranger": "string",
  • "composer": "string",
  • "description": "string",
  • "tags": [
    ],
  • "creationType": "original",
  • "license": "copyright",
  • "licenseText": "string",
  • "durationTime": 0,
  • "numberMeasures": 0,
  • "mainTempoQpm": 0,
  • "mainKeySignature": 0,
  • "rights": {
    },
  • "collaborators": [
    ],
  • "creationDate": "2019-08-24T14:15:22Z",
  • "modificationDate": "2019-08-24T14:15:22Z",
  • "publicationDate": "2019-08-24T14:15:22Z",
  • "scheduledDeletionDate": "2019-08-24T14:15:22Z",
  • "highlightedDate": "2019-08-24T14:15:22Z",
  • "organization": "string",
  • "parentScore": "string",
  • "instruments": [
    ],
  • "instrumentsNames": [
    ],
  • "samples": [
    ],
  • "googleDriveFileId": "string",
  • "likes": {
    },
  • "comments": {
    },
  • "views": {
    },
  • "plays": {
    },
  • "collections": [
    ]
}

Delete a score from the collection

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.

Authorizations:
OAuth2
path Parameters
collection
required
string

Unique identifier of the collection. The following aliases are supported:

  • root: The root collection of the account
  • app: Alias for the current app collection
  • sharedWithMe: Automatically contains new resources that have been shared individually
  • trash: Automatically contains resources that have been deleted
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).

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

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

Users profiles

API methods related to the Flat Community user profiles and Flat for Education profiles

Get a public user profile

Get a profile of a Flat or Flat for Education User.

Authorizations:
OAuth2
path Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "id": "000000000000000000000001",
  • "username": "flat",
  • "name": "Flat Team",
  • "printableName": "Flat Team",
  • "picture": "https://flat.io/img/logo_flat.svg",
  • "badges": [
    ],
  • "organization": "string",
  • "organizationRole": "admin",
  • "classRole": "teacher",
  • "htmlUrl": "string",
  • "bio": "string",
  • "registrationDate": "2019-08-24T14:15:22Z",
  • "likedScoresCount": 0,
  • "followersCount": 0,
  • "followingCount": 0,
  • "ownedPublicScoresCount": 0,
  • "likesCount": 0,
  • "playsCount": 0,
  • "coverPicture": "string",
  • "profileTheme": "string",
  • "instruments": [
    ],
  • "links": {
    }
}

List liked scores

Authorizations:
OAuth2
path Parameters
user
required
string

Unique identifier of a Flat user. If you authenticated, you can use me to refer to the current user.

query Parameters
next
string

An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

previous
string

An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

limit
integer [ 1 .. 100 ]
Default: 25

This is the maximum number of objects that may be returned

ids
boolean

Return only the identifiers of the scores

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List user's scores

Get the list of public scores owned by a User. If you want to access to private scores, please use the Collections API. For example GET /v2/collections/allScores/scores to list all recently updated scores.

Authorizations:
OAuth2
path Parameters
user
required
string

Unique identifier of a Flat user. If you authenticated, you can use me to refer to the current user.

query Parameters
paginate
boolean
Default: false

When set to true, the API will return a paginated result. When set to false or unset, the API will return all the scores. If this parameter is unset or false, then limit/sort/direction/next/previous will be ignored.

sort
string
Enum: "creationDate" "modificationDate" "title"

Sort

direction
string
Enum: "asc" "desc"

Sort direction

limit
integer [ 1 .. 100 ]
Default: 25

This is the maximum number of objects that may be returned

next
string

An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

previous
string

An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Flat for Education Organizations

Flat for Education Organizations

List the organization users

Authorizations:
OAuth2
query Parameters
sort
string

The order to sort the user list

direction
string
Enum: "asc" "desc"

Sort direction

next
string

An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

previous
string

An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

role
Array of strings
Items Enum: "user" "teacher" "admin"

Filter users by role

q
string

The query to search

group
Array of strings

Filter users by group

noActiveLicense
boolean

Filter users who don't have an active license

licenseExpirationDate
Array of strings

Filter users by license expiration date or active / notActive

onlyIds
boolean

Return only user ids

limit
integer [ 1 .. 1000 ]
Default: 25

This is the maximum number of objects that may be returned

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new user account

Authorizations:
OAuth2
Request Body schema: application/json
required
username
required
string [ 1 .. 30 ] characters ^[A-Za-z0-9\-_.]+$

Username of the new account

firstname
string <= 60 characters

First name of the user

lastname
string <= 60 characters

Last name of the user

email
string <email>

Email of the new account

password
required
string <password> [ 6 .. 1000 ] characters

Password of the new account

locale
string (FlatLocales)
Default: "en"
Enum: "en" "en-GB" "es" "fr" "de" "it" "ja" "ja-HIRA" "ko" "nl" "pl" "pt" "pt-BR" "ro" "ru" "sv" "tr" "zh-Hans"

The user language

role
string
Default: "user"
Enum: "user" "teacher" "admin"

Role of the new account

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "firstname": "string",
  • "lastname": "string",
  • "email": "user@example.com",
  • "password": "pa$$word",
  • "locale": "en",
  • "role": "user"
}

Response samples

Content type
application/json
{
  • "id": "000000000000000000000001",
  • "username": "flat",
  • "name": "Flat Team",
  • "printableName": "Flat Team",
  • "picture": "https://flat.io/img/logo_flat.svg",
  • "badges": [
    ],
  • "organization": "string",
  • "organizationRole": "admin",
  • "classRole": "teacher",
  • "htmlUrl": "string",
  • "email": "user@example.com",
  • "lastActivityDate": "2019-08-24T14:15:22Z",
  • "license": {
    },
  • "groups": [
    ]
}

Count the organization users using the provided filters

Authorizations:
OAuth2
query Parameters
role
Array of strings
Items Enum: "user" "teacher" "admin"

Filter users by role

q
string

The query to search

group
Array of strings

Filter users by group

noActiveLicense
boolean

Filter users who don't have an active license

Responses

Response samples

Content type
application/json
0
0

Update account information

Authorizations:
OAuth2
path Parameters
user
required
string

Unique identifier of the Flat account

Request Body schema: application/json
required
password
string <password> [ 6 .. 1000 ] characters

Password of the account

organizationRole
string (OrganizationRoles)
Enum: "admin" "billing" "teacher" "user"

User's Organization Role (for Edu users only)

username
string [ 1 .. 30 ] characters ^[A-Za-z0-9\-_.]+$

Username of the account

firstname
string <= 60 characters

First name of the user

lastname
string <= 60 characters

Last name of the user

email
string <email>

Email of the account

Responses

Request samples

Content type
application/json
{
  • "password": "pa$$word",
  • "organizationRole": "admin",
  • "username": "string",
  • "firstname": "string",
  • "lastname": "string",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "id": "000000000000000000000001",
  • "username": "flat",
  • "name": "Flat Team",
  • "printableName": "Flat Team",
  • "picture": "https://flat.io/img/logo_flat.svg",
  • "badges": [
    ],
  • "organization": "string",
  • "organizationRole": "admin",
  • "classRole": "teacher",
  • "htmlUrl": "string",
  • "email": "user@example.com",
  • "lastActivityDate": "2019-08-24T14:15:22Z",
  • "license": {
    },
  • "groups": [
    ]
}

Remove an account from Flat

This operation removes an account from Flat and its data, including:

  • The music scores created by this user (documents, history, comments, collaboration information)
  • Education related data (assignments and classroom information)
Authorizations:
OAuth2
path Parameters
user
required
string

Unique identifier of the Flat account

query Parameters
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. This operation will remove the education-related data from the account. Before 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.

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

Create a delegated API access token for an organization user

This operation will create an API access token for a chosen organization user. This token will be valid for a limited time and can be used to access the API as the organization user.

Authorizations:
OAuth2
path Parameters
user
required
string

Unique identifier of the Flat account

Request Body schema: application/json
required
scopes
required
Array of strings (AppScopes)
Items Enum: "account.public_profile" "account.email" "account.education_profile" "scores.readonly" "scores.social" "scores" "collections.readonly" "collections.add_scores" "collections" "notifications.readonly" "edu.resources" "edu.resources.readonly" "edu.classes" "edu.classes.readonly" "edu.assignments" "edu.assignments.readonly" "edu.admin" "edu.admin.lti" "edu.admin.lti.readonly" "edu.admin.users" "edu.admin.users.readonly" "tasks.readonly"

List of requested scopes for this credential

Responses

Request samples

Content type
application/json
{
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "0000000000000000",
  • "name": "API Access Token name",
  • "token": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  • "issuedDate": "2022-01-01T00:00:00Z",
  • "expirationDate": "2022-01-01T00:00:00Z",
  • "scopes": [
    ]
}

List the organization invitations

Authorizations:
OAuth2
query Parameters
role
string
Enum: "user" "teacher" "admin"

Filter users by role

limit
integer [ 1 .. 1000 ]
Default: 50

This is the maximum number of objects that may be returned

next
string

An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

previous
string

An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new invitation to join the organization

This method creates and sends invitation for teachers and admins.

Invitations can only be used by new Flat users or users who are not part of the organization yet.

If the email of the user is already associated to a user of your organization, the API will simply update the role of the existing user and won't send an invitation. In this case, the property usedBy will be directly filled with the uniquer identifier of the corresponding user.

Authorizations:
OAuth2
Request Body schema: application/json
required
email
string

The email address you want to send the invitation to

organizationRole
string
Default: "teacher"
Enum: "admin" "teacher"

User's Organization Role

Responses

Request samples

Content type
application/json
{
  • "email": "edu@flat.io",
  • "organizationRole": "teacher"
}

Response samples

Content type
application/json
{
  • "creationDate": "2017-07-02T15:05:15.576000Z",
  • "customCode": "u5raQ7pZ",
  • "email": "edu@flat.io",
  • "id": "59590bab53b1af260610000",
  • "invitedBy": "55b8d8f395c8db031ed00000",
  • "organization": "55df29a6694e4a3953100000",
  • "organizationRole": "teacher"
}

Remove an organization invitation

Authorizations:
OAuth2
path Parameters
invitation
required
string

Unique identifier of the invitation

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

List LTI 1.x credentials

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new couple of LTI 1.x credentials

Flat for Education is a Certified LTI Provider. You can use these API methods to automate the creation of LTI credentials. You can read more about our LTI implementation, supported components and LTI Endpoints in our Developer Documentation.

Authorizations:
OAuth2
Request Body schema: application/json
required
name
required
string <= 300 characters

Name of the couple of credentials

lms
required
string (LmsName)
Enum: "canvas" "moodle" "schoology" "blackboard" "desire2learn" "sakai" "schoolbox" "other"

LMS name

Responses

Request samples

Content type
application/json
{
  • "name": "My couple of credentials for Canvas",
  • "lms": "canvas"
}

Response samples

Content type
application/json
{
  • "id": "59368be5c66caf895ee02387",
  • "name": "My couple of credentials for Canvas",
  • "lms": "canvas",
  • "organization": "5832c801a4bedc05f4fb4993",
  • "creator": "5832bf149995c4024bd6de7d",
  • "creationDate": "2017-06-06T11:03:01.955000Z",
  • "lastUsage": "2017-06-13T16:02:34.324000Z",
  • "consumerKey": "200082F5-FAFD-4C6E-BB19-7DAB5D6264D4",
  • "consumerSecret": "ABCDE1234"
}

Revoke LTI 1.x credentials

Authorizations:
OAuth2
path Parameters
credentials
required
string

Credentials unique identifier

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

Flat for Education Classes

Flat for Education Classes

List submissions related to the score

This API call will list the different assignments submissions where the score is attached. This method can be used by anyone that are part of the organization and have at least read access to the document.

Authorizations:
OAuth2
path Parameters
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).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List the classes available for the current user

Authorizations:
OAuth2
query Parameters
state
string
Default: "active"
Enum: "active" "inactive" "archived"

Filter the classes by state

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new class

Classrooms on Flat allow you to create activities with assignments and post content to a specific group.

When creating a class, Flat automatically creates two groups: one for the teachers of the course, one for the students. The creator of this class is automatically added to the teachers group.

If the classsroom is synchronized with another application like Google Classroom, some of the meta information will automatically be updated.

You can add users to this class using PUT /classes/{class}/users/{user}, they will automatically added to the group based on their role on Flat. Users can also enroll themselves to this class using POST /classes/enroll/{enrollmentCode} and the enrollmentCode returned in the ClassDetails response.

Authorizations:
OAuth2
Request Body schema: application/json
required
name
required
string <= 255 characters

The name of the new class

section
string <= 255 characters

The section of the new class

level
string (ClassGradeLevel)
Enum: "elementary" "middle" "high" "university" "other"

Class grade level

skillsFocused
Array of strings (EduSkillsFocused)
Items Enum: "notation" "sight-reading" "performance-instrumental" "ear-training" "music-theory" "composition" "jazz-ensemble" "music-technology" "other"

Specific skills that will be focused in classroom

size
number or null >= 0

Number of students in the classroom

Responses

Request samples

Content type
application/json
{
  • "name": "Music Theory Course",
  • "section": "Music Theory 101"
}

Response samples

Content type
application/json
{
  • "id": "100000000000000000000001",
  • "state": "active",
  • "name": "Music Theory 101",
  • "section": "Music Theory 101",
  • "organization": "100000000000000000000002",
  • "owner": "100000000000000000000003",
  • "enrollmentCode": "jm447ear",
  • "theme": "blue-8",
  • "assignmentsCount": 10,
  • "creationTime": "2017-01-25T09:47:34.544000Z",
  • "googleClassroom": {},
  • "microsoftGraph": {
    },
  • "googleDrive": {},
  • "lti": {
    },
  • "canvas": {
    }
}

Get the details of a single class

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

Responses

Response samples

Content type
application/json
{
  • "id": "100000000000000000000001",
  • "state": "active",
  • "name": "Music Theory 101",
  • "section": "Music Theory 101",
  • "organization": "100000000000000000000002",
  • "owner": "100000000000000000000003",
  • "enrollmentCode": "jm447ear",
  • "theme": "blue-8",
  • "assignmentsCount": 10,
  • "creationTime": "2017-01-25T09:47:34.544000Z",
  • "googleClassroom": {},
  • "microsoftGraph": {
    },
  • "googleDrive": {},
  • "lti": {
    },
  • "canvas": {
    }
}

Update the class

Update the meta information of the class

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

Request Body schema: application/json
required

Details of the Class

name
string <= 255 characters

The name of the class

section
string <= 255 characters

The section of the class

level
string (ClassGradeLevel)
Enum: "elementary" "middle" "high" "university" "other"

Class grade level

skillsFocused
Array of strings (EduSkillsFocused)
Items Enum: "notation" "sight-reading" "performance-instrumental" "ear-training" "music-theory" "composition" "jazz-ensemble" "music-technology" "other"

Specific skills that will be focused in classroom

size
number or null >= 0

Number of students in the classroom

Responses

Request samples

Content type
application/json
{
  • "name": "Music Theory Course",
  • "section": "Music Theory 101"
}

Response samples

Content type
application/json
{
  • "id": "100000000000000000000001",
  • "state": "active",
  • "name": "Music Theory 101",
  • "section": "Music Theory 101",
  • "organization": "100000000000000000000002",
  • "owner": "100000000000000000000003",
  • "enrollmentCode": "jm447ear",
  • "theme": "blue-8",
  • "assignmentsCount": 10,
  • "creationTime": "2017-01-25T09:47:34.544000Z",
  • "googleClassroom": {},
  • "microsoftGraph": {
    },
  • "googleDrive": {},
  • "lti": {
    },
  • "canvas": {
    }
}

Archive the class

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

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

Responses

Response samples

Content type
application/json
{
  • "id": "100000000000000000000001",
  • "state": "active",
  • "name": "Music Theory 101",
  • "section": "Music Theory 101",
  • "organization": "100000000000000000000002",
  • "owner": "100000000000000000000003",
  • "enrollmentCode": "jm447ear",
  • "theme": "blue-8",
  • "assignmentsCount": 10,
  • "creationTime": "2017-01-25T09:47:34.544000Z",
  • "googleClassroom": {},
  • "microsoftGraph": {
    },
  • "googleDrive": {},
  • "lti": {
    },
  • "canvas": {
    }
}

Unarchive the class

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

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

Responses

Response samples

Content type
application/json
{
  • "id": "100000000000000000000001",
  • "state": "active",
  • "name": "Music Theory 101",
  • "section": "Music Theory 101",
  • "organization": "100000000000000000000002",
  • "owner": "100000000000000000000003",
  • "enrollmentCode": "jm447ear",
  • "theme": "blue-8",
  • "assignmentsCount": 10,
  • "creationTime": "2017-01-25T09:47:34.544000Z",
  • "googleClassroom": {},
  • "microsoftGraph": {
    },
  • "googleDrive": {},
  • "lti": {
    },
  • "canvas": {
    }
}

Activate the class

Mark the class as active. This is mainly used for classes synchronized from Clever that are initially with an inactive state and hidden in the UI.

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

Responses

Response samples

Content type
application/json
{
  • "id": "100000000000000000000001",
  • "state": "active",
  • "name": "Music Theory 101",
  • "section": "Music Theory 101",
  • "organization": "100000000000000000000002",
  • "owner": "100000000000000000000003",
  • "enrollmentCode": "jm447ear",
  • "theme": "blue-8",
  • "assignmentsCount": 10,
  • "creationTime": "2017-01-25T09:47:34.544000Z",
  • "googleClassroom": {},
  • "microsoftGraph": {
    },
  • "googleDrive": {},
  • "lti": {
    },
  • "canvas": {
    }
}

Add a user to the class

This method can be used by a teacher of the class to enroll another Flat user into the class.

Only users that are part of your Organization can be enrolled in a class of this same Organization.

When enrolling a user in the class, Flat will automatically add this user to the corresponding Class group, based on this role in the Organization.

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

user
required
string

Unique identifier of the user

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

Remove a user from the class

This method can be used by a teacher to remove a user from the class, or by a student to leave the classroom.

Warning: Removing a user from the class will remove the associated resources, including the submissions and feedback related to these submissions.

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

user
required
string

Unique identifier of the user

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

List the submissions for a student

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

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

user
required
string

Unique identifier of the user

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Assignments listing

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

Responses

Response samples

Content type
application/json
[]

Assignment creation

Use this method as a teacher to create and post a new assignment to a class.

If the class is synchronized with Google Classroom, the assignment will be automatically posted to your Classroom course.

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

Request Body schema: application/json
required
type
string (AssignmentType)
Enum: "none" "newScore" "scoreTemplate" "sharedWriting" "worksheet" "performance"

Type of the assignment

title
string [ 1 .. 1000 ] characters

Title of the assignment

description
string

Description and content of the assignment

Array of objects (ClassAttachmentCreation)
nbPlaybackAuthorized
number or null

The number of playback authorized on the scores of the assignment.

restrictPlayNote
boolean

Restrict the ability to get an audio feedback every time a student adds or selects a note.

restrictToAudioTracks
boolean

Restrict the audio source to provided audio tracks on a score. Students won't be able to use the editor playback.

toolset
string or null

The id of the toolset to apply to this assignment. The toolset will be copied to the assignment as a dedicated object to prevent unexpected changes when making modifications to the template toolset. This property can be set to null to delete the linked toolset and switch back to all the tools available for this assignment.

coverFile
string or null

The id of the cover to display

cover
string or null

The URL of the cover to display

maxPoints
number or null [ 0 .. 10000 ]

If set, the grading will be enabled for the assignement with this value as the maximum of points

releaseGrades
string
Enum: "auto" "manual"

For worksheets, how grading will work for the assignment:

  • If set to auto, the grades will be automatically released when the student submits the submissions
  • If set to manual, the grades will only be set as draftGrade and will be released when the teacher returns the submissions
shuffleExercises
boolean

Mixing worksheets exercises for each student

state
string
Enum: "draft" "active"

State of the assignment

dueDate
string or null <date-time>

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 or null <date-time>

The publication (scheduled) date of the assignment. If this one is specified, the assignment will only be listed to the teachers of the class.

object

Google Classroom options for this assignment

object

Microsoft Graph options for this assignment

assigneeMode
string
Enum: "everyone" "selected"

Possible modes of assigning assignments

assignedStudents
Array of strings

Identifiers for the students that have access to the assignment

Responses

Request samples

Content type
application/json
{
  • "title": "First assignment",
  • "description": "Get started with Flat",
  • "maxPoints": 100,
  • "attachments": [],
  • "scheduledDate": "2017-06-20T13:56:19.613000Z",
  • "dueDate": "2017-07-12T13:56:19.613000Z"
}

Response samples

Content type
application/json
{}

Copy an assignment

Copy an assignment to a specified class or the resource library

For class assignments:

  • If the original assignment has a due date in the past, this new assignment will be created without a due date.
  • If the class is synchronized with an external app (e.g. Google Classroom), the copied assignment will also be posted on the external app.
Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

Request Body schema: application/json
required
One of
classroom
required
string

The destination classroom where the assignment will be copied

assignment
string

An optional destination assignment where the original assignement will be copied. Must be a draft.

scheduledDate
string <date-time>

The publication (scheduled) date of the assignment. If this one is specified, the assignment will only be listed to the teachers of the class. Alternatively the existing scheduledDate from the copied assignment will be used.

Responses

Request samples

Content type
application/json
Example
{
  • "classroom": "0000000000000000"
}

Response samples

Content type
application/json
{}

Archive the assignment

Archive the assignment

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

Responses

Response samples

Content type
application/json
{}

Unarchive the assignment.

Mark the assignment as active.

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

Responses

Response samples

Content type
application/json
{}

List the students' submissions

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or edit a submission

Use this method as a student to create, update and submit a submission related to an assignment. Students can only set attachments and submit. Teachers can use PUT /classes/{class}/assignments/{assignment}/submissions/{submission} to update a submission by id.

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

Request Body schema: application/json
required
Array of objects (ClassAttachmentCreation)
submit
boolean

If true, the submission will be marked as done

draftGrade
number or null [ 0 .. 10000 ]

Optional grade. If unset, no grade was set. This value is only visible by the teacher, and we will be set to grade once the teacher returns the submission

grade
number or null [ 0 .. 10000 ]

Optional grade. If unset, no grade was set.

exercisesIds
Array of strings or null

The ids of exercises when they need to be in a specific order

return
boolean

If true, the submission will be marked as done

Responses

Request samples

Content type
application/json
{
  • "attachments": [
    ],
  • "submit": true
}

Response samples

Content type
application/json
{
  • "id": "58c4955c226ffff257211a90",
  • "classroom": "58c4725345cd836264f0b29e",
  • "assignment": "58c49068524c03ec576ca43c",
  • "creator": "559eb5c7f0d4d5e46d03781d",
  • "creationDate": "2020-08-12T00:25:00.748000Z",
  • "submissionDate": "2020-08-12T00:45:22.748000Z",
  • "attachments": [
    ],
  • "returnDate": "2020-08-15T00:25:00.748000Z",
  • "returnCreator": "559eb5c7f0d4d5e46d000000",
  • "grade": 80,
  • "draftGrade": 82,
  • "googleClassroom": {}
}

CSV Grades exports

Export list of submissions grades to a CSV file

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

Responses

Excel Grades exports

Export list of submissions grades to an Excel file

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

Responses

Get a student submission

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

submission
required
string

Unique identifier of the submission

Responses

Response samples

Content type
application/json
{
  • "id": "58c4955c226ffff257211a90",
  • "classroom": "58c4725345cd836264f0b29e",
  • "assignment": "58c49068524c03ec576ca43c",
  • "creator": "559eb5c7f0d4d5e46d03781d",
  • "creationDate": "2020-08-12T00:25:00.748000Z",
  • "submissionDate": "2020-08-12T00:45:22.748000Z",
  • "attachments": [
    ],
  • "returnDate": "2020-08-15T00:25:00.748000Z",
  • "returnCreator": "559eb5c7f0d4d5e46d000000",
  • "grade": 80,
  • "draftGrade": 82,
  • "googleClassroom": {}
}

Edit a submission

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

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

submission
required
string

Unique identifier of the submission

Request Body schema: application/json
required
Array of objects (ClassAttachmentCreation)
submit
boolean

If true, the submission will be marked as done

draftGrade
number or null [ 0 .. 10000 ]

Optional grade. If unset, no grade was set. This value is only visible by the teacher, and we will be set to grade once the teacher returns the submission

grade
number or null [ 0 .. 10000 ]

Optional grade. If unset, no grade was set.

exercisesIds
Array of strings or null

The ids of exercises when they need to be in a specific order

return
boolean

If true, the submission will be marked as done

Responses

Request samples

Content type
application/json
{
  • "attachments": [
    ],
  • "submit": true
}

Response samples

Content type
application/json
{
  • "id": "58c4955c226ffff257211a90",
  • "classroom": "58c4725345cd836264f0b29e",
  • "assignment": "58c49068524c03ec576ca43c",
  • "creator": "559eb5c7f0d4d5e46d03781d",
  • "creationDate": "2020-08-12T00:25:00.748000Z",
  • "submissionDate": "2020-08-12T00:45:22.748000Z",
  • "attachments": [
    ],
  • "returnDate": "2020-08-15T00:25:00.748000Z",
  • "returnCreator": "559eb5c7f0d4d5e46d000000",
  • "grade": 80,
  • "draftGrade": 82,
  • "googleClassroom": {}
}

Reset a submission

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

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

submission
required
string

Unique identifier of the submission

Responses

Response samples

Content type
application/json
{
  • "id": "58c4955c226ffff257211a90",
  • "classroom": "58c4725345cd836264f0b29e",
  • "assignment": "58c49068524c03ec576ca43c",
  • "creator": "559eb5c7f0d4d5e46d03781d",
  • "creationDate": "2020-08-12T00:25:00.748000Z",
  • "submissionDate": "2020-08-12T00:45:22.748000Z",
  • "attachments": [
    ],
  • "returnDate": "2020-08-15T00:25:00.748000Z",
  • "returnCreator": "559eb5c7f0d4d5e46d000000",
  • "grade": 80,
  • "draftGrade": 82,
  • "googleClassroom": {}
}

Get the history of the submission

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

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

submission
required
string

Unique identifier of the submission

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List the feedback comments of a submission

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

submission
required
string

Unique identifier of the submission

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a feedback comment to a submission

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

submission
required
string

Unique identifier of the submission

Request Body schema: application/json
required
comment
required
string

The comment text

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "user": "string",
  • "submission": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "modificationDate": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "unread": true
}

Update a feedback comment to a submission

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

submission
required
string

Unique identifier of the submission

comment
required
string

Unique identifier of the comment

Request Body schema: application/json
required
comment
required
string

The comment text

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "user": "string",
  • "submission": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "modificationDate": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "unread": true
}

Delete a feedback comment to a submission

Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

assignment
required
string

Unique identifier of the assignment

submission
required
string

Unique identifier of the submission

comment
required
string

Unique identifier of the comment

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

Create a test student account

Test students account can be created by teachers an admin and be used to experiment the assignments.

  • They are automatically added to the class.
  • They can be reset using this API endpoint (a new account will be created and the previous one scheduled for deletion).
  • These accounts don't use a user license.
Authorizations:
OAuth2
path Parameters
class
required
string

Unique identifier of the class

query Parameters
reset
boolean

If true, the testing account will be re-created.

Responses

Response samples

Content type
application/json
{
  • "id": "000000000000000000000001",
  • "username": "flat",
  • "name": "Flat Team",
  • "printableName": "Flat Team",
  • "picture": "https://flat.io/img/logo_flat.svg",
  • "badges": [
    ],
  • "organization": "string",
  • "organizationRole": "admin",
  • "classRole": "teacher",
  • "htmlUrl": "string",
  • "bio": "string",
  • "registrationDate": "2019-08-24T14:15:22Z",
  • "likedScoresCount": 0,
  • "followersCount": 0,
  • "followingCount": 0,
  • "ownedPublicScoresCount": 0,
  • "likesCount": 0,
  • "playsCount": 0,
  • "coverPicture": "string",
  • "profileTheme": "string",
  • "instruments": [
    ],
  • "links": {
    },
  • "azureDetails": {
    },
  • "privateProfile": true,
  • "locale": "en",
  • "groups": [
    ],
  • "pictureFile": "string",
  • "coverPictureFile": "string"
}

Join a class

Use this method to join a class using an enrollment code given one of the teacher of this class. This code is also available in the ClassDetails returned to the teachers when creating the class or listing / fetching a specific class.

Flat will automatically add the user to the corresponding class group based on this role in the organization.

Authorizations:
OAuth2
path Parameters
enrollmentCode
required
string

The enrollment code, available to the teacher in ClassDetails

Responses

Response samples

Content type
application/json
{
  • "id": "100000000000000000000001",
  • "state": "active",
  • "name": "Music Theory 101",
  • "section": "Music Theory 101",
  • "organization": "100000000000000000000002",
  • "owner": "100000000000000000000003",
  • "enrollmentCode": "jm447ear",
  • "theme": "blue-8",
  • "assignmentsCount": 10,
  • "creationTime": "2017-01-25T09:47:34.544000Z",
  • "googleClassroom": {},
  • "microsoftGraph": {
    },
  • "googleDrive": {},
  • "lti": {
    },
  • "canvas": {
    }
}

Flat for Education Resources [Beta]

Resource libraries in Flat for Education. These API endpoints are in beta and may include breaking changes over the upcoming months.

List education resources in a library or folder

Authorizations:
OAuth2
query Parameters
parent
string
Default: "root"

List the resources contained in this parent library or folder

withoutSubfoldersResources
boolean

For the parent = organization, do not include resources from subfolders. By default in the Resource Library UI, we include resources from subfolders, but for example in a picker like LTI, we don't want to include them.

type
string
Enum: "assignment" "folder"

Filter the returned resources by type

subjects
Array of strings (TeachingTheme)
Items Enum: "composition" "music-theory" "general-music" "band" "choir" "orchestra" "jazz-ensemble" "music-technology" "other"

Filter the returned resources by subjects

assignmentTypes
Array of strings (AssignmentType)
Items Enum: "none" "newScore" "scoreTemplate" "sharedWriting" "worksheet" "performance"

Filter the returned resources by assignment types

grades
Array of strings (Grade)
Items Enum: "1" "2" "3" "4" "5" "6" "7" "8" "9" "10" "11" "12" "university"

Filter the returned resources by grades

sort
string
Default: "creationDate"
Enum: "creationDate" "updateDate" "title"

Sort

direction
string
Enum: "asc" "desc"

Sort direction

limit
integer [ 1 .. 100 ]
Default: 25

This is the maximum number of resources that may be returned

next
string

An opaque string cursor to fetch the next page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

previous
string

An opaque string cursor to fetch the previous page of data. The paginated API URLs are returned in the Link header when requesting the API. These URLs will contain a next and previous cursor based on the available data.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new education resource

Authorizations:
OAuth2
Request Body schema: application/json
required
type
required
string (EduResourceType)
Enum: "assignment" "folder"

Type of an education resource

title
required
string [ 1 .. 1000 ] characters

Title of the resource

parent
string
Default: "root"

Identifier of the parent resource where the new one will created, e.g. a folder id or root

Responses

Request samples

Content type
application/json
{
  • "type": "assignment",
  • "title": "string",
  • "parent": "root"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator": "string",
  • "type": "assignment",
  • "privacy": "private",
  • "tags": [
    ],
  • "parent": "string",
  • "title": "string",
  • "sharingDescription": "string",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "updateDate": "2019-08-24T14:15:22Z",
  • "resource": {},
  • "capabilities": {
    },
  • "subjects": [
    ],
  • "grades": [
    ]
}

List the education libraries

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an education resource

Authorizations:
OAuth2
path Parameters
resource
required
string

Unique identifier of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator": "string",
  • "type": "assignment",
  • "privacy": "private",
  • "tags": [
    ],
  • "parent": "string",
  • "title": "string",
  • "sharingDescription": "string",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "updateDate": "2019-08-24T14:15:22Z",
  • "resource": {},
  • "capabilities": {
    },
  • "subjects": [
    ],
  • "grades": [
    ]
}

Update an education resource metadata

Update any resources metadata (e.g. title).

Use this method to rename education resources folders or assignments.

Authorizations:
OAuth2
path Parameters
resource
required
string

Unique identifier of the resource

Request Body schema: application/json
required
title
string [ 1 .. 1000 ] characters

Title of the resource

sharingDescription
string <= 400 characters

Sharing description of the resource

privacy
string (EduResourcePrivacy)
Default: "private"
Enum: "private" "organizationPublic" "public"

The Education resource privacy mode.

subjects
Array of strings (EduResourceSubjects)
Items Enum: "composition" "music-theory" "general-music" "band" "choir" "orchestra" "jazz-ensemble" "music-technology" "other"

The subjects of this resource, or the subjects of the resources included in the folder

grades
Array of strings (EduResourceGrades)
Items Enum: "1" "2" "3" "4" "5" "6" "7" "8" "9" "10" "11" "12" "university"

The grades of this resource, or the grades of the resources included in the folder.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "sharingDescription": "string",
  • "privacy": "private",
  • "subjects": [
    ],
  • "grades": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator": "string",
  • "type": "assignment",
  • "privacy": "private",
  • "tags": [
    ],
  • "parent": "string",
  • "title": "string",
  • "sharingDescription": "string",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "updateDate": "2019-08-24T14:15:22Z",
  • "resource": {},
  • "capabilities": {
    },
  • "subjects": [
    ],
  • "grades": [
    ]
}

Delete an education resource

Authorizations:
OAuth2
path Parameters
resource
required
string

Unique identifier of the resource

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_ERROR",
  • "message": "Invalid request",
  • "id": "123456789"
}

Move an education resource

Authorizations:
OAuth2
path Parameters
resource
required
string

Unique identifier of the resource

Request Body schema: application/json
required
destination
required
string

Unique identifier of the destination of the folder where to move this resource. This can also be root to move the resource at the root of the user resource library.

Responses

Request samples

Content type
application/json
{
  • "destination": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator": "string",
  • "type": "assignment",
  • "privacy": "private",
  • "tags": [
    ],
  • "parent": "string",
  • "title": "string",
  • "sharingDescription": "string",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "updateDate": "2019-08-24T14:15:22Z",
  • "resource": {},
  • "capabilities": {
    },
  • "subjects": [
    ],
  • "grades": [
    ]
}

Copy an education resource to a Resource Library

Authorizations:
OAuth2
path Parameters
resource
required
string

Unique identifier of the resource

Request Body schema: application/json
required
destination
required
string

Unique identifier of the destination of the folder where to copy this resource. This can also be root to copy the resource at the root of the user resource library.

Responses

Request samples

Content type
application/json
{
  • "destination": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator": "string",
  • "type": "assignment",
  • "privacy": "private",
  • "tags": [
    ],
  • "parent": "string",
  • "title": "string",
  • "sharingDescription": "string",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "updateDate": "2019-08-24T14:15:22Z",
  • "resource": {},
  • "capabilities": {
    },
  • "subjects": [
    ],
  • "grades": [
    ]
}

Copy an education assignment to a teacher demo class

Once a resource library can be published to a class (Assignment.capabilities.canPublishInClass = true), this endpoint can be used for the feature "View as student".

It will ensure the teacher has a demo class, then copy the assignment to the demo class. You can then use POST /classes/{class}/testStudent to create a testing student account in the demo class.

Authorizations:
OAuth2
path Parameters
resource
required
string

Unique identifier of the resource

Responses

Response samples

Content type
application/json
{}

Use an education resource in a class

This endpoint will copy a resource and the underlying resources. The assignment will be created as a draft that can be completed with other options before publishing (e.g. due date, publication date for scheduling, etc.).

Authorizations:
OAuth2
path Parameters
resource
required
string

Unique identifier of the resource

Request Body schema: application/json
required
classroom
required
string

The destination classroom where the resource will be copied.

assignment
string

An optional destination assignment where the original assignement will be copied. Must be a draft.

Responses

Request samples

Content type
application/json
{
  • "classroom": "string",
  • "assignment": "string"
}

Response samples

Content type
application/json
{}

Update an education resource assignment

Authorizations:
OAuth2
path Parameters
resource
required
string

Unique identifier of the resource

Request Body schema: application/json
required
type
string (AssignmentType)
Enum: "none" "newScore" "scoreTemplate" "sharedWriting" "worksheet" "performance"

Type of the assignment

title
string [ 1 .. 1000 ] characters

Title of the assignment

description
string

Description and content of the assignment

Array of objects (ClassAttachmentCreation)
nbPlaybackAuthorized
number or null

The number of playback authorized on the scores of the assignment.

restrictPlayNote
boolean

Restrict the ability to get an audio feedback every time a student adds or selects a note.

restrictToAudioTracks
boolean

Restrict the audio source to provided audio tracks on a score. Students won't be able to use the editor playback.

toolset
string or null

The id of the toolset to apply to this assignment. The toolset will be copied to the assignment as a dedicated object to prevent unexpected changes when making modifications to the template toolset. This property can be set to null to delete the linked toolset and switch back to all the tools available for this assignment.

coverFile
string or null

The id of the cover to display

cover
string or null

The URL of the cover to display

maxPoints
number or null [ 0 .. 10000 ]

If set, the grading will be enabled for the assignement with this value as the maximum of points

releaseGrades
string
Enum: "auto" "manual"

For worksheets, how grading will work for the assignment:

  • If set to auto, the grades will be automatically released when the student submits the submissions
  • If set to manual, the grades will only be set as draftGrade and will be released when the teacher returns the submissions
shuffleExercises
boolean

Mixing worksheets exercises for each student

Responses

Request samples

Content type
application/json
{
  • "title": "First assignment",
  • "description": "Get started with Flat",
  • "maxPoints": 100,
  • "attachments": []
}

Response samples

Content type
application/json
{}

Flat for Education Groups

Flat for Education Groups

Get group information

Authorizations:
OAuth2
path Parameters
group
required
string

Unique identifier of a Flat group

Responses

Response samples

Content type
application/json
{
  • "id": "58c4955c226ffff257211a00",
  • "name": "5th Grade - Teachers",
  • "type": "classTeachers",
  • "organization": "0000000000000000000000042",
  • "creationDate": "2017-07-02T15:02:40.207000Z",
  • "usersCount": 2,
  • "readOnly": false
}

List group's users

Authorizations:
OAuth2
path Parameters
group
required
string

Unique identifier of a Flat group

query Parameters
source
string
Enum: "googleClassroom" "microsoftGraph" "clever"

Filter the users by their source

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List group's scores

Get the list of scores shared with a group.

Authorizations:
OAuth2
path Parameters
group
required
string

Unique identifier of a Flat group

query Parameters
parent
string

Filter the score forked from the score id parent

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Asynchronous tasks

Scheduled and asynchronous tasks

Get a task details

This method can be used to follow a task progression, for example while a score is being exported.

Authorizations:
OAuth2
path Parameters
task
required
string

Unique identifier for the task

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "state": "created",
  • "format": "string",
  • "score": "string",
  • "progress": {
    },
  • "creationDate": "2019-08-24T14:15:22Z",
  • "modificationDate": "2019-08-24T14:15:22Z",
  • "doneDate": "2019-08-24T14:15:22Z",
  • "result": {
    },
  • "errorHistory": [
    ]
}