flatapi
Module flatapi
API
Definitions
ballerinax/flatapi Ballerina library
Overview
Flat is a collaborative music notation platform for creating, sharing and teaching music. The Flat connector lets Ballerina integrations work with scores, collections, comments and collaborators, and with the education features of Flat such as organizations, classes, groups and assignments.
The connector supports version 2.26.2 of the Flat REST API.
Key features
- Create, import, update and delete music scores and manage their collaborators and comments
- Organize scores into collections and browse the scores of a user
- Manage classes, groups, assignments and student submissions for education workflows
- Administer organization users, invitations and LTI configurations
- Convert scanned sheet music into editable scores with optical music recognition jobs
Setup guide
To use the Flat connector you need an access token for the Flat API.
-
Sign in to Flat and open the developer settings.
-
Create a new app, or open an existing one, to obtain a client ID and client secret for OAuth 2.0. To try the connector quickly, generate a personal access token from the same page instead.
-
Request only the scopes your integration needs, for example
scores.readonlyto read scores,scores.socialto post comments,edu.classes.readonlyto read classes oredu.classesto manage them. -
Complete the OAuth 2.0 authorization code flow against
https://flat.io/auth/oauthandhttps://api.flat.io/oauth/access_tokento obtain an access token and a refresh token. -
Store the token in a
Config.tomlfile next to your Ballerina program:flatAccessToken = "<your-access-token>"
Quickstart
To use the Flat connector in your Ballerina application, update the .bal file as follows:
-
Import the
ballerinax/flatapimodule.import ballerinax/flatapi; -
Create a
Config.tomlfile and add the access token.flatAccessToken = "<your-access-token>" -
Create a
flatapi:Clientwith the access token.configurable string flatAccessToken = ?; final flatapi:Client flat = check new ({auth: {token: flatAccessToken}}); -
Invoke an operation, for example retrieve the authenticated user.
public function main() returns error? { flatapi:UserDetails _ = check flat->getAuthenticatedUser(); }
Examples
The Flat connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:
- Class assignment overview - List the active classes of a teacher together with their assignments, and optionally create a class.
- Score feedback review - Print the collaborators and comments on recently updated scores, and optionally post a comment.
Clients
flatapi: Client
Provides access to the Flat music notation platform. Create, import, browse, update and export music scores, and manage education resources such as organizations, classes, rosters and assignments.
Constructor
Gets invoked to initialize the connector.
init (ConnectionConfig config, string serviceUrl)- config ConnectionConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://api.flat.io/v2" - URL of the target service
listBillingCreditsHistory
function listBillingCreditsHistory(map<string|string[]> headers, *ListBillingCreditsHistoryQueries queries) returns CreditTransactionList|errorList credit history
Parameters
- queries *ListBillingCreditsHistoryQueries - Queries to be sent with the request
Return Type
- CreditTransactionList|error - List of credit transactions
listClasses
function listClasses(map<string|string[]> headers, *ListClassesQueries queries) returns ClassDetails[]|errorList the classes available for the current user
Parameters
- queries *ListClassesQueries - Queries to be sent with the request
Return Type
- ClassDetails[]|error - The list of classes
createClass
function createClass(ClassCreation payload, map<string|string[]> headers) returns ClassDetails|errorCreate a new class
Parameters
- payload ClassCreation - Details of the class to create
Return Type
- ClassDetails|error - The new class details
getClass
Get the details of a single class
Parameters
- 'class string - Unique identifier of the class
Return Type
- ClassDetails|error - The new class details
updateClass
function updateClass(string 'class, ClassUpdate payload, map<string|string[]> headers) returns ClassDetails|errorUpdate the class
Return Type
- ClassDetails|error - The new class details
archiveClass
Archive the class
Parameters
- 'class string - Unique identifier of the class
Return Type
- ClassDetails|error - The class details
unarchiveClass
Unarchive the class
Parameters
- 'class string - Unique identifier of the class
Return Type
- ClassDetails|error - The class details
activateClass
Activate the class
Parameters
- 'class string - Unique identifier of the class
Return Type
- ClassDetails|error - The class details
addClassUser
Add a user to the class
Return Type
- error? - The user has been added to the class
deleteClassUser
Remove a user from the class
Return Type
- error? - The user has been removed from the class
listClassStudentSubmissions
function listClassStudentSubmissions(string 'class, string user, map<string|string[]> headers) returns AssignmentSubmission[]|errorList the submissions for a student
Return Type
- AssignmentSubmission[]|error - The list of submissions
listAssignments
function listAssignments(string 'class, map<string|string[]> headers) returns ClassAssignment[]|errorAssignments listing
Parameters
- 'class string - Unique identifier of the class
Return Type
- ClassAssignment[]|error - List of assignments for the class
createClassAssignment
function createClassAssignment(string 'class, ClassAssignmentUpdate payload, map<string|string[]> headers) returns Assignment|errorAssignment creation
Parameters
- 'class string - Unique identifier of the class
- payload ClassAssignmentUpdate - Details of the assignment to create
Return Type
- Assignment|error - The assignment has been created
getAssignment
function getAssignment(string 'class, string assignment, map<string|string[]> headers) returns Assignment|errorGet an assignment
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
Return Type
- Assignment|error - The assignment has been retrieved
updateClassAssignment
function updateClassAssignment(string 'class, string assignment, ClassAssignmentUpdate payload, map<string|string[]> headers) returns Assignment|errorUpdate an assignment
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
- payload ClassAssignmentUpdate - Assignment properties to update
Return Type
- Assignment|error - The assignment has been updated
deleteAssignment
function deleteAssignment(string 'class, string assignment, map<string|string[]> headers) returns error?Delete an assignment
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
Return Type
- error? - The assignment has been deleted
copyAssignment
function copyAssignment(string 'class, string assignment, AssignmentCopy payload, map<string|string[]> headers) returns AssignmentCopyResponse|errorCopy an assignment
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
- payload AssignmentCopy - Destination of the assignment copy
Return Type
- AssignmentCopyResponse|error - The new created assignment
archiveAssignment
function archiveAssignment(string 'class, string assignment, map<string|string[]> headers) returns Assignment|errorArchive the assignment
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
Return Type
- Assignment|error - The assignment details
unarchiveAssignment
function unarchiveAssignment(string 'class, string assignment, map<string|string[]> headers) returns Assignment|errorUnarchive the assignment.
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
Return Type
- Assignment|error - The assignment details
getSubmissions
function getSubmissions(string 'class, string assignment, map<string|string[]> headers) returns AssignmentSubmission[]|errorList the students' submissions
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
Return Type
- AssignmentSubmission[]|error - The submissions
createSubmission
function createSubmission(string 'class, string assignment, AssignmentSubmissionUpdate payload, map<string|string[]> headers) returns AssignmentSubmission|errorCreate or edit a submission
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
- payload AssignmentSubmissionUpdate - Submission content to create, edit or submit
Return Type
- AssignmentSubmission|error - The submission
exportSubmissionsReviewsAsCsv
function exportSubmissionsReviewsAsCsv(string 'class, string assignment, map<string|string[]> headers) returns byte[]|errorCSV Grades exports
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
Return Type
- byte[]|error - List of submissions
exportSubmissionsReviewsAsExcel
function exportSubmissionsReviewsAsExcel(string 'class, string assignment, map<string|string[]> headers) returns byte[]|errorExcel Grades exports
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
Return Type
- byte[]|error - List of submissions
getSubmission
function getSubmission(string 'class, string assignment, string submission, map<string|string[]> headers) returns AssignmentSubmission|errorGet a student submission
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
- submission string - Unique identifier of the submission
Return Type
- AssignmentSubmission|error - A submission
editSubmission
function editSubmission(string 'class, string assignment, string submission, AssignmentSubmissionUpdate payload, map<string|string[]> headers) returns AssignmentSubmission|errorEdit a submission
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
- submission string - Unique identifier of the submission
- payload AssignmentSubmissionUpdate - Submission properties to update
Return Type
- AssignmentSubmission|error - The submission
deleteSubmission
function deleteSubmission(string 'class, string assignment, string submission, map<string|string[]> headers) returns AssignmentSubmission|errorReset a submission
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
- submission string - Unique identifier of the submission
Return Type
- AssignmentSubmission|error - The submission object once reset
getSubmissionHistory
function getSubmissionHistory(string 'class, string assignment, string submission, map<string|string[]> headers) returns AssignmentSubmissionHistory[]|errorGet the history of the submission
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
- submission string - Unique identifier of the submission
Return Type
- AssignmentSubmissionHistory[]|error - The history of the submission
getSubmissionComments
function getSubmissionComments(string 'class, string assignment, string submission, map<string|string[]> headers) returns AssignmentSubmissionComment[]|errorList the feedback comments of a submission
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
- submission string - Unique identifier of the submission
Return Type
- AssignmentSubmissionComment[]|error - The comments of the submission
addSubmissionComment
function addSubmissionComment(string 'class, string assignment, string submission, AssignmentSubmissionCommentCreation payload, map<string|string[]> headers) returns AssignmentSubmissionComment|errorAdd a feedback comment to a submission
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
- submission string - Unique identifier of the submission
- payload AssignmentSubmissionCommentCreation - The feedback comment to add
Return Type
- AssignmentSubmissionComment|error - The comment
updateSubmissionComment
function updateSubmissionComment(string 'class, string assignment, string submission, string comment, AssignmentSubmissionCommentCreation payload, map<string|string[]> headers) returns AssignmentSubmissionComment|errorUpdate a feedback comment to a submission
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
- submission string - Unique identifier of the submission
- comment string - Unique identifier of the comment
- payload AssignmentSubmissionCommentCreation - The updated feedback comment
Return Type
- AssignmentSubmissionComment|error - The comment
deleteSubmissionComment
function deleteSubmissionComment(string 'class, string assignment, string submission, string comment, map<string|string[]> headers) returns error?Delete a feedback comment to a submission
Parameters
- 'class string - Unique identifier of the class
- assignment string - Unique identifier of the assignment
- submission string - Unique identifier of the submission
- comment string - Unique identifier of the comment
Return Type
- error? - The comment has been deleted
createTestStudentAccount
function createTestStudentAccount(string 'class, map<string|string[]> headers, *CreateTestStudentAccountQueries queries) returns UserDetails|errorCreate a test student account
Parameters
- 'class string - Unique identifier of the class
- queries *CreateTestStudentAccountQueries - Queries to be sent with the request
Return Type
- UserDetails|error - Test account created
enrollClass
function enrollClass(string enrollmentCode, map<string|string[]> headers) returns ClassDetails|errorJoin a class
Parameters
- enrollmentCode string - The enrollment code, available to the teacher in
ClassDetails
Return Type
- ClassDetails|error - The new class details
listCollections
function listCollections(map<string|string[]> headers, *ListCollectionsQueries queries) returns Collection[]|errorList the collections
Parameters
- queries *ListCollectionsQueries - Queries to be sent with the request
Return Type
- Collection[]|error - List of collections
createCollection
function createCollection(CollectionCreation payload, map<string|string[]> headers) returns Collection|errorCreate a new collection
Parameters
- payload CollectionCreation - Details of the collection to create
Return Type
- Collection|error - Collection created
getCollection
function getCollection(string collection, map<string|string[]> headers, *GetCollectionQueries queries) returns Collection|errorGet collection details
Parameters
- collection string - Unique identifier of the collection.
The following collection aliases are supported:
root: Deprecated. The root collection of the accountapp: Alias for the current app collectiontrash: Automatically contains resources that have been deleted The following virtual collections are supported:allScores: All the scores contained in the user accountcollaborations: All shared scores by the user or someone elselikes: Liked scores
- queries *GetCollectionQueries - Queries to be sent with the request
Return Type
- Collection|error - Collection details
editCollection
function editCollection(string collection, CollectionModification payload, map<string|string[]> headers) returns Collection|errorUpdate a collection's metadata
Parameters
- collection string - Unique identifier of the collection.
The following collection aliases are supported:
root: Deprecated. The root collection of the accountapp: Alias for the current app collectiontrash: Automatically contains resources that have been deleted The following virtual collections are supported:allScores: All the scores contained in the user accountcollaborations: All shared scores by the user or someone elselikes: Liked scores
- payload CollectionModification - Collection metadata to update
Return Type
- Collection|error - Collection details
deleteCollection
Delete the collection
Parameters
- collection string - Unique identifier of the collection.
The following collection aliases are supported:
root: Deprecated. The root collection of the accountapp: Alias for the current app collectiontrash: Automatically contains resources that have been deleted The following virtual collections are supported:allScores: All the scores contained in the user accountcollaborations: All shared scores by the user or someone elselikes: Liked scores
Return Type
- error? - Collection deleted
untrashCollection
Untrash a collection
Parameters
- collection string - Unique identifier of the collection
Deprecated
listCollectionScores
function listCollectionScores(string collection, map<string|string[]> headers, *ListCollectionScoresQueries queries) returns ScoreDetails[]|errorList the scores contained in a collection
Parameters
- collection string - Unique identifier of the collection.
The following collection aliases are supported:
root: Deprecated. The root collection of the accountapp: Alias for the current app collectiontrash: Automatically contains resources that have been deleted The following virtual collections are supported:allScores: All the scores contained in the user accountcollaborations: All shared scores by the user or someone elselikes: Liked scores
- queries *ListCollectionScoresQueries - Queries to be sent with the request
Return Type
- ScoreDetails[]|error - List of scores
addScoreToCollection
function addScoreToCollection(string collection, string score, map<string|string[]> headers, *AddScoreToCollectionQueries queries) returns ScoreDetails|errorAdd a score to the collection
Parameters
- collection string - Unique identifier of the collection.
The following collection aliases are supported:
root: Deprecated. The root collection of the accountapp: Alias for the current app collectiontrash: Automatically contains resources that have been deleted
- score 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 withdrive-(e.g.drive-0B000000000)
- queries *AddScoreToCollectionQueries - Queries to be sent with the request
Return Type
- ScoreDetails|error - Score details
deleteScoreFromCollection
function deleteScoreFromCollection(string collection, string score, map<string|string[]> headers, *DeleteScoreFromCollectionQueries queries) returns error?Delete a score from the collection
Parameters
- collection string - Unique identifier of the collection.
The following collection aliases are supported:
root: Deprecated. The root collection of the accountapp: Alias for the current app collectiontrash: Automatically contains resources that have been deleted
- score 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 withdrive-(e.g.drive-0B000000000)
- queries *DeleteScoreFromCollectionQueries - Queries to be sent with the request
Return Type
- error? - Score removed from the collection
listEduResources
function listEduResources(map<string|string[]> headers, *ListEduResourcesQueries queries) returns EduResource[]|errorList education resources in a library or folder
Parameters
- queries *ListEduResourcesQueries - Queries to be sent with the request
Return Type
- EduResource[]|error - List of resources
createEduResource
function createEduResource(EduResourceCreation payload, map<string|string[]> headers) returns EduResource|errorCreate a new education resource
Parameters
- payload EduResourceCreation - Details of the education resource to create
Return Type
- EduResource|error - Fetched resource
listEduLibraries
function listEduLibraries(map<string|string[]> headers) returns EduLibrary[]|errorList the education libraries
Return Type
- EduLibrary[]|error - Fetched resource
getEduResource
Get an education resource
Parameters
- 'resource string - Unique identifier of the resource
Return Type
- EduResource|error - Fetched resource
updateEduResource
function updateEduResource(string 'resource, EduResourceUpdate payload, map<string|string[]> headers) returns EduResource|errorUpdate an education resource metadata
Parameters
- 'resource string - Unique identifier of the resource
- payload EduResourceUpdate - Education resource metadata to update
Return Type
- EduResource|error - Fetched resource
deleteEduResource
Delete an education resource
Parameters
- 'resource string - Unique identifier of the resource
Return Type
- error? - Resource deleted
moveEduResource
function moveEduResource(string 'resource, EduResourceMove payload, map<string|string[]> headers) returns EduResource|errorMove an education resource
Parameters
- 'resource string - Unique identifier of the resource
- payload EduResourceMove - Destination folder of the education resource
Return Type
- EduResource|error - Fetched resource
copyEduResource
function copyEduResource(string 'resource, EduResourceCopy payload, map<string|string[]> headers) returns EduResource|errorCopy an education resource to a Resource Library
Parameters
- 'resource string - Unique identifier of the resource
- payload EduResourceCopy - Destination library of the education resource copy
Return Type
- EduResource|error - Fetched resource
copyEduResourceToDemoClass
function copyEduResourceToDemoClass(string 'resource, map<string|string[]> headers) returns ClassAssignment|errorCopy an education assignment to a teacher demo class
Parameters
- 'resource string - Unique identifier of the resource
Return Type
- ClassAssignment|error - Assignment copied to the demo class
useEduResourceInClass
function useEduResourceInClass(string 'resource, EduResourceUseInClass payload, map<string|string[]> headers) returns ClassAssignment|errorUse an education resource in a class
Parameters
- 'resource string - Unique identifier of the resource
- payload EduResourceUseInClass - Class and options for using the education resource
Return Type
- ClassAssignment|error - Assignment copied to the chosen class
createEduResourceLtiLink
function createEduResourceLtiLink(string 'resource, map<string|string[]> headers) returns EduResourceLtiLink|errorCreate an LTI link for an education resource
Parameters
- 'resource string - Unique identifier of the resource
Return Type
- EduResourceLtiLink|error - Created LTI Link
updateEduResourceAssignment
function updateEduResourceAssignment(string 'resource, AssignmentUpdate payload, map<string|string[]> headers) returns Assignment|errorUpdate an education resource assignment
Parameters
- 'resource string - Unique identifier of the resource
- payload AssignmentUpdate - Assignment properties to update on the education resource
Return Type
- Assignment|error - Fetched resource
listGroups
function listGroups(map<string|string[]> headers, *ListGroupsQueries queries) returns GroupDetails[]|errorList groups
Parameters
- queries *ListGroupsQueries - Queries to be sent with the request
Return Type
- GroupDetails[]|error - List of groups
createGroup
function createGroup(GroupCreation payload, map<string|string[]> headers) returns GroupDetails|errorCreate a new group
Parameters
- payload GroupCreation - Details of the group to create
Return Type
- GroupDetails|error - The new group
getGroupDetails
Get group information
Parameters
- group string - Unique identifier of a Flat group
Return Type
- GroupDetails|error - The group details
renameGroup
function renameGroup(string group, RenameGroupRequest payload, map<string|string[]> headers) returns GroupDetails|errorRename a group
Parameters
- group string - Unique identifier of a Flat group
- payload RenameGroupRequest - The new name of the group
Return Type
- GroupDetails|error - Updated group
deleteGroup
Delete a group
Parameters
- group string - Unique identifier of a Flat group
Return Type
- error? - Group deleted
listGroupUsers
function listGroupUsers(string group, map<string|string[]> headers, *ListGroupUsersQueries queries) returns UserPublic[]|errorList group's users
Parameters
- group string - Unique identifier of a Flat group
- queries *ListGroupUsersQueries - Queries to be sent with the request
Return Type
- UserPublic[]|error - The users who are members of the group
addGroupUser
function addGroupUser(string group, AddGroupUserRequest payload, map<string|string[]> headers) returns AddGroupUserResponse|errorAdd a student to a group
Parameters
- group string - Unique identifier of a Flat group
- payload AddGroupUserRequest - The student to add to the group
Return Type
- AddGroupUserResponse|error - Membership created
removeGroupUser
Remove a student from a class group
Return Type
- error? - Membership removed
getGroupScores
function getGroupScores(string group, map<string|string[]> headers, *GetGroupScoresQueries queries) returns ScoreDetails[]|errorList group's scores
Parameters
- group string - Unique identifier of a Flat group
- queries *GetGroupScoresQueries - Queries to be sent with the request
Return Type
- ScoreDetails[]|error - The group's scores
getAuthenticatedUser
function getAuthenticatedUser(map<string|string[]> headers, *GetAuthenticatedUserQueries queries) returns UserDetails|errorGet current user account
Parameters
- queries *GetAuthenticatedUserQueries - Queries to be sent with the request
Return Type
- UserDetails|error - Current user details
getOmrCapabilities
function getOmrCapabilities(GetOmrCapabilitiesHeaders headers) returns OmrCapabilities|errorOMR capabilities and limits
Parameters
- headers GetOmrCapabilitiesHeaders (default {}) - Headers to be sent with the request
Return Type
- OmrCapabilities|error - Capabilities
listOmrJobs
function listOmrJobs(ListOmrJobsHeaders headers, *ListOmrJobsQueries queries) returns OmrJob[]|errorList OMR jobs
Parameters
- headers ListOmrJobsHeaders (default {}) - Headers to be sent with the request
- queries *ListOmrJobsQueries - Queries to be sent with the request
createOmrJob
function createOmrJob(OmrJobCreation payload, CreateOmrJobHeaders headers) returns OmrJob|errorCreate an OMR job
Parameters
- payload OmrJobCreation - Details of the OMR job to create
- headers CreateOmrJobHeaders (default {}) - Headers to be sent with the request
getOmrJob
function getOmrJob(string job, GetOmrJobHeaders headers, *GetOmrJobQueries queries) returns OmrJob|errorGet an OMR job
Parameters
- job string - Unique identifier of the OMR job
- headers GetOmrJobHeaders (default {}) - Headers to be sent with the request
- queries *GetOmrJobQueries - Queries to be sent with the request
deleteOmrJob
function deleteOmrJob(string job, DeleteOmrJobHeaders headers) returns OmrJob|errorDelete an OMR job's data
Parameters
- job string - Unique identifier of the OMR job
- headers DeleteOmrJobHeaders (default {}) - Headers to be sent with the request
addOmrJobFile
function addOmrJobFile(string job, OmrJobFileUpload payload, AddOmrJobFileHeaders headers) returns OmrJobFileUploadResult|errorAdd a file to an OMR job
Parameters
- job string - Unique identifier of the OMR job
- payload OmrJobFileUpload - The page image file to add to the OMR job
- headers AddOmrJobFileHeaders (default {}) - Headers to be sent with the request
Return Type
- OmrJobFileUploadResult|error - File added
getOmrJobFile
function getOmrJobFile(string job, int index, GetOmrJobFileHeaders headers) returns byte[]|errorGet an input page image
Parameters
- job string - Unique identifier of the OMR job
- index int - 0-based index of the input file (page) to fetch
- headers GetOmrJobFileHeaders (default {}) - Headers to be sent with the request
Return Type
- byte[]|error - Page image
startOmrJob
function startOmrJob(string job, StartOmrJobHeaders headers) returns OmrJob|errorStart an OMR job
Parameters
- job string - Unique identifier of the OMR job
- headers StartOmrJobHeaders (default {}) - Headers to be sent with the request
submitOmrJobStep
function submitOmrJobStep(string job, OmrStepName step, OmrStepSubmission payload, SubmitOmrJobStepHeaders headers) returns OmrJob|errorSubmit an interactive step
Parameters
- job string - Unique identifier of the OMR job
- step OmrStepName - The pending step being submitted
- payload OmrStepSubmission - The data submitted for the interactive OMR step
- headers SubmitOmrJobStepHeaders (default {}) - Headers to be sent with the request
getOmrJobExport
function getOmrJobExport(string job, "musicxml"|"mxl"|"midi"|"thumbnail.png" format, GetOmrJobExportHeaders headers) returns byte[]|errorDownload the finalized result
Parameters
- job string - Unique identifier of the OMR job
- format "musicxml"|"mxl"|"midi"|"thumbnail.png" - Export format. New formats may be added over time; request what your client supports.
musicxml: Uncompressed MusicXML (plain text.xml,application/vnd.recordare.musicxml+xml).mxl: Compressed MusicXML (zip archive.mxl,application/vnd.recordare.musicxml), the same notation asmusicxmlbut smaller to download.midi: Standard MIDI file (.mid,audio/midi).thumbnail.png: PNG preview of the first page (image/png)
- headers GetOmrJobExportHeaders (default {}) - Headers to be sent with the request
Return Type
- byte[]|error - Exported file (content type depends on the requested format)
cancelOmrJob
function cancelOmrJob(string job, CancelOmrJobHeaders headers) returns OmrJob|errorCancel an OMR job
Parameters
- job string - Unique identifier of the OMR job
- headers CancelOmrJobHeaders (default {}) - Headers to be sent with the request
listOrganizationUsers
function listOrganizationUsers(map<string|string[]> headers, *ListOrganizationUsersQueries queries) returns UserDetailsAdmin[]|errorList the organization users
Parameters
- queries *ListOrganizationUsersQueries - Queries to be sent with the request
Return Type
- UserDetailsAdmin[]|error - List of users
createOrganizationUser
function createOrganizationUser(UserCreation payload, map<string|string[]> headers) returns UserDetailsAdmin|errorCreate a new user account
Parameters
- payload UserCreation - Details of the user account to create
Return Type
- UserDetailsAdmin|error - New user created
countOrganizationUsers
function countOrganizationUsers(map<string|string[]> headers, *CountOrganizationUsersQueries queries) returns int|errorCount the organization users using the provided filters
Parameters
- queries *CountOrganizationUsersQueries - Queries to be sent with the request
updateOrganizationUser
function updateOrganizationUser(string user, UserAdminUpdate payload, map<string|string[]> headers) returns UserDetailsAdmin|errorUpdate account information
Parameters
- user string - Unique identifier of the Flat account
- payload UserAdminUpdate - Account properties to update
Return Type
- UserDetailsAdmin|error - User updated
removeOrganizationUser
function removeOrganizationUser(string user, map<string|string[]> headers, *RemoveOrganizationUserQueries queries) returns error?Remove an account from Flat
Parameters
- user string - Unique identifier of the Flat account
- queries *RemoveOrganizationUserQueries - Queries to be sent with the request
Return Type
- error? - User deleted
createOrganizationUserSigninLink
function createOrganizationUserSigninLink(string user, UserSigninLinkCreation payload, map<string|string[]> headers) returns UserSigninLink|errorCreate a sign in link for an organization user
Parameters
- user string - Unique identifier of the Flat account
- payload UserSigninLinkCreation - Options for the sign in link
Return Type
- UserSigninLink|error - Sign in link
createOrganizationUserAccessToken
function createOrganizationUserAccessToken(string user, OrganizationUserAccessTokenCreation payload, map<string|string[]> headers) returns ApiAccessToken|errorCreate a delegated API access token for an organization user
Parameters
- user string - Unique identifier of the Flat account
- payload OrganizationUserAccessTokenCreation - Options for the delegated access token
Return Type
- ApiAccessToken|error - Created API access token
listOrganizationInvitations
function listOrganizationInvitations(map<string|string[]> headers, *ListOrganizationInvitationsQueries queries) returns OrganizationInvitation[]|errorList the organization invitations
Parameters
- queries *ListOrganizationInvitationsQueries - Queries to be sent with the request
Return Type
- OrganizationInvitation[]|error - List of invitations
createOrganizationInvitation
function createOrganizationInvitation(OrganizationInvitationCreation payload, map<string|string[]> headers) returns OrganizationInvitation|errorCreate a new invitation to join the organization
Parameters
- payload OrganizationInvitationCreation - Details of the invitation to create
Return Type
- OrganizationInvitation|error - New invitation created
removeOrganizationInvitation
function removeOrganizationInvitation(string invitation, map<string|string[]> headers) returns error?Remove an organization invitation
Parameters
- invitation string - Unique identifier of the invitation
Return Type
- error? - The invitation has been removed
listLtiCredentials
function listLtiCredentials(map<string|string[]> headers) returns LtiCredentials[]|errorList LTI 1.x credentials
Return Type
- LtiCredentials[]|error - The list of LTI Credentials
Deprecated
createLtiCredentials
function createLtiCredentials(LtiCredentialsCreation payload, map<string|string[]> headers) returns LtiCredentials|errorCreate a new pair of LTI 1.1 credentials
Parameters
- payload LtiCredentialsCreation - Details of the LTI 1.1 credentials to create
Return Type
- LtiCredentials|error - The LTI Credentials
Deprecated
revokeLtiCredentials
Revoke LTI 1.x credentials
Parameters
- credentials string - Credentials unique identifier
Return Type
- error? - Credentials revoked
Deprecated
listLtiConfigurations
function listLtiConfigurations(map<string|string[]> headers) returns LtiConfiguration[]|errorList LTI configurations (1.1 and 1.3)
Return Type
- LtiConfiguration[]|error - The list of LTI configurations for the caller's organization
createLtiConfiguration
function createLtiConfiguration(LtiConfigurationCreate payload, map<string|string[]> headers) returns LtiConfiguration|errorCreate a new LTI configuration (1.1 or 1.3)
Parameters
- payload LtiConfigurationCreate - Details of the LTI configuration to create
Return Type
- LtiConfiguration|error - The created LTI configuration
updateLtiConfiguration
function updateLtiConfiguration(string configuration, LtiConfigurationUpdate payload, map<string|string[]> headers) returns LtiConfiguration|errorUpdate an existing LTI configuration (edit 1.3; 1.1 not editable)
Parameters
- configuration string - Configuration unique identifier
- payload LtiConfigurationUpdate - LTI configuration properties to update
Return Type
- LtiConfiguration|error - The updated configuration
deleteLtiConfiguration
Delete an LTI configuration
Parameters
- configuration string - Configuration unique identifier
Return Type
- error? - Configuration deleted
createScore
function createScore(ScoreCreation payload, map<string|string[]> headers) returns ScoreDetails|Task|errorCreate a new score
Parameters
- payload ScoreCreation - Details of the score to create or import
Return Type
- ScoreDetails|Task|error - Score created
getScore
function getScore(string score, map<string|string[]> headers, *GetScoreQueries queries) returns ScoreDetails|errorGet a score's metadata
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- queries *GetScoreQueries - Queries to be sent with the request
Return Type
- ScoreDetails|error - Score details
editScore
function editScore(string score, ScoreModification payload, map<string|string[]> headers) returns ScoreDetails|errorEdit a score's metadata
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- payload ScoreModification - Score metadata to update
Return Type
- ScoreDetails|error - Score details
deleteScore
function deleteScore(string score, map<string|string[]> headers, *DeleteScoreQueries queries) returns error?Delete a score
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- queries *DeleteScoreQueries - Queries to be sent with the request
Return Type
- error? - The score has been removed
untrashScore
Untrash a score
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
Return Type
- error? - The score has been untrashed
getScoreSubmissions
function getScoreSubmissions(string score, map<string|string[]> headers) returns AssignmentSubmission[]|errorList submissions related to the score
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
Return Type
- AssignmentSubmission[]|error - List of submissions
forkScore
function forkScore(string score, ScoreFork payload, map<string|string[]> headers, *ForkScoreQueries queries) returns ScoreDetails|errorFork a score
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- payload ScoreFork - Options for forking the score
- queries *ForkScoreQueries - Queries to be sent with the request
Return Type
- ScoreDetails|error - Score details
getScoreCollaborators
function getScoreCollaborators(string score, map<string|string[]> headers, *GetScoreCollaboratorsQueries queries) returns ResourceCollaborator[]|errorList the collaborators
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- queries *GetScoreCollaboratorsQueries - Queries to be sent with the request
Return Type
- ResourceCollaborator[]|error - List of collaborators
addScoreCollaborator
function addScoreCollaborator(string score, ResourceCollaboratorCreation payload, map<string|string[]> headers) returns ResourceCollaborator|errorAdd a new collaborator
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- payload ResourceCollaboratorCreation - The user, group or email to share the score with
Return Type
- ResourceCollaborator|error - The newly added collaborator metadata
getScoreCollaborator
function getScoreCollaborator(string score, string collaborator, map<string|string[]> headers, *GetScoreCollaboratorQueries queries) returns ResourceCollaborator|errorGet a collaborator
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- collaborator string - Unique identifier of a collaborator permission, or unique identifier of a User, or unique identifier of a Group
- queries *GetScoreCollaboratorQueries - Queries to be sent with the request
Return Type
- ResourceCollaborator|error - Collaborator information
removeScoreCollaborator
function removeScoreCollaborator(string score, string collaborator, map<string|string[]> headers, *RemoveScoreCollaboratorQueries queries) returns error?Delete a collaborator
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- collaborator string - Unique identifier of a collaborator permission, or unique identifier of a User, or unique identifier of a Group
- queries *RemoveScoreCollaboratorQueries - Queries to be sent with the request
Return Type
- error? - The collaborator has been removed
listScoreTracks
function listScoreTracks(string score, map<string|string[]> headers, *ListScoreTracksQueries queries) returns ScoreTrack[]|errorList the audio or video tracks linked to a score
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- queries *ListScoreTracksQueries - Queries to be sent with the request
Return Type
- ScoreTrack[]|error - List of tracks
addScoreTrack
function addScoreTrack(string score, ScoreTrackCreation payload, map<string|string[]> headers) returns ScoreTrackCreationResponse|errorAdd a new video or audio track to the score
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- payload ScoreTrackCreation - Details of the track to add to the score
Return Type
- ScoreTrackCreationResponse|error - Created track
getScoreTrack
function getScoreTrack(string score, string track, map<string|string[]> headers, *GetScoreTrackQueries queries) returns ScoreTrack|errorRetrieve the details of an audio or video track linked to a score
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- track string - Unique identifier of a score audio track
- queries *GetScoreTrackQueries - Queries to be sent with the request
Return Type
- ScoreTrack|error - Track details
updateScoreTrack
function updateScoreTrack(string score, string track, ScoreTrackUpdate payload, map<string|string[]> headers) returns ScoreTrack|errorUpdate an audio or video track linked to a score
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- track string - Unique identifier of a score audio track
- payload ScoreTrackUpdate - Track properties to update
Return Type
- ScoreTrack|error - Updated track
deleteScoreTrack
Remove an audio or video track linked to the score
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- track string - Unique identifier of a score audio track
Return Type
- error? - Track removed
getScoreComments
function getScoreComments(string score, map<string|string[]> headers, *GetScoreCommentsQueries queries) returns ScoreComment[]|errorList comments
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- queries *GetScoreCommentsQueries - Queries to be sent with the request
Return Type
- ScoreComment[]|error - The comments of the score
addScoreComment
function addScoreComment(string score, ScoreCommentCreation payload, map<string|string[]> headers, *AddScoreCommentQueries queries) returns ScoreComment|errorPost a new comment
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- payload ScoreCommentCreation - The comment to post on the score
- queries *AddScoreCommentQueries - Queries to be sent with the request
Return Type
- ScoreComment|error - The new comment
updateScoreComment
function updateScoreComment(string score, string comment, ScoreCommentUpdate payload, map<string|string[]> headers, *UpdateScoreCommentQueries queries) returns ScoreComment|errorUpdate an existing comment
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- comment string - Unique identifier of a sheet music comment
- payload ScoreCommentUpdate - The updated comment
- queries *UpdateScoreCommentQueries - Queries to be sent with the request
Return Type
- ScoreComment|error - The edited comment
deleteScoreComment
function deleteScoreComment(string score, string comment, map<string|string[]> headers, *DeleteScoreCommentQueries queries) returns error?Delete a comment
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- comment string - Unique identifier of a sheet music comment
- queries *DeleteScoreCommentQueries - Queries to be sent with the request
Return Type
- error? - The comment has been deleted
markScoreCommentResolved
function markScoreCommentResolved(string score, string comment, map<string|string[]> headers, *MarkScoreCommentResolvedQueries queries) returns error?Mark the comment as resolved
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- comment string - Unique identifier of a sheet music comment
- queries *MarkScoreCommentResolvedQueries - Queries to be sent with the request
Return Type
- error? - The comment has been marked as resolved
markScoreCommentUnresolved
function markScoreCommentUnresolved(string score, string comment, map<string|string[]> headers, *MarkScoreCommentUnresolvedQueries queries) returns error?Mark the comment as unresolved
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- comment string - Unique identifier of a sheet music comment
- queries *MarkScoreCommentUnresolvedQueries - Queries to be sent with the request
Return Type
- error? - The comment has been unmarked as resolved
getScoreRevisions
function getScoreRevisions(string score, map<string|string[]> headers, *GetScoreRevisionsQueries queries) returns ScoreRevision[]|errorList the revisions
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- queries *GetScoreRevisionsQueries - Queries to be sent with the request
Return Type
- ScoreRevision[]|error - List of revisions
createScoreRevision
function createScoreRevision(string score, ScoreRevisionCreation payload, map<string|string[]> headers) returns ScoreRevision|errorCreate a new revision
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- payload ScoreRevisionCreation - Details of the revision to create
Return Type
- ScoreRevision|error - The new created revision metadata
getScoreRevision
function getScoreRevision(string score, string revision, map<string|string[]> headers, *GetScoreRevisionQueries queries) returns ScoreRevision|errorGet a score revision
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- revision string - Unique identifier of a score revision. You can use
lastto fetch the information related to the last version created
- queries *GetScoreRevisionQueries - Queries to be sent with the request
Return Type
- ScoreRevision|error - Revision metadata
getScoreRevisionData
function getScoreRevisionData(string score, string revision, "json"|"mxl"|"xml"|"abc"|"mp3"|"wav"|"midi"|"flat"|"thumbnail.png"|"synchronizationPoints" format, map<string|string[]> headers, *GetScoreRevisionDataQueries queries) returns byte[]|errorGet a score revision data
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- revision string - Unique identifier of a score revision. You can use
lastto fetch the information related to the last version created
- format "json"|"mxl"|"xml"|"abc"|"mp3"|"wav"|"midi"|"flat"|"thumbnail.png"|"synchronizationPoints" - The format of the file you will retrieve
- queries *GetScoreRevisionDataQueries - Queries to be sent with the request
Return Type
- byte[]|error - Revision data
createExportTask
function createExportTask(string score, string revision, "mp3"|"wav"|"practicefirst" format, TaskExportOptions payload, map<string|string[]> headers, *CreateExportTaskQueries queries) returns Task|errorCreate a new score export task
Parameters
- score 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 withdrive-(e.g.drive-0B000000000)
- revision string - Unique identifier of a score revision. You can use
lastto fetch the information related to the last version created
- format "mp3"|"wav"|"practicefirst" - The format of the file that will be generated or the target service name where the file will be exported
- payload TaskExportOptions - Options of the export task
- queries *CreateExportTaskQueries - Queries to be sent with the request
getTask
Get task details
Parameters
- task string - Unique identifier for the task
getUser
Get a public user profile
Parameters
- user string - This route parameter is the unique identifier of the user. You can specify an email instead of a unique identifier. If you are executing this request authenticated, you can use
meas a value instead of the current User unique identifier to work on the current authenticated user
Return Type
- UserPublic|error - The user public details
getUserLikes
function getUserLikes(string user, map<string|string[]> headers, *GetUserLikesQueries queries) returns ScoreDetails[]|errorList liked scores
Parameters
- user string - Unique identifier of a Flat user. If you authenticated, you can use
meto refer to the current user
- queries *GetUserLikesQueries - Queries to be sent with the request
Return Type
- ScoreDetails[]|error - List of liked scores
getUserScores
function getUserScores(string user, map<string|string[]> headers, *GetUserScoresQueries queries) returns ScoreDetails[]|errorList user's scores
Parameters
- user string - Unique identifier of a Flat user. If you authenticated, you can use
meto refer to the current user
- queries *GetUserScoresQueries - Queries to be sent with the request
Return Type
- ScoreDetails[]|error - The user scores
Records
flatapi: AddGroupUserRequest
Fields
- user string - ID of the student to add
flatapi: AddGroupUserResponse
Fields
- user? string - User ID that was added
flatapi: AddOmrJobFileHeaders
Represents the Headers record for the operation: addOmrJobFile
Fields
- xFlatLocale? string - Preferred locale for localized content in the response (translated error messages, emails, etc.).
Accepts any IETF language tag. The API best-matches the value to a supported locale and never rejects an unknown one (it falls back to the closest match, then to
en). Supported normalized locales:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ko,ms,nl,nb,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW. Precedence (highest first): thisX-Flat-Localeheader, the authenticated user's account locale, theAccept-Languageheader, thenen
flatapi: AddScoreCommentQueries
Represents the Queries record for the operation: addScoreComment
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: AddScoreToCollectionQueries
Represents the Queries record for the operation: addScoreToCollection
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: ApiAccessToken
An API access token
Fields
- issuedDate? string - The date when this token was issued
- name? string - Name of the personal access token
- id? string - Unique identifier of this private token
- scopes? AppScopes[] - The list of scopes associated to the token
- token? string - The token. This token will only be returned once, then only the first 4 characters will be returned
- expirationDate? string - The date when this token will expire
flatapi: Assignment
Assignment details
Fields
- toolset? string - The id of the associated toolset
- attachments MediaAttachment[] - Reference material handed to the students with the assignment: scores, videos, links and Drive files. A score attached here is the one each student receives their own copy of
- teacherInstructionsHtml? string - HTML version of teacher-only instructions with rich text formatting. Supports the following HTML tags: p, br, strong, b, em, i, u, a, ul, ol, li, h1, h2, h3, img. Images are served as absolute http(s) URLs
- description? string - Student instructions and content of the assignment (plain text)
- releaseGrades? "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 asdraftGradeand will be released when the teacher returns the submissions
- If set to
- restrictPlayNote? boolean - Restrict the ability to get an audio feedback every time a student adds or selects a note
- 'type AssignmentType - Type of the assignment
- title string - Title of the assignment
- freeRecord? boolean - For performance assignments: "Free Record" mode.
When
true, no score is attached to the assignment. Students freely record a varied repertoire or an ensemble performance without being constrained by a single score's structure or duration, and all score-dependent options (playback, metronome, backtracking, speed control) are hidden. Only set when type is 'performance'
- allowMetronome? boolean - For performance assignments: Enable students to use the metronome while they are recording, helping them stay in time. Only set when type is 'performance'
- cover? string - The URL of the cover to display
- teacherInstructions? string - Teacher-only instructions for this assignment.
These instructions are only visible to teachers and are not returned when students view the assignment.
If
teacherInstructionsHtmlis provided, this field will contain the plain text version for compatibility
- maxPoints? decimal - If set, the grading will be enabled for the assignment
- recordingType? "audio"|"video" - For performance assignments: recording type that will be either 'audio' or 'video'.
audio: Only audio will be required during the recording.video: Camera will be required during the recording.
- submissionStudentsMode? AssignmentSubmissionStudentsMode - Submission mode for assignments:
- "single": Individual submissions (default)
- "group": Group submissions (for shared writing assignments)
- nbPlaybackAuthorized? decimal - The number of playbacks authorized on the scores of the assignment
- id string - Unique identifier of the assignment
- useDedicatedAttachments? boolean - For all assignments created after 02/2023, all the underlying resources must be dedicated and stored in the assignment. This boolean indicates that this assignment only supports dedicated attachments
- shuffleExercises? boolean - Shuffle the worksheet exercises for each student
- allowSpeedChange? boolean - For performance assignments: whether students can adjust the playback speed of the score during recording.
true: Students can change the tempo/speed during practice and recordingfalse: Tempo is fixed to the original score tempo
- capabilities AssignmentCapabilities - Capabilities the current user has on this assignment. Each capability corresponds to a fine-grained action that a user may take
- coverFile? string - The id of the cover to display
- restrictToAudioTracks? boolean - Restrict the audio source to provided audio tracks on a score. Students won't be able to use the editor playback
- allowBackingTrack? boolean - For performance assignments: Enable students to listen to the accompaniment without their instrument part while they are playing. Only set when type is 'performance'
- descriptionHtml? string - HTML version of student instructions with rich text formatting. Supports the following HTML tags: p, br, strong, b, em, i, u, a, ul, ol, li, h1, h2, h3, img. Images are served as absolute http(s) URLs
flatapi: AssignmentCapabilities
Capabilities the current user has on this assignment. Each capability corresponds to a fine-grained action that a user may take
Fields
- canPublishInClass boolean - Whether this assignment can be published in a class
- canArchive boolean - Whether the current user can archive the assignment
- canUnarchive boolean - Whether the current user can unarchive the assignment
- canEdit boolean - Whether the current user can edit the assignment
- canPublishInClassError? AssignmentCapabilitiesCanPublishInClassError - If
canPublishInClassandcanEditare false, the issue why this assignment cannot be published in a class
flatapi: AssignmentCapabilitiesCanPublishInClassError
If canPublishInClass and canEdit are false, the issue why this assignment cannot be published in a class
Fields
- code string - A corresponding code for this error
- message string - A printable and localized message for this error
flatapi: AssignmentCopyResponse
Fields
- Fields Included from *Assignment
- toolset string
- attachments MediaAttachment[]
- teacherInstructionsHtml string
- description string
- releaseGrades "auto"|"manual"
- restrictPlayNote boolean
- type AssignmentType
- title string
- freeRecord boolean
- allowMetronome boolean
- cover string
- teacherInstructions string
- maxPoints decimal
- recordingType "audio"|"video"
- submissionStudentsMode AssignmentSubmissionStudentsMode
- nbPlaybackAuthorized decimal
- id string
- useDedicatedAttachments boolean
- shuffleExercises boolean
- allowSpeedChange boolean
- capabilities AssignmentCapabilities
- coverFile string
- restrictToAudioTracks boolean
- allowBackingTrack boolean
- descriptionHtml string
- anydata...
- 'resource? string - If this assignment is stored as a resource in the Flat for Education Resource Library, the unique identifier of the resource
flatapi: AssignmentCopyToClass
Copy the assignment to a class
Fields
- assignment? string - An optional destination assignment where the original assignment will be copied. Must be a draft
- scheduledDate? string - 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
scheduledDatefrom the copied assignment will be used
- classroom string - The destination classroom where the assignment will be copied
flatapi: AssignmentCopyToResourceLibrary
Copy the assignment to the EDU Resource Library
Fields
- verifyIfNotAlreadyInResourceLibrary? boolean - Option to check if the assignment is already in Resource Library
- libraryParent string - Identifier of the parent resource where the new one will be created, e.g. a folder id or
root
flatapi: AssignmentGroup
A group assigned to an assignment for shared writing assignments
Fields
- parent? string - The unique identifier of the parent class group. Only available for groups of type 'assignmentStudentsSubGroup'. May be null if the parent class group was deleted
- members string[] - Array of user IDs that are members of this group
- name string - The display name of the group
- id string - The unique identifier of the group
flatapi: AssignmentSubmission
Assignment Submission
Fields
- lti? AssignmentSubmissionLti - If set, this submission has a linked LTI 1.3 AGS or LTI 1.1 Outcomes
- creator string - The User identifier of the student who created the submission
- attachments MediaAttachment[] - The attachments of the submission
- comments AssignmentSubmissionComments - The feedback comments counters of the submission
- assignment string - Unique identifier of the assignment
- googleClassroom? GoogleClassroomSubmission - A coursework submission on Google Classroom
- classroom string - Unique identifier of the classroom where the assignment was posted
- submissionDate? string - The date when the student submitted their work
- creationDate string - The date when the submission was created
- draftGrade? decimal? - Optional grade. If unset, no grade was set. This value is only visible to the teacher, and is copied to
gradeonce the teacher returns the submission
- returnDate? string - The date when the teacher returned the work
- maxPoints? decimal - Optional max points for the grade. If set, a corresponding
draftGradeorgradewill be set
- grade? decimal? - Optional grade. If unset, no grade was set
- playback AssignmentSubmissionPlayback[] - The playback statistics of the submission scores
- id string - Unique identifier of the submission
- state AssignmentSubmissionState - State of the submission
- microsoftGraph? MicrosoftGraphSubmission - The Microsoft Graph submission linked to this submission
- exercisesIds? string[] - The ids of exercises when they need to be in a specific order
- returnCreator? string - The User unique identifier of the teacher who returned the submission
flatapi: AssignmentSubmissionComment
Feedback comment added to an assignment submission
Fields
- date? string - The date when the comment was posted
- modificationDate? string - The date of the last comment modification
- unread? boolean - True if the comment is unread by the current user
- submission? string - The submission unique identifier
- comment? string - The comment text
- id? string - The comment unique identifier
- user? string - The author unique identifier
flatapi: AssignmentSubmissionCommentCreation
Creation of an assignment submission comment
Fields
- comment string - The comment text
flatapi: AssignmentSubmissionComments
The feedback comments counters of the submission
Fields
- total? decimal - The total number of comments added to the submission
- unread? decimal - The number of unread comments for the current user
flatapi: AssignmentSubmissionHistory
History item of the submission
Fields
- date string - The date when the submission was changed
- assignment? string - The assignment unique identifier where the submission was changed
- dueDate? string - The due date of this assignment
- classroom? string - The classroom unique identifier where the submission was changed
- 'source? "lti"|"googleClassroom"|"microsoftGraph" - The source of the change if the change was made by a third-party software
- users string[] - The user(s) unique identifier(s) who made the change
- draftGrade? decimal - The numerator of the grade at this time in the submission grade history
- attachment? AssignmentSubmissionHistoryAttachment - The attachment that changed
- maxPoints? decimal - The denominator of the grade at this time in the submission grade history
- grade? decimal - The numerator of the grade at this time in the submission grade history
- submission? string - The submission unique identifier
- comment? string - The comment that is made to this submission
- state? AssignmentSubmissionHistoryState - State of the submission history
flatapi: AssignmentSubmissionHistoryAttachment
The attachment that changed
Fields
- score? string - The score identifier that changed
- title? string - The title of the score that changed
- revision? string - The revision identifier that changed
flatapi: AssignmentSubmissionLti
If set, this submission has a linked LTI 1.3 AGS or LTI 1.1 Outcomes
Fields
- sourcedid? string - The sourcedid of the LTI submission when using LTI Outcomes
- gradeService "ags2p0"|"outcomes1p1" - The kind of grading service available for this submission:
ags2p0: LTI 1.3 Assignment and Grade Services 2.0outcomes1p1: LTI 1.1 Outcomes 1.1
flatapi: AssignmentSubmissionPlayback
Playback used by a student for an assignment submission
Fields
- score string - The score unique identifier
- nbPlayAttempt decimal - Number of times the score was played
flatapi: AssignmentSubmissionUpdate
Assignment Submission creation
Fields
- draftGrade? decimal? - Optional grade. If unset, no grade was set. This value is only visible to the teacher, and is copied to
gradeonce the teacher returns the submission
- attachments? ClassAttachmentCreation[] - The attachments to set on the submission
- submit? boolean - If
true, the submission will be marked as done
- grade? decimal? - Optional grade. If unset, no grade was set
- playback? AssignmentSubmissionPlayback[] - The playback statistics of the submission scores
- exercisesIds? string[]? - The ids of exercises when they need to be in a specific order
- 'return? boolean - If
true, the submission will be returned to the student (teachers only)
flatapi: AssignmentUpdate
Assignment Resource Editing
Fields
- toolset? string? - 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
- attachments? ClassAttachmentCreation[] - The complete attachment list. Omitting this property on an update leaves the existing
attachments alone; sending it replaces them.
Dropping a dedicated score from the list deletes the students' copies of it, so send the
full set you want to keep rather than only the additions. Duplicates, judged by
url,score,worksheetorgoogleDriveFileId, are discarded silently, and exceeding the per-assignment limit fails withASSIGNMENT_ATTACHMENTS_LIMIT
- teacherInstructionsHtml? string - HTML version of teacher-only instructions.
Pasted images may be sent as inline base64
data:URIs; they are uploaded to storage and rewritten to hosted URLs on save. The final HTML is limited to 100000 characters. When provided, the plain text version will be automatically extracted for compatibility
- description? string - Student instructions and content of the assignment (plain text)
- restrictPlayNote? boolean - Restrict the ability to get an audio feedback every time a student adds or selects a note
- coverFile? string? - The id of the cover to display
- releaseGrades? "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 asdraftGradeand will be released when the teacher returns the submissions
- If set to
- 'type? AssignmentType - Type of the assignment
- title? string - Title of the assignment
- restrictToAudioTracks? boolean - Restrict the audio source to provided audio tracks on a score. Students won't be able to use the editor playback
- freeRecord? boolean - For performance assignments: "Free Record" mode.
When
true, no score is attached to the assignment. Students freely record a varied repertoire or an ensemble performance without being constrained by a single score's structure or duration, and all score-dependent options (playback, metronome, backtracking, speed control) are hidden. Only set when type is 'performance'
- allowMetronome? boolean - For performance assignments: Enable students to use the metronome while they are recording, helping them stay in time. Only set when type is 'performance'
- cover? string? - The URL of the cover to display
- teacherInstructions? string - Teacher-only instructions (plain text)
- maxPoints? decimal? - If set, the grading will be enabled for the assignment with this value as the maximum of points
- recordingType? "audio"|"video" - For performance assignments: recording type that will be either 'audio' or 'video'.
audio: Only audio will be required during the recording.video: Camera will be required during the recording.
- submissionStudentsMode? AssignmentSubmissionStudentsMode - Submission mode for assignments:
- "single": Individual submissions (default)
- "group": Group submissions (for shared writing assignments)
- nbPlaybackAuthorized? decimal? - The number of playbacks authorized on the scores of the assignment
- allowBackingTrack? boolean - For performance assignments: Enable students to listen to the accompaniment without their instrument part while they are playing. Only set when type is 'performance'
- descriptionHtml? string - HTML version of student instructions.
Pasted images may be sent as inline base64
data:URIs; they are uploaded to storage and rewritten to hosted URLs on save. The final HTML is limited to 100000 characters. When provided, the plain text version will be automatically extracted for compatibility
- shuffleExercises? boolean - Shuffle the worksheet exercises for each student
- allowSpeedChange? boolean - For performance assignments: whether students can adjust the playback speed of the score during recording.
true: Students can change the tempo/speed during practice and recordingfalse: Tempo is fixed to the original score tempo
flatapi: CancelOmrJobHeaders
Represents the Headers record for the operation: cancelOmrJob
Fields
- xFlatLocale? string - Preferred locale for localized content in the response (translated error messages, emails, etc.).
Accepts any IETF language tag. The API best-matches the value to a supported locale and never rejects an unknown one (it falls back to the closest match, then to
en). Supported normalized locales:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ko,ms,nl,nb,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW. Precedence (highest first): thisX-Flat-Localeheader, the authenticated user's account locale, theAccept-Languageheader, thenen
flatapi: ClassAssignment
Fields
- Fields Included from *Assignment
- toolset string
- attachments MediaAttachment[]
- teacherInstructionsHtml string
- description string
- releaseGrades "auto"|"manual"
- restrictPlayNote boolean
- type AssignmentType
- title string
- freeRecord boolean
- allowMetronome boolean
- cover string
- teacherInstructions string
- maxPoints decimal
- recordingType "audio"|"video"
- submissionStudentsMode AssignmentSubmissionStudentsMode
- nbPlaybackAuthorized decimal
- id string
- useDedicatedAttachments boolean
- shuffleExercises boolean
- allowSpeedChange boolean
- capabilities AssignmentCapabilities
- coverFile string
- restrictToAudioTracks boolean
- allowBackingTrack boolean
- descriptionHtml string
- anydata...
- lti? ClassAssignment_lti - An LTI assignment
- creator? string - The User unique identifier of the creator of this assignment
- canvas? ClassAssignment_canvas - A Canvas LMS assignment
- issue? string - Detected issue for this assignment
- googleClassroom? GoogleClassroomCoursework - A coursework on Google Classroom
- dueDate? string - The due date of this assignment, late submissions will be marked as past due
- scheduledDate? string - The publication (scheduled) date of the assignment. If this one is specified, the assignment will only be listed to the teachers of the class
- classroom? string - The unique identifier of the class where this assignment was posted
- mfc? ClassAssignment_mfc - A MusicFirst Classroom assignment
- creationDate string - The creation date of this assignment
- assignedStudents? string[] - Identifiers for the students that have access to the assignment
- submissions AssignmentSubmission[] -
- state "draft"|"active"|"archived" - State of the assignment
- microsoftGraph? MicrosoftGraphAssignment - A Microsoft Teams assignment
- assigneeMode? "everyone"|"selected" - Possible modes of assigning assignments
- assignedGroups? AssignmentGroup[] - Groups that have access to the assignment (for shared writing assignments)
flatapi: ClassAssignment_canvas
A Canvas LMS assignment
Fields
- alternateLink? string - Link to Canvas assignment
- id? string - Unique identifier of the assignment on Canvas
flatapi: ClassAssignment_lti
An LTI assignment
Fields
- id? string - Resource ID in the LMS
flatapi: ClassAssignment_mfc
A MusicFirst Classroom assignment
Fields
- alternateLink? string - Link to MusicFirst Classroom task
- id? string - Unique identifier of the task on MusicFirst Classroom
flatapi: ClassAssignmentUpdate
Fields
- Fields Included from *AssignmentUpdate
- toolset string|()
- attachments ClassAttachmentCreation[]
- teacherInstructionsHtml string
- description string
- restrictPlayNote boolean
- coverFile string|()
- releaseGrades "auto"|"manual"
- type AssignmentType
- title string
- restrictToAudioTracks boolean
- freeRecord boolean
- allowMetronome boolean
- cover string|()
- teacherInstructions string
- maxPoints decimal|()
- recordingType "audio"|"video"
- submissionStudentsMode AssignmentSubmissionStudentsMode
- nbPlaybackAuthorized decimal|()
- allowBackingTrack boolean
- descriptionHtml string
- shuffleExercises boolean
- allowSpeedChange boolean
- anydata...
- assignedStudents? string[] - Identifiers for the students that have access to the assignment
- googleClassroom? ClassAssignmentUpdate_googleClassroom - Google Classroom options for this assignment
- dueDate? string? - The due date of this assignment, late submissions will be marked as past due. If not set, the assignment won't have a due date
- submissionStudentsMode? AssignmentSubmissionStudentsMode - Submission mode for assignments:
- "single": Individual submissions (default)
- "group": Group submissions (for shared writing assignments)
- classGroupIds? ClassGroupIdsToApplyToAssignment? - Optional list of specific class group IDs to apply to the assignment.
When transitioning to active state with group submission mode:
- If provided: Only these specific groups will be applied
- If not provided: All class groups will be applied, or randomized groups created if none exist
- scheduledDate? string? - The publication (scheduled) date of the assignment. If this one is specified, the assignment will only be listed to the teachers of the class
- state? "draft"|"active" - State of the assignment
- microsoftGraph? ClassAssignmentUpdate_microsoftGraph - Microsoft Graph options for this assignment
- assigneeMode? "everyone"|"selected" - Possible modes of assigning assignments
flatapi: ClassAssignmentUpdate_googleClassroom
Google Classroom options for this assignment
Fields
- topicId? string? - Identifier of the topic where the assignment is created
flatapi: ClassAssignmentUpdate_microsoftGraph
Microsoft Graph options for this assignment
Fields
- categories? string[]? - List of categories this assignment belongs to
flatapi: ClassAttachmentCreation
Attachment creation for an assignment or stream post.
This attachment must contain a score or a url; its details are resolved and returned as a MediaAttachment once the assignment or stream post is created
Fields
- score? string - A unique Flat score identifier. The user creating the assignment must at least have read access to the document. If the user has admin rights, new group permissions will be automatically added for the teachers and students of the class
- teacherOnly boolean(default false) - Flag indicating if this attachment should only be visible to teachers
- sharingMode? MediaScoreSharingMode - The sharing mode of the score for classes post and assignments
- lockScoreTemplate? boolean - To be used with a score attached in
sharingModecopy(score used as template). If true, students won't be able to change the original notes of the template
- worksheet? string - A unique worksheet identifier
- 'type? "rich"|"photo"|"video"|"link"|"flat"|"googleDrive"|"worksheet" - The type of the attachment posted:
rich,photo,videoare attachment types that are automatically resolved from alinkattachment.- A
flatattachment is a score document where the unique identifier will be specified in thescoreproperty. Its sharing mode will be provided in thesharingModeproperty
- partUuid? string - The UUID of the instrument part selected for this attachment (for performance submissions)
- url? string - The URL of the attachment
- googleDriveFileId? string - The ID of the Google Drive File
- revision? string - A unique revision identifier of a score
flatapi: ClassCreation
Creation of a classroom
Fields
- size? decimal? - Number of students in the classroom
- level? ClassGradeLevel - Class grade level
- skillsFocused? EduSkillsFocused - Specific skills that will be focused in classroom
- name string - The name of the new class
- section? string - The section of the new class
flatapi: ClassDetails
A classroom
Fields
- googleClassroom? ClassDetailsGoogleClassroom - Google Classroom course-related information
- assignmentsCount? decimal - The number of assignments created in the class
- description? string - An optional description for this class
- section? string - The section of the class
- enrollmentCode? string - [Teachers only] The enrollment code that can be used by the students to join the class
- issues? ClassDetailsIssues - Detected issues for this class
- clever? ClassDetailsClever - Clever.com section-related information
- theme? string - The theme identifier used in the Flat user interface
- id string - The unique identifier of the class
- state ClassState - The state of a classroom
- googleDrive? ClassDetailsGoogleDrive - Google Drive course-related information provided by Google Classroom
- owner? string - The unique identifier of the User owning this class
- lti? ClassDetailsLti - Info about LTI context (1.1 and 1.3)
- canvas? ClassDetailsCanvas - Meta information provided by Canvas LMS
- level? ClassGradeLevel - Class grade level
- skillsFocused? EduSkillsFocused - Specific skills that will be focused in classroom
- teachersGroup? GroupDetails - The details of a group
- mfc? ClassDetailsMfc - Meta information provided by MusicFirst Classroom
- creationDate string - The date when the class was created
- modificationDate? string - The date when the class was last modified
- size? decimal? - Number of students in the classroom
- organization? string - The unique identifier of the Organization owning this class
- name string - The name of the class
- studentsGroup? GroupDetails - The details of a group
- microsoftGraph? ClassDetailsMicrosoftGraph - The Microsoft Graph course linked to the class
flatapi: ClassDetailsCanvas
Meta information provided by Canvas LMS
Fields
- domain? string - Canvas instance domain (e.g. "canvas.instructure.com")
- id? string - Unique identifier of the course on Canvas
flatapi: ClassDetailsClever
Clever.com section-related information
Fields
- modificationDate? string - The last modification date of the section on clever
- termEndDate? string - End date of the term
- subject? "english/language arts"|"math"|"science"|"social studies"|"language"|"homeroom/advisory"|"interventions/online learning"|"technology and engineering"|"PE and health"|"arts and music"|"other" - Normalized subject of the course
- termStartDate? string - Beginning date of the term
- id? string - Clever section unique identifier
- creationDate? string - The creation date of the section on clever
- termName? string - Name of the term when this course happens
flatapi: ClassDetailsGoogleClassroom
Google Classroom course-related information
Fields
- alternateLink? string - Absolute link to this course in the Classroom web UI
- id? string - The course identifier on Google Classroom
flatapi: ClassDetailsGoogleDrive
Google Drive course-related information provided by Google Classroom
Fields
- teacherFolderId? string - [Teachers only] The Drive directory identifier of the teachers' folder
- teacherFolderAlternateLink? string - [Teachers only] The Drive URL of the teachers' folder
flatapi: ClassDetailsIssues
Detected issues for this class
Fields
- sync? ClassDetailsIssuesSync[] - Synchronization issues for the class
flatapi: ClassDetailsIssuesSync
A sync issue
Fields
- reason? "otherOrgnanization"|"productMigration"|"disabledAccount" - The reason why the account cannot be synced
- id? string - The account user identifier
- email? string - The email address of the user concerned by this sync issue
flatapi: ClassDetailsLti
Info about LTI context (1.1 and 1.3)
Fields
- hasNrpsService? boolean - If true, the class has been synchronized with the LTI 1.3 NRPS 2.0 service
- contextId? string - Unique context identifier provided
- contextTitle? string - Context title
- contextLabel? string - Context label
flatapi: ClassDetailsMfc
Meta information provided by MusicFirst Classroom
Fields
- alternateLink? string - Link to MusicFirst Classroom class
- id? string - Unique identifier of the course on MusicFirst Classroom
flatapi: ClassDetailsMicrosoftGraph
The Microsoft Graph course linked to the class
Fields
- id? string - The course identifier on Microsoft Graph
flatapi: ClassUpdate
Update of a classroom
Fields
- size? decimal? - Number of students in the classroom
- level? ClassGradeLevel - Class grade level
- skillsFocused? EduSkillsFocused - Specific skills that will be focused in classroom
- name? string - The name of the class
- section? string - The section of the class
flatapi: Collection
Collection of scores
Fields
- app? CollectionApp - For App collections, the details of the app that created the collection
- capabilities CollectionCapabilities - Capabilities the current user has on this collection. Each capability corresponds to a fine-grained action that a user may take
- isPinned? boolean - Whether the collection is pinned by the owner
- htmlUrl string - The url where the collection can be viewed in a web browser
- privacy CollectionPrivacy - The collection main privacy mode.
private: The collection is private and can only be accessed, modified, and administered by specified collaborators
- title string - The title of the collection
- 'type CollectionType - Type of the collection.
The type will influence the capabilities available on the collections and how this collection is/can be populated.
root: Deprecated. Previously the root collection of the user. TheallScoresvirtual collection should be used instead.regular: A regular collection created by the user. This collection can be deleted and modified by the user.app: An automatically created collection containing the scores created by an app (e.g. Music Snippet)trash: An automatically created collection containing the trashed scores.
allScores: All the scores contained in the user accountcollaborations: All shared scores by the user or someone elselikes: Liked scores
- creationDate string - The date when the collection was created
- sharingKey? string - The private sharing key of the collection (available when the
privacymode is set toprivateLink)
- modificationDate? string - The date when the collection was last modified
- contents CollectionContents - The contents of the collection
- collections? string[] - The list of parent collections this score is included in. Please note that you might not have access to all of them
- organization? string - If the score has been created in an organization, the identifier of this organization.
- rights? ResourceRights - The rights of the current user on a score or collection
- collaborators? ResourceCollaborator[] - The list of the collaborators of the collection
- id string - Unique identifier of the collection
- labelKey? string - Product-specific translation key for the collection type.
Only set for specific collection types:
- For
regulartype:playlist(Flat) orcollection(Flat for Education) - For
collaborationstype:collaboration(Flat) orshared-scores(Flat for Education)
- For
- user? UserPublicSummary - Public User details summary
flatapi: CollectionApp
For App collections, the details of the app that created the collection
Fields
- name? string - The name of the app
- logo? string - The app logo url
- id? string - The app unique identifier
flatapi: CollectionCapabilities
Capabilities the current user has on this collection. Each capability corresponds to a fine-grained action that a user may take
Fields
- canDeleteScores boolean - Whether the current user can delete scores from the collection
If this collection has the
typetrash, this property will be set tofalse. UsePOST /v2/scores/{score}/untrashto restore a score
- canAddScores boolean - Whether the current user can add scores to the collection
If this collection has the
typetrash, this property will be set tofalse. UseDELETE /v2/scores/{score}to trash a score
- canEdit boolean - Whether the current user can modify the metadata for the collection
- canShare boolean - Whether the current user can modify the sharing settings for the collection
- canDelete boolean - Whether the current user can delete the collection
flatapi: CollectionContents
The contents of the collection
Fields
- scoresCount int - The number of scores in the collection
flatapi: CollectionCreation
Fields
- privacy? CollectionPrivacy - The collection main privacy mode.
private: The collection is private and can only be accessed, modified, and administered by specified collaborators
- title? string - The title of the collection
flatapi: CollectionModification
Edit the collection metadata
Fields
- privacy? CollectionPrivacy - The collection main privacy mode.
private: The collection is private and can only be accessed, modified, and administered by specified collaborators
- title? string - The title of the collection
flatapi: ConnectionConfig
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth BearerTokenConfig|OAuth2RefreshTokenGrantConfig - Configurations related to client authentication
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 30) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded/x-forwardedheader
- followRedirects? FollowRedirects - Configurations associated with Redirection
- poolConfig? PoolConfiguration - Configurations associated with request pooling
- cache CacheConfig(default {}) - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding) header
- circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig? RetryConfig - Configurations associated with retrying
- cookieConfig? CookieConfig - Configurations associated with cookies
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- secureSocket? ClientSecureSocket - SSL/TLS-related options
- proxy? ProxyConfig - Proxy server related options
- socketConfig ClientSocketConfig(default {}) - Provides settings related to client socket configuration
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
- laxDataBinding boolean(default true) - Enables relaxed data binding on the client side. When enabled,
nilvalues are treated as optional, and absent fields are handled asnilabletypes. Enabled by default.
flatapi: CountOrganizationUsersQueries
Represents the Queries record for the operation: countOrganizationUsers
Fields
- q? string - The query to search
- role? ("user"|"teacher"|"admin"|"accountAdmin")[] - Filter users by role
- testAccounts? "exclude"|"only" - Filter users based on test account status.
Test accounts are student accounts created for testing purposes by teachers.
exclude: Hide test accounts from results.only: Show only test accounts.
- group? string[] - Filter users by group
- noActiveLicense? boolean - Filter users who don't have an active license
flatapi: CreateExportTaskQueries
Represents the Queries record for the operation: createExportTask
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: CreateOmrJobHeaders
Represents the Headers record for the operation: createOmrJob
Fields
- xFlatLocale? string - Preferred locale for localized content in the response (translated error messages, emails, etc.).
Accepts any IETF language tag. The API best-matches the value to a supported locale and never rejects an unknown one (it falls back to the closest match, then to
en). Supported normalized locales:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ko,ms,nl,nb,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW. Precedence (highest first): thisX-Flat-Localeheader, the authenticated user's account locale, theAccept-Languageheader, thenen
flatapi: CreateTestStudentAccountQueries
Represents the Queries record for the operation: createTestStudentAccount
Fields
- reset? boolean - If true, the testing account will be re-created
flatapi: CreditTransaction
A single credit ledger entry
Fields
- amount int - How many credits this entry moved, signed: positive for top-ups
(
+30from a credit pack), negative for deductions (-2for a two-page import). Sum only entries whosestateisactive
- modificationDate string - When the transaction was last modified
- feature? "omr" - Which product the credits relate to. Set on deductions and on the credits a refund returns, absent on credit-pack top-ups, which are not tied to a single feature
- id string - Unique identifier of the credit transaction
- 'source "subscription"|"purchase"|"free_tier"|"support" - Which pool the credits came from:
subscription: the plan's periodic allowancepurchase: credits bought as a pack, which do not expire with the billing periodfree_tier: promotional grantssupport: a manual adjustment made by Flat's support team
purchase
- state "active"|"canceled" - Whether the entry still counts:
active: in effectcanceled: reversed, and no longer affecting the balance. Deductions are canceled when the import they paid for fails or is refunded
- 'type "ai" - Credit category.
aicovers every AI-powered feature
- job? string - Identifier of the import this entry belongs to, when it relates to one. Present on an import's deduction, on its reversal, and on credits returned when an import is refunded. Absent on credit-pack top-ups and manual adjustments
- creationDate string - When the transaction was created
flatapi: DeleteOmrJobHeaders
Represents the Headers record for the operation: deleteOmrJob
Fields
- xFlatLocale? string - Preferred locale for localized content in the response (translated error messages, emails, etc.).
Accepts any IETF language tag. The API best-matches the value to a supported locale and never rejects an unknown one (it falls back to the closest match, then to
en). Supported normalized locales:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ko,ms,nl,nb,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW. Precedence (highest first): thisX-Flat-Localeheader, the authenticated user's account locale, theAccept-Languageheader, thenen
flatapi: DeleteScoreCommentQueries
Represents the Queries record for the operation: deleteScoreComment
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
- eventProperties? string - Optional analytics properties merged into the analytics events recorded for this request.
JSON-encoded string representing event properties. Example:
?eventProperties={"context":"discover","screenLevel0":"home"}
flatapi: DeleteScoreFromCollectionQueries
Represents the Queries record for the operation: deleteScoreFromCollection
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
- eventProperties? string - Optional analytics properties merged into the analytics events recorded for this request.
JSON-encoded string representing event properties. Example:
?eventProperties={"context":"discover","screenLevel0":"home"}
flatapi: DeleteScoreQueries
Represents the Queries record for the operation: deleteScore
Fields
- now boolean(default false) - If
true, the score deletion will be scheduled as soon as possible
flatapi: EduLibrary
A Flat for Education Library
Fields
- visibility "private"|"organization"|"public" - Visibility of the library
- name string - Name of the library
- id string - Unique identifier of the library.
This one can be used to list the underlying resources using
GET /v2/eduResources?parent={library-id}
- 'type "myResources"|"organizationResources"|"flatEduContent" - Type of the library
flatapi: EduResource
A Flat for Education resource contained in a resources library
Fields
- parent? string - Identifier of the parent resource, e.g. a folder or root
- creator? string - The User identifier of the resource creator
- sharingDescription? string - Sharing description of this resource
- updateDate? string - The date when the resource was updated
- capabilities EduResourceCapabilities - Capabilities available for this resource
- 'resource? Assignment|EduResourceFolder - The assignment or folder described by this resource
- subjects? EduResourceSubjects - The subjects of this resource, or the subjects of the resources included in the folder
- privacy? EduResourcePrivacy - The Education resource privacy mode
- grades? EduResourceGrades - The grades of this resource, or the grades of the resources included in the folder
- 'type EduResourceType - Type of an education resource
- title string - Title of the resource
- creationDate? string - The date when the resource was created
- tags? string[] - Specific attributes for the resource (e.g. sample resources with custom design)
- sharingDescriptionHtml? string - HTML version of sharing description with rich text formatting. Supports safe HTML tags: p, br, strong, b, em, i, u, a
- id string - Resource unique identifier
flatapi: EduResourceAssignmentCreation
Assignment-specific creation options.
Only applicable when creating a resource with type: assignment.
If type is not provided, defaults to none
Fields
- 'type? AssignmentType - Type of the assignment
flatapi: EduResourceCapabilities
Capabilities available for this resource
Fields
- canAddFolders? boolean - Whether the current user can add folders within this resource (e.g.
folderinsideroot)
- canAddResources? boolean - Whether the current user can add resources within this resource (e.g.
assignmentinside afolder)
- canChangePrivacy? boolean - Whether the current user can change the privacy of this resource (e.g. to share as
organizationPublicor unshare it withprivate)
- canEdit? boolean - Whether the current user can modify this resource
flatapi: EduResourceCopy
Copy an education resource
Fields
- destination string - Unique identifier of the destination folder for the copy.
This can also be
rootto copy the resource at the root of the user resource library
flatapi: EduResourceCreation
Creation of an education resource
Fields
- parent string(default "root") - Identifier of the parent resource where the new one will be created, e.g. a folder id or
root
- sharingDescription? string - Sharing description of the resource
- 'resource? EduResourceAssignmentCreation - Assignment-specific creation options.
Only applicable when creating a resource with
type: assignment. Iftypeis not provided, defaults tonone
- sharingDescriptionHtml? string - HTML version of sharing description with rich text formatting. Supports safe HTML tags: p, br, strong, b, em, i, u, a
- 'type EduResourceType - Type of an education resource
- title string - Title of the resource
flatapi: EduResourceFolder
Education resources folder
Fields
- assignmentsTypes? AssignmentType[] - The assignment types of the resources included in the folder
- resourcesCount? decimal - The number of resources inside the folder
- title? string - Title of the folder
flatapi: EduResourceLtiLink
LTI Link details for the class
Fields
- ltiUrl string - A URL that can be used to launch LTI with this resource in a classroom
flatapi: EduResourceMove
Move an education resource
Fields
- destination string - Unique identifier of the destination folder for this resource.
This can also be
rootto move the resource at the root of the user resource library
flatapi: EduResourceUpdate
Update of an education resource
Fields
- sharingDescription? string - Sharing description of the resource
- sharingDescriptionHtml? string - HTML version of sharing description with rich text formatting. Supports safe HTML tags: p, br, strong, b, em, i, u, a
- subjects? EduResourceSubjects - The subjects of this resource, or the subjects of the resources included in the folder
- privacy? EduResourcePrivacy - The Education resource privacy mode
- grades? EduResourceGrades - The grades of this resource, or the grades of the resources included in the folder
- title? string - Title of the resource
flatapi: EduResourceUseInClass
Use an education resource in class
Fields
- assignment? string - An optional destination assignment where the original assignment will be copied. Must be a draft
- classroom string - The destination classroom where the resource will be copied
flatapi: ForkScoreQueries
Represents the Queries record for the operation: forkScore
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: GetAuthenticatedUserQueries
Represents the Queries record for the operation: getAuthenticatedUser
Fields
- onlyId boolean(default false) - Only return the user id
flatapi: GetCollectionQueries
Represents the Queries record for the operation: getCollection
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: GetGroupScoresQueries
Represents the Queries record for the operation: getGroupScores
Fields
- parent? string - Only return the scores forked from the score
parent
flatapi: GetOmrCapabilitiesHeaders
Represents the Headers record for the operation: getOmrCapabilities
Fields
- xFlatLocale? string - Preferred locale for localized content in the response (translated error messages, emails, etc.).
Accepts any IETF language tag. The API best-matches the value to a supported locale and never rejects an unknown one (it falls back to the closest match, then to
en). Supported normalized locales:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ko,ms,nl,nb,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW. Precedence (highest first): thisX-Flat-Localeheader, the authenticated user's account locale, theAccept-Languageheader, thenen
flatapi: GetOmrJobExportHeaders
Represents the Headers record for the operation: getOmrJobExport
Fields
- xFlatLocale? string - Preferred locale for localized content in the response (translated error messages, emails, etc.).
Accepts any IETF language tag. The API best-matches the value to a supported locale and never rejects an unknown one (it falls back to the closest match, then to
en). Supported normalized locales:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ko,ms,nl,nb,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW. Precedence (highest first): thisX-Flat-Localeheader, the authenticated user's account locale, theAccept-Languageheader, thenen
flatapi: GetOmrJobFileHeaders
Represents the Headers record for the operation: getOmrJobFile
Fields
- xFlatLocale? string - Preferred locale for localized content in the response (translated error messages, emails, etc.).
Accepts any IETF language tag. The API best-matches the value to a supported locale and never rejects an unknown one (it falls back to the closest match, then to
en). Supported normalized locales:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ko,ms,nl,nb,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW. Precedence (highest first): thisX-Flat-Localeheader, the authenticated user's account locale, theAccept-Languageheader, thenen
flatapi: GetOmrJobHeaders
Represents the Headers record for the operation: getOmrJob
Fields
- xFlatLocale? string - Preferred locale for localized content in the response (translated error messages, emails, etc.).
Accepts any IETF language tag. The API best-matches the value to a supported locale and never rejects an unknown one (it falls back to the closest match, then to
en). Supported normalized locales:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ko,ms,nl,nb,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW. Precedence (highest first): thisX-Flat-Localeheader, the authenticated user's account locale, theAccept-Languageheader, thenen
flatapi: GetOmrJobQueries
Represents the Queries record for the operation: getOmrJob
Fields
- 'wait? int - Long-poll up to this many seconds for a state change before returning
flatapi: GetScoreCollaboratorQueries
Represents the Queries record for the operation: getScoreCollaborator
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: GetScoreCollaboratorsQueries
Represents the Queries record for the operation: getScoreCollaborators
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: GetScoreCommentsQueries
Represents the Queries record for the operation: getScoreComments
Fields
- sort? "date" - Sort
- 'type? "document"|"inline" - Filter the comments by type
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
- direction? "asc"|"desc" - Sort direction
flatapi: GetScoreQueries
Represents the Queries record for the operation: getScore
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: GetScoreRevisionDataQueries
Represents the Queries record for the operation: getScoreRevisionData
Fields
- parts? string - An optional set of part UUIDs to export. This parameter must be composed of part UUIDs separated by commas. For example "59df645f-bb1c-f1b4-b573-d2afc4491f94,34ef645f-1aef-f3bc-1564-34cca4492b87"
- defaultTrack? boolean - When
formatismp3, this property is set to true and the score has a defaultScoreTrack(mp3), this one will be returned instead of the playback file
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
- url? boolean - Returns a json with the
urlin it instead of redirecting
flatapi: GetScoreRevisionQueries
Represents the Queries record for the operation: getScoreRevision
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: GetScoreRevisionsQueries
Represents the Queries record for the operation: getScoreRevisions
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: GetScoreTrackQueries
Represents the Queries record for the operation: getScoreTrack
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: GetUserLikesQueries
Represents the Queries record for the operation: getUserLikes
Fields
- next? string - An opaque string cursor to fetch the next page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor 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
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- 'limit int(default 25) - This is the maximum number of objects that may be returned
- ids? boolean - Return only the identifiers of the scores
flatapi: GetUserScoresQueries
Represents the Queries record for the operation: getUserScores
Fields
- next? string - An opaque string cursor to fetch the next page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor 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
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- 'limit int(default 25) - This is the maximum number of objects that may be returned
- paginate boolean(default false) - When set to
true, the API will return a paginated result. When set tofalseor 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? "creationDate"|"modificationDate"|"title" - Sort
- direction? "asc"|"desc" - Sort direction
flatapi: GoogleClassroomCoursework
A coursework on Google Classroom
Fields
- topicId? string? - Identifier of the topic where the assignment is created
- alternateLink? string - Absolute link to this coursework in the Classroom web UI
- id? string - Identifier of the coursework assigned by Classroom
- state? string - State of the coursework
flatapi: GoogleClassroomSubmission
A coursework submission on Google Classroom
Fields
- alternateLink string - Absolute link to this coursework in the Classroom web UI
- id string - Identifier of the coursework submission assigned by Classroom
- state string - State of the submission on Google Classroom
flatapi: Group
A group of users
Fields
- organization? string - If the group is related to an organization, this field will contain the unique identifier of the organization
- name? string - The display name of the group
- usersCount? decimal - The number of users in this group
- readOnly? boolean -
Trueif the group is set in read-only
- id? string - The unique identifier of the group
- 'type? GroupType - The type of the group:
generic: A group created by a Flat userclassTeachers: A group created automatically by Flat that contains the teachers of a classclassStudents: A group created automatically by Flat that contains the students of a classclassStudentsSubGroup: Manually created sub-group of students of a class.assignmentStudentsSubGroup: Manually created Sub-group of students of a class, in relation to a specific assignment
- creationDate? string - The creation date of the group
flatapi: GroupCreation
Fields
- members? string[] - Array of student IDs to add to the group
- name? string - Name of the group (optional - auto-generated if not provided).
Special names:
edu:testing-students: Creates a group tagged for test student accounts. The display name will be localized (e.g., "Test Students") and the group will be tagged withedu:testing-students
- classroom string - Classroom ID
- 'type "classStudentsSubGroup" - Type of group (currently only classStudentsSubGroup is supported)
flatapi: GroupDetails
The details of a group
Fields
- parent? string - The unique identifier of the parent class group. Only available for groups of type 'assignmentStudentsSubGroup'. May be null if the parent class group was deleted
- assignment? string - The unique identifier of the assignment owning the group. Only available for groups of type 'assignmentStudentsSubGroup'
- organization? string - The unique identifier of the Organization owning the group
- name string - The displayable name of the group
- classroom? string - The unique identifier of the classroom owning the group. Only available for groups of type 'classStudentsSubGroup' or 'assignmentStudentsSubGroup'
- usersCount decimal - The number of students in this group
- readOnly boolean -
trueif the properties and members of this group are read-only
- id string - The unique identifier of the group
- 'type GroupType - The type of the group:
generic: A group created by a Flat userclassTeachers: A group created automatically by Flat that contains the teachers of a classclassStudents: A group created automatically by Flat that contains the students of a classclassStudentsSubGroup: Manually created sub-group of students of a class.assignmentStudentsSubGroup: Manually created Sub-group of students of a class, in relation to a specific assignment
- creationDate string - The date when the group was created
- tags string[] - Tags for categorizing groups.
edu:testing-students: Marks this group as containing test student accounts
flatapi: ListBillingCreditsHistoryQueries
Represents the Queries record for the operation: listBillingCreditsHistory
Fields
- next? string - An opaque string cursor to fetch the next page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor 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
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- 'limit int(default 50) - This is the maximum number of objects that may be returned
flatapi: ListClassesQueries
Represents the Queries record for the operation: listClasses
Fields
- state "active"|"inactive"|"archived" (default "active") - Filter the classes by state
flatapi: ListCollectionScoresQueries
Represents the Queries record for the operation: listCollectionScores
Fields
- next? string - An opaque string cursor to fetch the next page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor 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
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- 'limit int(default 25) - This is the maximum number of objects that may be returned
- sort? "creationDate"|"modificationDate"|"title" - Sort
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
- direction? "asc"|"desc" - Sort direction
flatapi: ListCollectionsQueries
Represents the Queries record for the operation: listCollections
Fields
- next? string - An opaque string cursor to fetch the next page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- parent string(default "user") - List the collections contained in this
parentcollection. When set touser(default), returns the user's own collections as well as collections shared with the user. UsingrootorsharedWithMeis deprecated and will be treated asuser
- previous? string - An opaque string cursor to fetch the previous page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- 'limit int(default 25) - This is the maximum number of objects that may be returned
- sort? "creationDate"|"modificationDate"|"title" - Sort
- direction? "asc"|"desc" - Sort direction
flatapi: ListEduResourcesQueries
Represents the Queries record for the operation: listEduResources
Fields
- next? string - An opaque string cursor to fetch the next page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- parent string(default "root") - List the resources contained in this
parentlibrary or folder. Accepts a folder identifier, or the identifier of one of the libraries returned bylistEduLibraries. Which libraries are available depends on the account, so use theidvalues that endpoint returns rather than hardcoding this list:root: the user's own resourcesorganization: resources shared with the organization
- previous? string - An opaque string cursor to fetch the previous page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- subjects? TeachingTheme[] - Filter the returned resources by subjects
- 'limit int(default 25) - This is the maximum number of resources that may be returned
- grades? Grade[] - Filter the returned resources by grades
- sort "creationDate"|"updateDate"|"title" (default "creationDate") - Sort
- 'type? "assignment"|"folder" - Filter the returned resources by type
- withoutSubfoldersResources? boolean - For the
parent=organization, do not include resources from subfolders. Resources from subfolders are included by default; set this totrueto list only the direct children, for example in a picker
- assignmentTypes? AssignmentType[] - Filter the returned resources by assignment types
- direction? "asc"|"desc" - Sort direction
flatapi: ListGroupsQueries
Represents the Queries record for the operation: listGroups
Fields
- assignment? string - Assignment ID to filter by
- classroom? string - Classroom ID to filter by
- 'type "classStudentsSubGroup"|"assignmentStudentsSubGroup" - The type of groups to list
flatapi: ListGroupUsersQueries
Represents the Queries record for the operation: listGroupUsers
Fields
- 'source? "googleClassroom"|"microsoftGraph"|"clever" - Filter the users by their source
flatapi: ListOmrJobsHeaders
Represents the Headers record for the operation: listOmrJobs
Fields
- xFlatLocale? string - Preferred locale for localized content in the response (translated error messages, emails, etc.).
Accepts any IETF language tag. The API best-matches the value to a supported locale and never rejects an unknown one (it falls back to the closest match, then to
en). Supported normalized locales:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ko,ms,nl,nb,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW. Precedence (highest first): thisX-Flat-Localeheader, the authenticated user's account locale, theAccept-Languageheader, thenen
flatapi: ListOmrJobsQueries
Represents the Queries record for the operation: listOmrJobs
Fields
- next? string - An opaque string cursor to fetch the next page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- expired? boolean - Filter by data-retention state, independently of
status.true: only jobs whose files have been erased.false: only jobs that still hold their files.
statusit finished with after erasure, so this is the only way to tell the two apart
- previous? string - An opaque string cursor to fetch the previous page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- 'limit int(default 50) - This is the maximum number of objects that may be returned
- status? OmrJobStatus - Filter jobs by status
flatapi: ListOrganizationInvitationsQueries
Represents the Queries record for the operation: listOrganizationInvitations
Fields
- next? string - An opaque string cursor to fetch the next page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- role? "user"|"teacher"|"admin" - Filter users by role
- previous? string - An opaque string cursor to fetch the previous page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- 'limit int(default 50) - This is the maximum number of objects that may be returned
flatapi: ListOrganizationUsersQueries
Represents the Queries record for the operation: listOrganizationUsers
Fields
- next? string - An opaque string cursor to fetch the next page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- q? string - The query to search
- role? ("user"|"teacher"|"admin"|"accountAdmin")[] - Filter users by role
- previous? string - An opaque string cursor to fetch the previous page of data.
The paginated API URLs are returned in the
Linkheader when requesting the API. These URLs will contain anextandpreviouscursor based on the available data
- licenseExpirationDate? string[] - Filter users by license expiration date or
active/notActive
- 'limit int(default 25) - This is the maximum number of objects that may be returned
- testAccounts? "exclude"|"only" - Filter users based on test account status.
Test accounts are student accounts created for testing purposes by teachers.
exclude: Hide test accounts from results.only: Show only test accounts.
- sort? "creationDate"|"firstname"|"lastname"|"username"|"lastActivityDate"|"licenseExpirationDate" - The order to sort the user list.
creationDate: Order by account creation.firstname,lastname,username: Order by the user identity.lastActivityDate: Order by the last recorded activity.licenseExpirationDate: Order by the expiration of the active license
- onlyIds? boolean - Return only user ids
- direction? "asc"|"desc" - Sort direction
- group? string[] - Filter users by group
- noActiveLicense? boolean - Filter users who don't have an active license
flatapi: ListScoreTracksQueries
Represents the Queries record for the operation: listScoreTracks
Fields
- assignment? string - Only return the tracks related to this assignment
- listAutoTrack? boolean - If
true, and when available, also return the latest MP3 export automatically generated by Flat as an additional track
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: LtiConfiguration1p1
Fields
- Fields Included from *LtiConfigurationBase
- ltiVersion? "1p1" - LTI version (1.1)
- consumerSecret? string - LTI 1.1 consumer secret (only included for admins)
- lms? string - LMS type
- name? string - Configuration name
- consumerKey? string - LTI 1.1 consumer key
- tool? LtiConfiguration1p1_tool - Platform/tool product information
flatapi: LtiConfiguration1p1_tool
Platform/tool product information
Fields
- product? string - Product family code (e.g., canvas, moodle, schoology)
- instanceContact? string - Contact email or handle for the instance
- instanceName? string - Instance display name
- instanceDomain? string - Instance root domain
- instanceGuid? string - Unique instance identifier
- version? string - Platform version string
flatapi: LtiConfiguration1p3Base
Fields
- deploymentMode? "single"|"multi" - Deployment mode (single for organization-specific, multi for shared parent platforms)
- publicKeysetUrl? string - Public keyset URL for the platform to retrieve Flat's public keys
- enableEmailMatching boolean(default true) - Enable email-based user matching during LTI authentication. When true (default): If a user with the same email exists in the organization, they will be matched and logged in instead of creating a new account. When false: Email matching is disabled. Only LTI ID matching is used, which means multiple LTI users can share the same email address and have separate Flat accounts. This is useful for cases like siblings sharing a parent email in the LMS
- clientId? string - OAuth2 client_id allocated by the platform
- jwksUrl? string - Platform JWKS endpoint (public keys)
- platformIss? string - Platform issuer URL
- redirectUris? string[] - Allowed redirect URIs for LTI launches
- tool? LtiConfiguration1p3BaseTool - Platform/tool product information
- mode? "1p3-manual"|"1p3-deployment"|"1p3-dynamic" - LTI 1.3 configuration mode
- authorizationUrl? string - OIDC authorization/login endpoint
- initiateLoginUrl? string - URL for the platform to initiate LTI login
- deploymentId? string - Deployment ID linking the tool to a tenant/class (varies by platform)
- accessTokenUrl? string - OAuth2 token endpoint (for AGS/NRPS)
- platformName? string - Platform display name
- supportedServices? LtiConfiguration1p3BaseSupportedServices - LTI services support information
flatapi: LtiConfiguration1p3BaseSupportedServices
LTI services support information
Fields
- nrps? LtiConfiguration1p3BaseSupportedServicesNrps - Names and Role Provisioning Services support
- deepLinking? LtiConfiguration1p3BaseSupportedServicesDeepLinking - Deep Linking support
- ags? LtiConfiguration1p3BaseSupportedServicesAgs - Assignment and Grade Services support
flatapi: LtiConfiguration1p3BaseSupportedServicesAgs
Assignment and Grade Services support
Fields
- available? boolean - Whether AGS claims were detected in launches from this platform
- lineitemsUrl? string - Base URL for line items operations as provided by the platform
- version? string - AGS version supported (e.g., "2.0")
- enabled? boolean - Whether AGS is enabled for this platform
flatapi: LtiConfiguration1p3BaseSupportedServicesDeepLinking
Deep Linking support
Fields
- available? boolean - Whether Deep Linking claims were detected in launches from this platform
- version? string - Deep Linking version supported (e.g., "2.0")
flatapi: LtiConfiguration1p3BaseSupportedServicesNrps
Names and Role Provisioning Services support
Fields
- available? boolean - Whether NRPS claims were detected in launches from this platform
- version? string - NRPS version supported (e.g., "2.0")
- enabled? boolean - Whether NRPS is enabled for this platform
flatapi: LtiConfiguration1p3BaseTool
Platform/tool product information
Fields
- product? string - Product family code (e.g., canvas, moodle, schoology)
- instanceContact? string - Contact email or handle for the instance
- instanceName? string - Instance name (e.g., 'My University Canvas')
- instanceDomain? string - Instance root domain
- instanceGuid? string - Unique instance identifier
- version? string - Platform version string
flatapi: LtiConfiguration1p3Deployment
Fields
- Fields Included from *LtiConfigurationBase
- Fields Included from *LtiConfiguration1p3Base
- deploymentMode "single"|"multi"
- publicKeysetUrl string
- enableEmailMatching boolean
- clientId string
- jwksUrl string
- platformIss string
- redirectUris string[]
- tool LtiConfiguration1p3BaseTool
- mode "1p3-manual"|"1p3-deployment"|"1p3-dynamic"
- authorizationUrl string
- initiateLoginUrl string
- deploymentId string
- accessTokenUrl string
- platformName string
- supportedServices LtiConfiguration1p3BaseSupportedServices
- anydata...
- ltiVersion? "1p3" - LTI version (1.3)
- mode? "1p3-deployment" - Deployment-based LTI 1.3 configuration mode
- deploymentBreakdownBy? string - Custom claim used for tenant identification (parent platforms only, read-only)
- deploymentKey? string - Deployment key (e.g., schoology, classlink)
- deploymentBreakdownId? string - Value of the custom claim that identifies this specific tenant (child platforms only)
- parentId? string - Parent configuration ID (for deployment-based configs)
- deploymentId string - Deployment ID linking the tool to a tenant/class (varies by platform)
flatapi: LtiConfiguration1p3Dynamic
Fields
- Fields Included from *LtiConfigurationBase
- Fields Included from *LtiConfiguration1p3Base
- deploymentMode "single"|"multi"
- publicKeysetUrl string
- enableEmailMatching boolean
- clientId string
- jwksUrl string
- platformIss string
- redirectUris string[]
- tool LtiConfiguration1p3BaseTool
- mode "1p3-manual"|"1p3-deployment"|"1p3-dynamic"
- authorizationUrl string
- initiateLoginUrl string
- deploymentId string
- accessTokenUrl string
- platformName string
- supportedServices LtiConfiguration1p3BaseSupportedServices
- anydata...
- ltiVersion? "1p3" - LTI version (1.3)
- mode? "1p3-dynamic" - Dynamic registration LTI 1.3 configuration mode
- registrationToken? string - Only included for admins
- registrationCompletionDate? string? - Date when dynamic registration completed (null when not completed)
- registrationTokenUsed? boolean - Whether dynamic registration token has been used
- registrationUrl? string - Dynamic registration URL (only included for admins when available)
flatapi: LtiConfiguration1p3Manual
Fields
- Fields Included from *LtiConfigurationBase
- Fields Included from *LtiConfiguration1p3Base
- deploymentMode "single"|"multi"
- publicKeysetUrl string
- enableEmailMatching boolean
- clientId string
- jwksUrl string
- platformIss string
- redirectUris string[]
- tool LtiConfiguration1p3BaseTool
- mode "1p3-manual"|"1p3-deployment"|"1p3-dynamic"
- authorizationUrl string
- initiateLoginUrl string
- deploymentId string
- accessTokenUrl string
- platformName string
- supportedServices LtiConfiguration1p3BaseSupportedServices
- anydata...
- ltiVersion? "1p3" - LTI version (1.3)
- mode? "1p3-manual" - Manual LTI 1.3 configuration mode
flatapi: LtiConfigurationBase
Fields
- ltiVersion "1p1"|"1p3" - LTI version
- organizationId? string - Organization ID
- organizationName? string - Organization name
- lastUsedDate? string? - Last time this configuration was used
- creatorId? string - ID of the user who created this configuration
- id string - Configuration ID
- creationDate string - Configuration creation date
- status? "ready-to-use"|"in-use"|"incomplete-setup" - Configuration status indicator
flatapi: LtiConfigurationCreate1p1
LTI 1.1 manual configuration creation
Fields
- mode "1p1-manual" - LTI 1.1 manual creation mode
- lms? string - LMS identifier for LTI 1.1 credentials
- name? string - Display name for LTI 1.1 credentials
flatapi: LtiConfigurationCreate1p3Deployment
LTI 1.3 deployment-based configuration creation
Fields
- mode "1p3-deployment" - LTI 1.3 deployment-based creation mode
- deploymentType string - Parent platform key (e.g., blackboard, schoology, classlink, manabipocket, manabipocket-stg)
- clientId? string - OAuth2 client_id for the tenant; required for ClassLink deployments
- deploymentId string - Deployment identifier provided by the platform
- deploymentBreakdownId? string - Value of the custom claim that identifies this specific tenant (for multi-tenant platforms like Schoology)
flatapi: LtiConfigurationCreate1p3Dynamic
LTI 1.3 dynamic registration configuration creation
Fields
- mode "1p3-dynamic" - LTI 1.3 dynamic registration mode
- platformInfo? LtiConfigurationCreate1p3DynamicPlatformInfo - Optional platform information for dynamic registration
- locale? string - Optional locale code for registration URL. Input values will be automatically normalized to a supported locale code
flatapi: LtiConfigurationCreate1p3DynamicPlatformInfo
Optional platform information for dynamic registration
Fields
- name? string - Platform display name
- url? string - Optional platform homepage or admin URL for reference
flatapi: LtiConfigurationCreate1p3Manual
LTI 1.3 manual configuration creation
Fields
- mode "1p3-manual" - LTI 1.3 manual creation mode
- enableEmailMatching? boolean - Enable email-based user matching during LTI authentication
- clientId? string - OAuth2 client_id allocated by the platform
- authorizationUrl? string - Platform OIDC authorization endpoint URL
- jwksUrl? string - Platform JWKS endpoint URL for public keys
- deploymentId? string - Deployment identifier provided by the platform
- accessTokenUrl? string - Platform access token endpoint URL
- platformIss? string - Platform issuer URL
- platformName? string - Platform display name
flatapi: LtiConfigurationUpdateDeployment
Update fields allowed for deployment-based configurations
Fields
- enableEmailMatching? boolean - Enable email-based user matching during LTI authentication
- deploymentId? string - Deployment identifier provided by the platform
- deploymentBreakdownId? string - Specific tenant identifier for multi-tenant platforms
flatapi: LtiConfigurationUpdateStandalone
Update fields allowed for standalone (manual/dynamic) configurations
Fields
- enableEmailMatching? boolean - Enable email-based user matching during LTI authentication
- clientId? string - OAuth2 client_id allocated by the platform
- authorizationUrl? string - Platform OIDC authorization endpoint URL
- jwksUrl? string - Platform JWKS endpoint URL for public keys
- deploymentId? string - Deployment identifier provided by the platform
- accessTokenUrl? string - Platform access token endpoint URL
- platformIss? string - Platform issuer URL
- platformName? string - Platform display name
flatapi: LtiCredentials
A pair of LTI 1.1 OAuth credentials
Fields
- consumerSecret? string - OAuth 1 Consumer Secret
- creator? string - Unique identifier of the user who created these credentials
- enableEmailMatching boolean(default true) - Enable email-based user matching during LTI authentication. When true (default): If a user with the same email exists in the organization, they will be matched and logged in instead of creating a new account. When false: Email matching is disabled. Only LTI ID matching is used, which means multiple LTI users can share the same email address and have separate Flat accounts. This is useful for cases like siblings sharing a parent email in the LMS
- lms? LmsName - LMS name
- organization? string - The unique identifier of the Organization associated to these credentials
- name? string - Name of the pair of credentials
- lastUsage? string - The last time these credentials were used
- id? string - The unique identifier of this pair of credentials
- creationDate? string - The creation date of these credentials
- consumerKey? string - OAuth 1 Consumer Key
flatapi: LtiCredentialsCreation
Creation of a pair of LTI 1.1 OAuth credentials
Fields
- lms LmsName - LMS name
- name string - Name of the pair of credentials
flatapi: MarkScoreCommentResolvedQueries
Represents the Queries record for the operation: markScoreCommentResolved
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: MarkScoreCommentUnresolvedQueries
Represents the Queries record for the operation: markScoreCommentUnresolved
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: MediaAttachment
Media attachment. The API will automatically resolve the details, oEmbed, and media available if possible and return them in this object
Fields
- dedicated? boolean - True if the resource is dedicated for the assignment (for scores and worksheets), meaning on the user-side this one is stored in the assignment
- htmlHeight? decimal - If the
htmlis available, the height of the widget
- teacherOnly boolean(default false) - If true, this attachment is only visible to teachers. When students view the assignment, attachments with this flag will be filtered out
- sharingMode? MediaScoreSharingMode - The sharing mode of the score for classes post and assignments
- description? string - The resolved description of the attachment
- mimeType? string - The MIME type of the file
- 'type "rich"|"photo"|"video"|"link"|"flat"|"googleDrive"|"worksheet" - The resolved type of the attachment:
rich,photo,videoare automatically resolved aslink- A
flatattachment is a score document where the unique identifier will be specified in thescoreproperty. Its sharing mode will be provided in thesharingModeproperty
- title? string - The resolved title of the attachment
- thumbnailWidth? int - If the
thumbnailUrlis available, the width of the thumbnail
- url? string - The url of the attachment
- googleDriveFileId? string - The ID of the Google Drive File
- revision? string - A unique revision identifier of a score
- score? string - A unique Flat score identifier
- lockScoreTemplate? boolean - To be used with a score attached in
sharingModecopy(score used as template). If true, students won't be able to change the original notes of the template
- authorName? string - The resolved author name of the attachment
- authorUrl? string - The resolved author url of the attachment
- htmlWidth? decimal - If the
htmlis available, the width of the widget
- worksheet? string - A unique worksheet identifier
- html? string - If the attachment type is
richorvideo, the HTML code of the media to display
- iconUrl? string - The URL of the icon
- track? string - A unique track identifier
- partUuid? string - The UUID of the instrument part selected for this attachment (for performance submissions)
- thumbnailHeight? int - If the
thumbnailUrlis available, the height of the thumbnail
- thumbnailUrl? string - If the attachment type is
rich,video,photoorlink, a displayable thumbnail for this attachment
flatapi: MicrosoftGraphAssignment
A Microsoft Teams assignment
Fields
- assignDateTime? string - The date when the assignment will become active on Microsoft Teams.
If set to a future date, the assignment will have status
scheduledand won't be visible to students until this date
- assignedStudentsMsIds? string[] - When assignToType is 'individual', array of Microsoft Azure user IDs of students assigned to this assignment. These are the students who can see and submit to this assignment on Teams
- assignToType? "class"|"individual" - Recipient configuration for this assignment on Microsoft Teams.
class: Assignment is visible to all students in the classindividual: Assignment is visible only to specific assigned students
- alternateLink? string - Absolute link to this assignment in the Microsoft Teams web UI
- id? string - Identifier of the assignment assigned by Microsoft Teams
- state? "draft"|"scheduled"|"published"|"assigned"|"inactive" - State of the assignment on Microsoft Teams.
draft: Assignment is in draft modescheduled: Assignment is scheduled to be published at a future datepublished: Assignment has been published to studentsassigned: Assignment has been assigned (legacy status)inactive: Assignment is inactive
- categories? string[] - List of categories where this assignment is published under
flatapi: MicrosoftGraphSubmission
A Microsoft Teams submission
Fields
- id string - Identifier of the submission assigned by Microsoft Teams
- state string - State of the submission
flatapi: OAuth2RefreshTokenGrantConfig
OAuth2 Refresh Token Grant Configs
Fields
- Fields Included from *OAuth2RefreshTokenGrantConfig
- refreshUrl string(default "https://api.flat.io/oauth/access_token") - Refresh URL
flatapi: OmrCapabilities
What the account or app can do, for client feature-detection
Fields
- outputs OmrJobOutput[] - Output destinations the account can use when creating a job
- remainingCredits? int - OMR credits remaining for the account
- formats string[] - Export formats available via
getOmrJobExport
- localesDetails OmrLocaleDetails[] - The same locales as
locales, each with its English display name, sorted alphabetically bynameand ready to bind to a language picker. Prefer this overlocaleswhen rendering a selector: it saves clients from shipping their own code-to-label table
- acceptedExtensions string[] - Filename extensions the accepted types appear under, for building a file picker.
Use these alongside
acceptedMimeTypesin anacceptattribute: browsers and native file dialogs filter unreliably on some of the image types, so a valid file can be greyed out when only its MIME type is offered. Longer thanacceptedMimeTypes, because one type arrives under several extensions (.jpgand.jpeg,.tifand.tiff,.heicand.heif). Picker metadata only. A file is identified by its content, so its extension never decides whether an upload is accepted
- maxFileSize int - Maximum size of a single file, in bytes
- steps OmrStepName[] - Interactive steps this server supports
- locales string[] - Locales selectable for OCR, as BCP 47 codes sorted alphabetically. These are the locales the recognition pipeline can actually read, which is neither the list of Flat interface locales nor a fixed set: new languages are added over time. Clients should default to the user's own locale when it appears here
- retentionDays? int - How many days a
musicxmljob's uploaded files and results are kept before erasure. Reflects the account's own period when one has been set, otherwise the platform default. Read-only: contact support to change it. Jobs withoutput: libraryare not covered by the retention policy and are unaffected by this value
- maxPages int - Maximum number of pages allowed across all input files of a single job
- acceptedMimeTypes string[] - MIME types accepted for input files: PDF, plus the raster image formats.
Drive the file picker from this list rather than hardcoding it, so newly
supported formats need no client release. A file is identified by its content,
so its declared type and its extension do not have to match.
A multi-page input counts as several pages against
maxPagesand is charged accordingly. That covers PDFs and, among the image formats, multi-page TIFF and animated GIF/WebP
- costPerPage? int - Credits charged per page
- maxParallelJobs int - Maximum number of OMR jobs that can run in parallel for this account
- maxFiles int - Maximum number of input files that can be added to a single job
flatapi: OmrDetailsStepData
Detected score details for the client to review before the score is built. title and
instruments are detected from the input; the language is not detected and is not part
of this payload (read the job's locales, set at creation)
Fields
- instruments OmrDetectedInstrument[] - The instruments detected in the scanned pages
- step "details" - Discriminator for
OmrPendingStep.data; alwaysdetailsfor this payload
- title? string - OCR-detected work title
flatapi: OmrDetailsSubmission
Overrides for the details step. Omitted fields keep the server's detected values
Fields
- instruments? OmrInstrumentOverride[] - Per-part overrides, each matched to a detected part by
index
- step "details" - Discriminator for
OmrStepSubmission; alwaysdetailsfor this submission
- title? string - Override the detected work title
- mainLanguage? string - Override the main language (BCP 47) used for lyric and text reading on resume.
Defaults to the job locale (
locales); set this to correct it on the review screen
flatapi: OmrDetectedInstrument
One detected part
Fields
- instrumentName? string - Localized display name, resolved server-side so the client needs no instruments dictionary
- resolvedConfidence? "high"|"medium"|"low" - Server confidence in the resolved instrument match
- instrumentId? string - Flat instrument ID in dotted
<group>.<instrument>form, for examplebrass.hornorvocals.voice-oohs. See the Instrument IDs reference. Always the canonical (non-premium) ID
- transposeKey? string - Transposition or written key shown in the UI, for example
Ffor Horn in F
- index int - 0-based position of the part in the score
- partName? string - Verbatim part name read from the score
- midiProgram? int - General MIDI program number
flatapi: OmrImportedMetadata
Metadata extracted from the recognized score
Fields
- instruments? string[] - Instrument IDs of the assembled parts
- mainTempoQpm? decimal - Main tempo, in quarter notes per minute
- numberMeasures? int - Number of measures in the recognized score
- mainKeySignature? int - Main key signature as a fifths count (negative for flats, positive for sharps, 0 for C major / A minor)
flatapi: OmrInstrumentOverride
Override for a single detected part, matched by index. Omitted fields keep the
detected value.
To set the instrument you may use either instrumentId (Flat's instrument id)
or midiProgram (a standard General MIDI program) — whichever your integration
prefers; you do not need both. If both are sent, instrumentId wins; otherwise
midiProgram is resolved to the matching instrument; otherwise the detected
instrument is kept. transposeKey and partName apply independently on top
Fields
- instrumentId? string - Override the resolved instrument with this Flat instrument id, for example
brass.horn. See the Instrument IDs reference for valid values. Both the dotted<group>.<instrument>form (brass.horn) and the bare instrument key (horn) are accepted. Use this ormidiProgram. Takes precedence overmidiProgramwhen both are set
- transposeKey? string - Override the transposition / written key: a pitch class as a letter
A-Gwith an optional accidental. For exampleFfor Horn in F orBbfor a B flat clarinet. The accidental may be ASCIIb(flat) or#(sharp), or the Unicode music glyphs♭(U+266D) and♯(U+266F). Unicode accidentals are normalized to their ASCII equivalent, soB♭is stored and returned asBb
- index int - 0-based position of the part to override, matching the
indexof the detected part
- partName? string - Override the part name
- midiProgram? int - Override the instrument with a standard General MIDI program number (0-127),
resolved server-side to the matching Flat instrument. Use this when you do not want
to map Flat instrument ids. Ignored if
instrumentIdis also set
flatapi: OmrJob
Fields
- importedMetadata? OmrImportedMetadata - Metadata extracted from the recognized score
- errorMessage? string - Localized, user-facing error message, present when
statusiserror. Rendered in the caller's locale and safe to display as-is. Pair witherrorCodefor branching
- errorCode? string - Stable, engine-agnostic failure code, present when
statusiserror. Branch on this for custom handling, and rendererrorMessagefor the user-facing text. This is an open string: new codes may be added over time, so keep a generic fallback and never hardcode an exhaustive switch. Current values:NO_MUSIC_DETECTED: no musical content found (poor scan, rotated page, or tablature).CORRUPTED_FILE: the input file is corrupted and could not be read.UNSUPPORTED_FORMAT: the file format or notation is not supported yet.UNSUPPORTED_TABLATURE: the file is guitar tablature, not supported yet.ENCRYPTED_PDF: the PDF is password-protected.TOO_LARGE: the document is too large or has an unusual shape to process.ENGINE_TIMEOUT: recognition took longer than expected and was stopped.GENERIC: unspecified failure
- creationDate? string - When the job was created
- output OmrJobOutput - Where the result of the job goes.
library: import the result into the Flat Library and create a score (default).musicxml: finalize the result only, downloadable viagetOmrJobExport. No score is created, for third-party integrations that do not use the Library
- interactiveSteps OmrStepName[] - Steps this job pauses at for client input, echoing the value set at creation
- currentStep? OmrStepName - The pending step when
statusisawaitingInput. Omitted otherwise
- result? OmrJobResult - The outcome of a finished job. Present when
statusisdone
- locales? string[] - Locale hints (BCP 47) the job was created with, used for OCR and as the default
main language at the
detailsstep
- modificationDate? string - When the job was last updated
- estimatedCredits? int - Credits that will be or were charged at start (page-based), so a client can show a confirmation before charging
- originalFileMetadata? OmrJobFileMetadata - Metadata about the uploaded input
- pendingStep? OmrPendingStep - The step currently awaiting client input. The
datashape is keyed bystep
- progress? OmrJobProgress - Live progress while the job is processing
- id string - Unique identifier of the OMR job
- autoRotate? boolean - Whether the job was created with
autoRotate, echoing the value set at creation
- retention? OmrJobRetention - Data-retention state of the job.
Present only on jobs whose
outputismusicxml. Jobs imported into the Flat library are part of your library content, are not covered by this policy, and omit this object entirely. Erasure happens shortly afterexpiryDaterather than exactly on it. Plan for the deadline, not the instant
- status OmrJobStatus - Status of the job.
draft: created, files can still be added; not yet started or charged.processing: the pipeline is running.awaitingInput: paused on thecurrentStep, waiting for the client to submit it.done: finished. Seeresult.error: failed. SeeerrorCode.canceled: canceled by the client
flatapi: OmrJobCreation
Parameters to create an OMR job. Send without files to create a draft (then add
files with addOmrJobFile and run startOmrJob), or include files and
autoStart: true to import in a single request
Fields
- output? OmrJobOutput - Where the result of the job goes.
library: import the result into the Flat Library and create a score (default).musicxml: finalize the result only, downloadable viagetOmrJobExport. No score is created, for third-party integrations that do not use the Library
- interactiveSteps OmrStepName[](default []) - Steps at which the pipeline should pause for this client. Omit or send
[]for a fully automatic import. The server only pauses at the steps listed here; declare only steps your client can actually render
- locales? string[] - Locale hints (BCP 47) to improve text and lyric detection, for example
["ja", "en"]. The first entry is the primary reading language. This is the input hint; the main language can be confirmed or corrected at thedetailsstep
- idempotencyKey? string - Optional client-supplied key. A retry with the same key returns the existing job instead of creating a duplicate, for safe retries on flaky networks
- files? OmrJobInputFile[] - Optional inline inputs for a one-shot import. For multi-image or mobile capture, omit this and use
addOmrJobFile
- collection? string - Target collection ID. Only used when
outputislibrary
- autoRotate boolean(default false) - Let the server detect and correct pages uploaded sideways or upside down (90/180/270°) before recognition. Off by default: pages are recognized in the orientation they are uploaded in, which is the right choice when your client lets the user rotate pages before upload. Enable it when it does not, for example a server-to-server integration importing scans as they come. Small tilt correction (a few degrees) always runs
- autoStart? boolean - Start processing immediately. Only valid when
filesis provided
flatapi: OmrJobFileMetadata
Metadata about the uploaded input
Fields
- filename? string - Original filename of the input as uploaded (of the first file when several were combined)
- numberOfPages? int - Total number of pages across all input files
- fileSize? int - Combined size of the input files, in bytes
- fileExtension? string - File extension of the input, without the leading dot (for example
pdf)
- mimeType? string - MIME type of the input (of the first file when several were combined)
- fileCount? int - Number of input files attached
flatapi: OmrJobFileUpload
One image or PDF added to a draft job
Fields
- file string - File data, base64-encoded. The type is read from the content itself, so no
declared MIME type or filename extension is needed. Accepted types are listed by
getOmrCapabilitiesinacceptedMimeTypes
- filename? string - Optional original filename, kept for display
flatapi: OmrJobFileUploadResult
Result of adding a file to a draft job
Fields
- fileIndex? int - 0-based index assigned to the uploaded file
- fileCount? int - Total number of files now attached to the job
flatapi: OmrJobInputFile
A single image or PDF input, base64-encoded
Fields
- file string - File data, base64-encoded. The type is read from the content itself, so no
declared MIME type or filename extension is needed. Accepted types are listed by
getOmrCapabilitiesinacceptedMimeTypes
- filename? string - Optional original filename, kept for display
flatapi: OmrJobProgress
Live progress while the job is processing
Fields
- text? string - Localized progress message, ready to display
- percent? decimal - Completion percentage (0-100)
- 'key? string - Stable progress key (for example
OMR_QUEUED,OMR_PROCESSING_PAGE,OMR_CREATING_SCORE), for matching the current phase in a stepper UI independent of locale
flatapi: OmrJobResult
The outcome of a finished job. Present when status is done
Fields
- score? string - Created score ID, when
outputislibrary
- exports? string[] - Formats available via
getOmrJobExport, for example["musicxml", "mxl", "midi"]
flatapi: OmrJobRetention
Data-retention state of the job.
Present only on jobs whose output is musicxml. Jobs imported into the Flat library
are part of your library content, are not covered by this policy, and omit this object
entirely.
Erasure happens shortly after expiryDate rather than exactly on it. Plan for the
deadline, not the instant
Fields
- expiryDate string - When this job's uploaded files and recognition results become eligible for erasure. Fixed when the job is created: changing the account's retention period does not move the deadline of jobs that already exist
- expiredDate? string - When the job's stored files were actually erased. Present only once that happened.
An expired job keeps the
statusit finished with and stays listable, but itsresultis no longer served and downloads fail withOMR_JOB_EXPIRED
flatapi: OmrLocaleDetails
An OCR-selectable locale with its English name
Fields
- code string - BCP 47 locale code. Always one of the codes listed in
locales
- name string - English name of the language, for display in a picker
flatapi: OmrPendingStep
The step currently awaiting client input. The data shape is keyed by step
Fields
- data OmrDetailsStepData - The data of the pending step
- step OmrStepName - Interactive pipeline step. Forward-compatible: new values may be added over time.
Only steps a client lists in
interactiveStepscan pause that client's job; any step a client does not list (including future ones) is auto-resolved by the server.details: confirm or adjust the detected title, main language and instruments before the score is built. Resuming from this step is fast: note recognition is already done and is not run again
flatapi: OrganizationInvitation
Details of an invitation to join an organization
Fields
- invitedBy? string - The unique identifier of the User who created this invitation
- allowMultipleUse boolean - If true, the invitation can be used multiple times. If false, the invitation can only be used once
- organizationRole OrganizationRoles - User's Organization Role (for Edu users only)
- organization string - The unique identifier of the Organization this invitation belongs to
- htmlUrl? string - URL to join the organization using this invitation
- id? string - The invitation unique identifier
- creationDate? string - The creation date of the invitation
- email? string - The email address this invitation was sent to
- usedBy? string[] - List of users who used this invitation
- customCode string? - Enrollment code to use when joining this organization
flatapi: OrganizationInvitationCreation
The parameters to create an organization invitation
Fields
- organizationRole "admin"|"teacher"|"accountAdmin" (default "teacher") - User's Organization Role
- email? string - The email address you want to send the invitation to
flatapi: OrganizationUserAccessTokenCreation
Creation of a delegated API access token for an organization user
Fields
- scopes AppScopes[] - List of requested scopes for this credential
flatapi: RemoveOrganizationUserQueries
Represents the Queries record for the operation: removeOrganizationUser
Fields
- 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 performing this operation, you need to be sure that the user is at least 13 years old and has read and agreed to the Individual Terms of Service of Flat available on https://flat.io/legal
flatapi: RemoveScoreCollaboratorQueries
Represents the Queries record for the operation: removeScoreCollaborator
Fields
- eventProperties? string - Optional analytics properties merged into the analytics events recorded for this request.
JSON-encoded string representing event properties. Example:
?eventProperties={"context":"discover","screenLevel0":"home"}
flatapi: RenameGroupRequest
Fields
- name string - New name for the group
flatapi: ResourceCollaborator
A collaborator of a score. The userEmail and group are only available if the requesting user is a collaborator of the related score (otherwise these permissions are not listed or exposed publicly)
Fields
- Fields Included from *ResourceRights
- date? string - The date when the permission was added
- score? string - If this object is a permission of a score, this property will contain the unique identifier of the score
- invited? boolean - If this property is
true, this is still a pending invitation
- userEmail? string - If the collaborator is not a user of Flat yet, this field will contain their email
- id? string - The unique identifier of the permission
- collection? string - If this object is a permission of a collection, this property will contain the unique identifier of the collection
- user? UserPublic - Public User details
- group? Group - A group of users
flatapi: ResourceCollaboratorCreation
Add a collaborator to a resource
Fields
- aclWrite boolean(default false) -
Trueif the related user can modify the score
- userToken? string - Token received in an invitation to join the score
- aclRead boolean(default true) -
Trueif the related user can read the score. (probably true if the user has a permission on the document)
- userEmail? string - Fill this field to invite an individual user by email
- aclAdmin boolean(default false) -
Trueif the related user can manage the current document, i.e. changing the document permissions and deleting the document
- user? string - The unique identifier of a Flat user
- group? string - The unique identifier of a Flat group
flatapi: ResourceRights
The rights of the current user on a score or collection
Fields
- aclWrite boolean(default false) -
Trueif the current user can modify the current document. If this is a right of a Collection, the capabilities of the associated user can be lower than this permission, check out thecapabilitiesproperty as the end-user to have the complete possibilities with the collection
- aclRead boolean(default false) -
Trueif the current user can read the current document
- isCollaborator boolean(default false) -
Trueif the current user is a collaborator of the current document (direct or via group)
- aclAdmin boolean(default false) -
Trueif the current user can manage the current document (i.e. share, delete) If this is a right of a Collection, the capabilities of the associated user can be lower than this permission, check out thecapabilitiesproperty as the end-user to have the complete possibilities with the collection
- collaboratorType? "owner"|"user"|"group" - The type of the collaborator for the resource
flatapi: ScoreComment
Comment added on a sheet music
Fields
- date string - The date when the comment was posted
- resolvedBy? string - If the comment is marked as resolved, this will contain the unique identifier of the User who marked this comment as resolved
- 'type "document"|"inline" - The type of the comment
- revision? string - The unique identifier of the revision where the comment was posted
- score string - The unique identifier of the score where the comment was posted
- modificationDate? string - The date of the last comment modification
- mentions? string[] - The list of user identifiers mentioned in this comment
- moderation? ScoreCommentModeration - Information about the comment being moderated
- replyTo? string - When the comment is a reply to another comment, the unique identifier of the parent comment
- context? 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)
- comment string - The comment text that can include mentions using the following
format:
@[id:username]
- id string - The comment unique identifier
- rawComment string - A raw version of the comment, that can be displayed without parsing the mentions
- spam? boolean -
trueif the message has been detected as spam and hidden from other users
- user string - The author unique identifier
- resolved? boolean - For inline comments, the comment can be marked as resolved and will be hidden in the future responses
flatapi: 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)
Fields
- staffIdx? decimal - (Deprecated, use
staffUuid) The identifier of the staff
- measureUuids string[] - The list of measure UUIDs
- partUuid string - The unique identifier (UUID) of the score part
- staffUuid? string - The unique identifier (UUID) of the staff
- stopDpq decimal - The division per quarter note where the commented range stops
- startTimePos decimal - The time position where the commented range starts
- stopTimePos decimal - The time position where the commented range stops
- startDpq decimal - The division per quarter note where the commented range starts
flatapi: ScoreCommentCreation
Creation of a comment
Fields
- mentions? string[] - 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
- context? 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)
- comment string - The comment text that can include 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
- revision? string - The unique identifier 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
flatapi: ScoreCommentModeration
Information about the comment being moderated
Fields
- reason? "spam"|"inappropriate" - If the comment is hidden, the reason why this one has been moderated
- hidden? boolean - If true, this comment will be hidden from other users
flatapi: ScoreCommentsCounts
A computed version of the total, unique, weekly, monthly and yearly number of comments added on the documents (this doesn't include inline comments)
Fields
- total? decimal - The total number of comments added to the score
- unique? decimal - The unique (1/user) number of comments added to the score
- monthly? decimal - The monthly unique number of comments added to the score
- yearly? decimal - The yearly unique number of comments added to the score
- weekly? decimal - The weekly unique number of comments added to the score
flatapi: ScoreCommentUpdate
Update of a comment
Fields
- context? 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)
- comment? string - The comment text that can include 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
- revision? string - The unique identifier 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
flatapi: ScoreCreationBuilderData
Fields
- Fields Included from *ScoreCreationCommon
- googleDriveFolder string
- privacy ScorePrivacy
- collection string
- title string
- anydata...
- builderData ScoreCreationBuilderData_builderData -
- title 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-titleorcredit-wordsfor MusicXML files). - Use the name of the file for files from a specified
source(e.g. Google Drive) or the one in thefilenameproperty - Set a default title (e.g. "New Music Score")
- Use the title contained in the file (e.g.
flatapi: ScoreCreationBuilderData_builderData
Fields
- layoutData? ScoreCreationBuilderData_builderData_layoutData - Control the appearance of the score. If missing, default values are used.
- scoreData ScoreCreationBuilderData_builderData_scoreData -
flatapi: ScoreCreationBuilderData_builderData_layoutData
Control the appearance of the score. If missing, default values are used.
Fields
- notesSpacingCoeff? decimal - A float value >= 1 that controls the spacing between notes.
- pageMarginRight? decimal - The right margin of the page in chosen unit (
lengthUnit).
- pageMarginTop? decimal - The top margin of the page in chosen unit (
lengthUnit).
- lengthUnit "cm"|"inch" (default "cm") - The unit to use for layout customizations
- pageMarginBottom? decimal - The bottom margin of the page in chosen unit (
lengthUnit).
- pageMarginLeft? decimal - The left margin of the page in chosen unit (
lengthUnit).
- pageHeight? decimal - The height of the page in chosen unit (
lengthUnit).
- pageWidth? decimal - The width of the page in chosen unit (
lengthUnit).
flatapi: ScoreCreationBuilderData_builderData_scoreData
Fields
- nbBeats? decimal - The number of beats in the measure
- useChordGrid? boolean - true if the chord grid must be displayed with fretted instruments
- instruments ScoreCreationBuilderData_builderData_scoreData_instruments[] - The list of instruments to add to the score.
See the Instrument IDs reference for the possible values for
groupandinstrument(also available as the@flat/instrumentspackage).
- useTabStaff? boolean - true if the TAB staff is displayed with fretted instruments
- beatType? decimal - The duration of a beat in the measure
- fifths? decimal - The key signature of the score (expressed between -7 and 7). Major C is used when the value is not provided.
flatapi: ScoreCreationBuilderData_builderData_scoreData_instruments
Fields
- instrument string - The identifier of the instrument (e.g.
piano,trumpet)
- shortName? string - The abbreviation of the name of the instrument
- hasQuarterTone? boolean - True if the part can use quarter tones (prevents the part from having a TAB staff or chord grid)
- group string - The identifier of the instrument group (e.g.
keyboards,brass)
- longName? string - The full name of the instrument
flatapi: ScoreCreationCommon
Fields
- googleDriveFolder? string - If the user uses Google Drive and this property is specified, the file will be created in this directory. The user creating the file must have write access to this directory
- privacy? ScorePrivacy - The score main privacy mode.
public: The score is public on the Internet. This one can be accessible at the urlhttps://flat.io/score/{score}and can be modified and administered by specified collaborators users.private: The score is private and can be only accessed, modified and administered by specified collaborators users.privateLink: The score is private but can be accessed using a private linkhtmlUrlor the private key in the propertysharingKey.organizationPublic: Available only with Flat for Education. The score is public in the organization: users of the same organization can access it. The score can be modified and administered by specified collaborators users.
publicmode 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 not be added to any collection and will only be visible in the
allScoresvirtual collection
- title? 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-titleorcredit-wordsfor MusicXML files). - Use the name of the file for files from a specified
source(e.g. Google Drive) or the one in thefilenameproperty - Set a default title (e.g. "New Music Score")
- Use the title contained in the file (e.g.
flatapi: ScoreCreationFileImport
Fields
- Fields Included from *ScoreCreationCommon
- googleDriveFolder string
- privacy ScorePrivacy
- collection string
- title string
- anydata...
- filename? string - If this is an imported file, its filename
- data string - The data of the score file. See the
POST /scoresendpoint description for the full list of supported formats. Binary payloads (e.g. compressed MusicXML, MIDI, Guitar Pro) can be encoded in Base64, in this case thedataEncodingproperty must match the encoding used for the API request
- dataEncoding? "base64" - The optional encoding of the score data. This property must match the encoding used for the
dataproperty
- supportsTasks? boolean - Set this to
trueif the client supports asynchronous task flows. When importing a score that requires OMR processing (a PDF or a page image), the API will return a 202 Accepted response along with a task reference. The client can then check the task status using the endpointGET /v2/tasks/{task}
flatapi: ScoreCreationGoogleDriveImport
Fields
- Fields Included from *ScoreCreationCommon
- googleDriveFolder string
- privacy ScorePrivacy
- collection string
- title string
- anydata...
- 'source ScoreSource -
flatapi: ScoreDetails
The score and all its details
Fields
- Fields Included from *ScoreSummary
- htmlUrl string
- privacy ScorePrivacy
- id string
- title string
- sharingKey string
- user UserPublic
- anydata...
- lyricist? string - Lyricist of the score
- licenseText? string - Additional license text written on the exported/printed score
- mainTempoQpm? decimal - The main tempo of the score (in QPM)
- highlightedDate? string - The date when the score was highlighted (featured) on our community
- description? string - Description of the creation
- numberMeasures? int - The number of measures in the score
- googleDriveFileId? string - If the user uses Google Drive and the score exists on Google Drive, this field will contain the unique identifier of the Flat score on Google Drive. You can access the document using the url:
https://drive.google.com/open?id={googleDriveFileId}
- instruments string[] - An array of the instrument identifiers used in the last version of the score.
This is mainly used to display a list of the instruments in Flat's UI or instruments icons.
The format of the strings is
{instrument-group}.{instrument-id}
- collections? string[] - The list of parent collections this score is included in. Please note that you might not have access to all of them
- rights? ResourceRights - The rights of the current user on a score or collection
- me? ScoreDetails_me - Information about the authenticated user and this score
- collaborators ResourceCollaborator[] - The list of the collaborators of the score
- parentScore? string - If the score has been forked, the unique identifier of the parent score
- mainKeySignature? decimal - The main key signature of the score (expressed between -7 and 7)
- publicationDate? string - The date when the score was published on Flat
- views? ScoreViewsCounts - A computed version of the total, weekly, monthly, and yearly number of views of the score
- likes? ScoreLikesCounts - A computed version of the weekly, monthly, yearly and total number of likes for a score
- durationTime? decimal - In seconds, an approximate duration of the score
- comments? ScoreCommentsCounts - A computed version of the total, unique, weekly, monthly and yearly number of comments added on the documents (this doesn't include inline comments)
- plays? ScorePlaysCounts - A computed version of the total, weekly, monthly, and yearly number of plays of the score
- scheduledDeletionDate? string - The date when the score will be definitively deleted.
This date can be in the past if the score will be deleted at the next deletion batch, in this case you can display something like "Deleted shortly".
Schedule:
- For all paying users, the scores will be definitively deleted after 90 days.
- For free users, the scores are no longer available after 24 hours, and can be restored with a paying account up to 90 days
- composer? string - Composer of the score
- creationDate string - The date when the score was created
- arranger? string - Arranger of the score
- samples string[] - An array of the audio sample identifiers used by the different score parts.
The format of the strings is
{instrument-group}.{sample-id}
- tags? ScoreDetailsTagsItemsString[] - Tags describing the score
- instrumentsNames string[] - An array of the instrument names used in the last version of the score.
This list is localized and ready-to-display and will match the indexes from the
instrumentslist
- creationType? ScoreCreationType? - The type of creation (an original, an arrangement)
- license? ScoreLicense? - License of the creation. Read more about the Creative Commons licenses on https://creativecommons.org/licenses/
- modificationDate? string - The date of the last revision of the score
- editHtmlUrl string - The url where the score can be edited in a web browser
- subtitle? string - Subtitle of the score
- organization? string - If the score has been created in an organization, the identifier of this organization. This property is especially used with the score privacy
organizationPublic
flatapi: ScoreDetails_me
Information about the authenticated user and this score
Fields
- isLiked boolean - True if the current user likes this score
- isInLibrary boolean - True if the score is stored in one of the user's collections
flatapi: ScoreFork
Options to fork the score
Fields
- 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)
- collection? string? - Unique identifier of a collection where the score will be copied.
If no collection identifier is provided, a virtual collection is used, or
nullis provided, the score won't be added to any collection and will only be visible in theallScoresvirtual collection
flatapi: ScoreLikesCounts
A computed version of the weekly, monthly, yearly and total number of likes for a score
Fields
- total? decimal - The total number of likes of the score
- monthly? decimal - The number of new likes during the last month
- yearly? decimal - The number of new likes during the last year
- weekly? decimal - The number of new likes during the last week
flatapi: ScoreModification
Edit the score metadata
Fields
- creationType? ScoreCreationType? - The type of creation (an original, an arrangement)
- license? ScoreLicense? - License of the creation. Read more about the Creative Commons licenses on https://creativecommons.org/licenses/
- lyricist? string? - The lyricist of the score
- licenseText? string? - The rights info written on the score
- composer? string? - The composer of the score
- subtitle? string? - The subtitle of the score
- privacy? ScorePrivacy - The score main privacy mode.
public: The score is public on the Internet. This one can be accessible at the urlhttps://flat.io/score/{score}and can be modified and administered by specified collaborators users.private: The score is private and can be only accessed, modified and administered by specified collaborators users.privateLink: The score is private but can be accessed using a private linkhtmlUrlor the private key in the propertysharingKey.organizationPublic: Available only with Flat for Education. The score is public in the organization: users of the same organization can access it. The score can be modified and administered by specified collaborators users.
publicmode is not available)
- description? string? - Description of the creation
- title? string - The title of the score
- arranger? string? - The arranger of the score
- sharingKey? string - When using the
privacymodeprivateLink, this property can be used to set a custom sharing key, otherwise a new key will be generated
- tags? string[] - Tags describing the score
flatapi: ScorePlaysCounts
A computed version of the total, weekly, monthly, and yearly number of plays of the score
Fields
- total? decimal - The total number of plays of the score
- monthly? decimal - The monthly number of plays of the score
- yearly? decimal - The yearly number of plays of the score
- weekly? decimal - The weekly number of plays of the score
flatapi: ScoreRevision
A score revision metadata
Fields
- date string - The date when this revision was created
- score string - The score identifier
- autosave? boolean - True if this revision was automatically generated by Flat and not on purpose by the user
- collaborators? string[] - The user identifiers of the collaborators of the revision
- description? string - A description associated to the revision
- id string - The unique identifier of the revision
- event? string - The last event (action id) of the revision
- user? string - The user identifier who created the revision
- statistics? ScoreRevisionStatistics - The statistics related to the score revision (additions and deletions)
flatapi: ScoreRevisionCreation
A new created revision
Fields
- autosave? boolean - Must be set to
trueif the revision was created automatically
- data string - The data of the score file. It must be a MusicXML 3 file (
vnd.recordare.musicxmlorvnd.recordare.musicxml+xml), a MIDI file (audio/midi) or a Flat JSON file. Binary payloads (vnd.recordare.musicxmlandaudio/midi) can be encoded in Base64, in this case thedataEncodingproperty must match the encoding used for the API request
- dataEncoding? "base64" - The optional encoding of the score data. This property must match the encoding used for the
dataproperty
- description? string - A description associated to the revision
flatapi: ScoreRevisionStatistics
The statistics related to the score revision (additions and deletions)
Fields
- additions? decimal - The number of additions operations in the last revision
- deletions? decimal - The number of deletions operations in the last revision
- endDate? string - The date of the latest action included in this revision
- startDate? string - The date of the first action included in this revision
flatapi: ScoreSource
Fields
- googleDrive? string - If the score is a file on Google Drive, this property must contain its identifier. To use this method, the Drive file must be public or the Flat Drive App must have access to the file
flatapi: ScoreSummary
A summary of the score details
Fields
- htmlUrl string - The url where the score can be viewed in a web browser
- privacy ScorePrivacy - The score main privacy mode.
public: The score is public on the Internet. This one can be accessible at the urlhttps://flat.io/score/{score}and can be modified and administered by specified collaborators users.private: The score is private and can be only accessed, modified and administered by specified collaborators users.privateLink: The score is private but can be accessed using a private linkhtmlUrlor the private key in the propertysharingKey.organizationPublic: Available only with Flat for Education. The score is public in the organization: users of the same organization can access it. The score can be modified and administered by specified collaborators users.
publicmode is not available)
- id string - The unique identifier of the score
- title string - The title of the score
- sharingKey? string - The private sharing key of the score (available when the
privacymode is set toprivateLink)
- user UserPublic - Public User details
flatapi: ScoreTrack
An audio track for a score
Fields
- synchronizationPoints? ScoreTrackPoint[] - The synchronization points between the track and the score
- creator string - The unique identifier of the track creator
- purpose ScoreTrackPurpose - The purpose of the audio track
- title? string - Title of the track
- creationDate string - The creation date of the track
- 'type ScoreTrackType - The type of an audio track
- mediaId? string - The unique identifier of the track when hosted on an external service.
For example, if the url is
https://www.youtube.com/watch?v=dQw4w9WgXcQ,mediaIdwill bedQw4w9WgXcQ
- url? string - The URL of the track
- score? string - The unique identifier of the score. Absent for Free Record performance submissions, which are recorded without an attached score
- modificationDate string - The modification date of the track
- default boolean - True if the track should be used as default audio source
- id string - The unique identifier of the score track
- state ScoreTrackState - State of the track
flatapi: ScoreTrackCreation
Creation of a new track. This one must contain the URL of the track or the corresponding file
Fields
- synchronizationPoints? ScoreTrackPoint[] - The synchronization points between the track and the score
- default? boolean - True if the track should be used as default audio source
- purpose? ScoreTrackPurpose - The purpose of the audio track
- state? ScoreTrackState - State of the track
- title? string - Title of the track
- url? string - The URL of the track
flatapi: ScoreTrackCreationResponse
Response for track creation including optional upload information
Fields
- track ScoreTrack - An audio track for a score
flatapi: ScoreTrackPoint
A track synchronization point
Fields
- measureUuid? string - The measure unique identifier
- time decimal - The corresponding time in seconds
- 'type "measure"|"end" - The type of the synchronization point. If the type is
measure, the measure uuid must be present inmeasureUuid
flatapi: ScoreTrackUpdate
Update an existing track
Fields
- synchronizationPoints? ScoreTrackPoint[] - The synchronization points between the track and the score
- default? boolean - True if the track should be used as default audio source
- purpose? ScoreTrackPurpose - The purpose of the audio track
- state? ScoreTrackState - State of the track
- title? string - Title of the track
flatapi: ScoreViewsCounts
A computed version of the total, weekly, monthly, and yearly number of views of the score
Fields
- total? decimal - The total number of views of the score
- monthly? decimal - The monthly number of views of the score
- yearly? decimal - The yearly number of views of the score
- weekly? decimal - The weekly number of views of the score
flatapi: StartOmrJobHeaders
Represents the Headers record for the operation: startOmrJob
Fields
- xFlatLocale? string - Preferred locale for localized content in the response (translated error messages, emails, etc.).
Accepts any IETF language tag. The API best-matches the value to a supported locale and never rejects an unknown one (it falls back to the closest match, then to
en). Supported normalized locales:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ko,ms,nl,nb,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW. Precedence (highest first): thisX-Flat-Localeheader, the authenticated user's account locale, theAccept-Languageheader, thenen
flatapi: SubmitOmrJobStepHeaders
Represents the Headers record for the operation: submitOmrJobStep
Fields
- xFlatLocale? string - Preferred locale for localized content in the response (translated error messages, emails, etc.).
Accepts any IETF language tag. The API best-matches the value to a supported locale and never rejects an unknown one (it falls back to the closest match, then to
en). Supported normalized locales:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ko,ms,nl,nb,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW. Precedence (highest first): thisX-Flat-Localeheader, the authenticated user's account locale, theAccept-Languageheader, thenen
flatapi: Task
An asynchronous task
Fields
- errorHistory? string[] - If any errors happened when processing this task, the list of errors identifiers
- format? string - For files processing, the file format (e.g.
mp3,wav)
- 'type? string - Type of the task:
audio-export: Exports a score to audio format (MP3, WAV)score-save: Saves or updates a score documentimport-omr: Processes a PDF through OMR (Optical Music Recognition) and imports it as a score
- creationDate? string - The creation date of the task
- revision? string - The score revision identifier for tasks related to scores
- result? TaskResult - Optional result information about this task
- score? string - The score unique identifier for tasks related to scores
- modificationDate? string - The last modification date of the task
- children? Task[] - Child tasks for hierarchical task structures (e.g., conversion subtasks)
- isCancellable? boolean - Whether the task can be canceled by the user.
Only
truewhen the task is increatedstate (waiting to be processed)
- progress? TaskProgress - Details about the task progression
- id string - Unique identifier of the task
- state "created"|"blocked"|"doing"|"done"|"canceled"|"error" - State of the Task
- doneDate? string - The date when the task has been completed
flatapi: TaskExportOptions
Options for the requested export
Fields
- parts? string[] - A list of parts to specifically export
flatapi: TaskProgress
Details about the task progression
Fields
- text? string - Text details of the task progress
- percent? decimal - Percent of the task progression
flatapi: TaskResult
Optional result information about this task
Fields
- 'error? string - Error message, when the task failed
- url? string - URL of the generated file, when the task produces one
flatapi: UpdateScoreCommentQueries
Represents the Queries record for the operation: updateScoreComment
Fields
- sharingKey? string - This sharing key must be specified to access to a score or collection with a
privacymode set toprivateLinkand the current user is not a collaborator of the document
flatapi: UserAdminUpdate
User update as an organization admin
Fields
- password? string - Password of the account
- firstname? string - First name of the user
- organizationRole? OrganizationRoles - User's Organization Role (for Edu users only)
- email? string - Email of the account
- username? string - Username of the account
- lastname? string - Last name of the user
flatapi: UserAzureDetails
Fields
- preferredUsername? string - User Preferred Username (UPN), i.e. the main email of the user
- oid? string - User object identifier on Azure AD
- hd? string - User tenant (domain name)
flatapi: UserBasics
Fields
- badges? string[] - List of badges for the user profile:
powerstaffcomposerOfTheMonthambassadorchallenge
- product TutteoProduct - A Tutteo product.
flat: Flat - Music notation software for individual usersflatEdu: Flat for Education - Music notation software for schools and educatorsmsnippet: Music Snippet - Embeddable music snippets for websitesembed: Flat Embed - Embeddable music notation editor
- printableName? string - The name that can be directly printed (name, firstname & lastname, or username)
- firstname? string - Firstname of the user (for education users)
- name? string - A displayable name for the user (for consumer users)
- id string - The user unique identifier
- 'type "user"|"guest" - The type of user account
- picture string? - The URL of the picture to display
- username string - The user name (unique for the organization)
- lastname? string - Lastname of the user (for education users)
flatapi: UserCommunityProfileLinks
Social networks links
Fields
- spotifyUrl? string? - Spotify Profile URL
- websiteUrl? string? - Personal website URL
- youtubeUrl? string? - YouTube channel URL
- soundcloudUrl? string? - SoundCloud Profile URL
- instagramUrl? string? - Instagram profile URL. For updates, also accepts Instagram usernames
- tiktokUrl? string? - TikTok profile URL. For updates, also accepts TikTok usernames
flatapi: UserCreation
User creation
Fields
- firstname? string - First name of the user
- password string - Password of the new account
- role "user"|"teacher"|"admin"|"accountAdmin" (default "user") - Role of the new account
- locale string(default "en") - User language. Input values will be automatically normalized to a supported locale code
- email? string - Email of the new account
- username string - Username of the new account
- lastname? string - Last name of the user
flatapi: UserDetails
User details
Fields
- Fields Included from *UserPublic
- allPublicScoresCount int
- likesCount int
- coverPicture string|()
- profileTheme string
- likedScoresCount int
- playsCount int
- registrationDate string
- bio string
- links UserCommunityProfileLinks
- followersCount int
- ownedPublicScoresCount int
- followingCount int
- organizationRole OrganizationRoles
- classRole ClassRoles
- organization string
- htmlUrl string
- badges string[]
- product TutteoProduct
- printableName string
- firstname string
- name string
- id string
- type "user"|"guest"
- picture string|()
- username string
- lastname string
- anydata...
- pictureFile? string? - The ID of the user profile picture
- groups? string[] - For Flat for Education accounts, list of Group identifiers the user is part of
- privateProfile? boolean - Whether this user profile is private (individual accounts only)
- azureDetails? UserAzureDetails - The Microsoft Azure account details of the user
- locale? FlatLocalesString - The user language. Input values will be automatically normalized to a supported locale code. Unknown locales will default to
en. Current supported locales include:da,de,en,en-GB,es,fi,fil,fr,fr-CA,hi,id,it,ja,ja-HIRA,ko,ms,nb,nl,pl,pt,pt-BR,ro,ru,sv,tr,zh-Hans,zh-HK,zh-TW
- isEmailVerified? boolean - Whether the user's email address has been verified
- coverPictureFile? string? - The ID of the user profile cover picture
flatapi: UserDetailsAdmin
User details (view for organization teacher / admin)
Fields
- Fields Included from *UserPublicSummary
- organizationRole OrganizationRoles
- classRole ClassRoles
- organization string
- htmlUrl string
- badges string[]
- product TutteoProduct
- printableName string
- firstname string
- name string
- id string
- type "user"|"guest"
- picture string|()
- username string
- lastname string
- anydata...
- license? UserDetailsAdmin_license - Current active license of the user
- lastActivityDate? string - Date of the last user activity
- isEduTestingStudent? boolean - Indicates if the user account is marked as a testing student account. Testing students are typically excluded from certain educational integrations and workflows. This field helps API clients distinguish between regular students and testing accounts
- groups? string[] - For Flat for Education accounts, list of Group identifiers the user is part of
- email? string - Email of the user
flatapi: UserDetailsAdmin_license
Current active license of the user
Fields
- mode? LicenseMode - Mode of the license
- active? boolean - Whether the license is currently active
- id? string - ID of the current license
- 'source? LicenseSources - Source of the license
- expirationDate? string - Date when the license expires
flatapi: UserPublic
Public User details
Fields
- Fields Included from *UserPublicSummary
- organizationRole OrganizationRoles
- classRole ClassRoles
- organization string
- htmlUrl string
- badges string[]
- product TutteoProduct
- printableName string
- firstname string
- name string
- id string
- type "user"|"guest"
- picture string|()
- username string
- lastname string
- anydata...
- allPublicScoresCount? int - Total number of public scores the user participates in (owned + joined)
- likesCount? int - Number of likes on the user published scores
- coverPicture? string? - Cover picture (background) for the profile
- profileTheme? string - Theme (background) for the profile
- likedScoresCount? int - Number of the scores liked by the user
- playsCount? int - Number of plays on the user published scores
- registrationDate? string - Date the user signed up
- bio? string - User's biography
- links? UserCommunityProfileLinks - Social networks links
- followersCount? int - Number of followers the user has
- ownedPublicScoresCount? int - Number of public scores the user owns
- followingCount? int - Number of people the user follows
flatapi: UserPublicSummary
Public User details summary
Fields
- Fields Included from *UserBasics
- organizationRole? OrganizationRoles - User's Organization Role (for Edu users only)
- classRole? ClassRoles - User's Class Role (for Edu users only)
- organization? string - Organization ID (for Edu users only)
- htmlUrl? string - Link to user profile (for Indiv. users only)
flatapi: UserSigninLink
Fields
- url? string - URL to use to sign in to this account
- token? string - Raw sign-in token, can be used to build custom URLs (e.g. deep links)
- expirationDate? string - Date when the link expires
flatapi: UserSigninLinkCreation
Fields
- destinationPath string(default "/") - Path to redirect to after signin
Union types
flatapi: LicenseSources
LicenseSources
Source of the license
flatapi: ScoreCreation
ScoreCreation
flatapi: AssignmentSubmissionState
AssignmentSubmissionState
State of the submission
flatapi: EduResourcePrivacy
EduResourcePrivacy
The Education resource privacy mode
flatapi: ScoreTrackState
ScoreTrackState
State of the track
flatapi: LmsName
LmsName
LMS name
flatapi: LicenseMode
LicenseMode
Mode of the license
flatapi: ScoreTrackPurpose
ScoreTrackPurpose
The purpose of the audio track
flatapi: LtiConfigurationUpdate
LtiConfigurationUpdate
Update an existing LTI 1.3 configuration (deployment clone or standalone)
flatapi: OrganizationRoles
OrganizationRoles
User's Organization Role (for Edu users only)
flatapi: AssignmentType
AssignmentType
Type of the assignment
flatapi: AssignmentSubmissionStudentsMode
AssignmentSubmissionStudentsMode
Submission mode for assignments:
- "single": Individual submissions (default)
- "group": Group submissions (for shared writing assignments)
flatapi: ClassRoles
ClassRoles
User's Class Role (for Edu users only)
flatapi: EduResourceType
EduResourceType
Type of an education resource
flatapi: OmrJobStatus
OmrJobStatus
Status of the job.
draft: created, files can still be added; not yet started or charged.processing: the pipeline is running.awaitingInput: paused on thecurrentStep, waiting for the client to submit it.done: finished. Seeresult.error: failed. SeeerrorCode.canceled: canceled by the client
flatapi: OmrJobOutput
OmrJobOutput
Where the result of the job goes.
library: import the result into the Flat Library and create a score (default).musicxml: finalize the result only, downloadable viagetOmrJobExport. No score is created, for third-party integrations that do not use the Library
flatapi: ClassState
ClassState
The state of a classroom
flatapi: MediaScoreSharingMode
MediaScoreSharingMode
The sharing mode of the score for classes post and assignments
flatapi: LtiConfigurationCreate
LtiConfigurationCreate
Request to create a new LTI configuration (unified 1.1 and 1.3)
flatapi: ScorePrivacy
ScorePrivacy
The score main privacy mode.
public: The score is public on the Internet. This one can be accessible at the urlhttps://flat.io/score/{score}and can be modified and administered by specified collaborators users.private: The score is private and can be only accessed, modified and administered by specified collaborators users.privateLink: The score is private but can be accessed using a private linkhtmlUrlor the private key in the propertysharingKey.organizationPublic: Available only with Flat for Education. The score is public in the organization: users of the same organization can access it. The score can be modified and administered 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 choose 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)
flatapi: ScoreCreationType
ScoreCreationType
The type of creation (an original, an arrangement)
flatapi: LtiConfiguration
LtiConfiguration
LTI configuration details (unified 1.1 and 1.3)
flatapi: GroupType
GroupType
The type of the group:
generic: A group created by a Flat userclassTeachers: A group created automatically by Flat that contains the teachers of a classclassStudents: A group created automatically by Flat that contains the students of a classclassStudentsSubGroup: Manually created sub-group of students of a class.assignmentStudentsSubGroup: Manually created Sub-group of students of a class, in relation to a specific assignment
flatapi: ScoreLicense
ScoreLicense
License of the creation. Read more about the Creative Commons licenses on https://creativecommons.org/licenses/
flatapi: TutteoProduct
TutteoProduct
A Tutteo product.
flat: Flat - Music notation software for individual usersflatEdu: Flat for Education - Music notation software for schools and educatorsmsnippet: Music Snippet - Embeddable music snippets for websitesembed: Flat Embed - Embeddable music notation editor
flatapi: ScoreTrackType
ScoreTrackType
The type of an audio track
flatapi: TeachingTheme
TeachingTheme
Teaching theme
flatapi: ClassGradeLevel
ClassGradeLevel
Class grade level
flatapi: AssignmentCopy
AssignmentCopy
flatapi: Grade
Grade
Class grade of the resource
flatapi: CollectionType
CollectionType
Type of the collection. The type will influence the capabilities available on the collections and how this collection is/can be populated.
root: Deprecated. Previously the root collection of the user. TheallScoresvirtual collection should be used instead.regular: A regular collection created by the user. This collection can be deleted and modified by the user.app: An automatically created collection containing the scores created by an app (e.g. Music Snippet)trash: An automatically created collection containing the trashed scores.
Virtual collections:
allScores: All the scores contained in the user accountcollaborations: All shared scores by the user or someone elselikes: Liked scores
flatapi: AppScopes
AppScopes
Available scopes
flatapi: LtiConfiguration1p3
LtiConfiguration1p3
LTI 1.3 configuration details
flatapi: AssignmentSubmissionHistoryState
AssignmentSubmissionHistoryState
State of the submission history
Array types
flatapi: CreditTransactionList
CreditTransactionList
Paginated list of credit transactions
flatapi: EduSkillsFocused
EduSkillsFocused
Specific skills that will be focused in classroom
flatapi: EduResourceGrades
EduResourceGrades
The grades of this resource, or the grades of the resources included in the folder
flatapi: ClassGroupIdsToApplyToAssignment
ClassGroupIdsToApplyToAssignment
Optional list of specific class group IDs to apply to the assignment. When transitioning to active state with group submission mode:
- If provided: Only these specific groups will be applied
- If not provided: All class groups will be applied, or randomized groups created if none exist
flatapi: EduResourceSubjects
EduResourceSubjects
The subjects of this resource, or the subjects of the resources included in the folder
String types
flatapi: ScoreDetailsTagsItemsString
ScoreDetailsTagsItemsString
flatapi: FlatLocalesString
FlatLocalesString
The user language. Input values will be automatically normalized to a supported locale code. Unknown locales will default to en.
Current supported locales include: da, de, en, en-GB, es, fi, fil, fr, fr-CA, hi, id, it, ja, ja-HIRA, ko, ms, nb, nl, pl, pt, pt-BR, ro, ru, sv, tr, zh-Hans, zh-HK, zh-TW
Simple name reference types
flatapi: OmrStepSubmission
OmrStepSubmission
Import
import ballerinax/flatapi;Metadata
Released date: 1 day ago
Version: 2.0.0
License: Apache-2.0
Security
Direct vulnerabilities: No known direct vulnerabilities
Indirect vulnerabilities:
Checked on 2026-11-20 via OSV.dev
Compatibility
Platform: any
Ballerina version: 2201.12.0
GraalVM compatible: Yes
Pull count
Total: 44
Current verison: 1
Weekly downloads
Keywords
Vendor/Flat
Area/Productivity & Collaboration
Type/Connector
Contributors