Ruby Client for the Flat REST API

Build Status Rubygems

The Flat API allows you to easily extend the abilities of the Flat Platform, with a wide range of use cases including the following:

  • Creating and importing new music scores using MusicXML or MIDI files
  • Browsing, updating, copying, exporting the user's scores (for example in MP3, WAV or MIDI)
  • Managing educational resources with Flat for Education: creating & updating the organization accounts, the classes, rosters and assignments.

You can find the API reference including code samples and our OpenAPI Specification at the following url:

To request some API credentials, please visit

This Ruby package is automatically generated by the Swagger Codegen project.


Build a gem

To build the Ruby code into a gem:

gem build flat_api.gemspec

Then either install the gem locally:

gem install ./flat_api-0.2.0.gem

(for development, run gem install --dev ./flat_api-0.2.0.gem to install the development dependencies)

or publish the gem to a gem hosting service, e.g. RubyGems.

Finally add this to the Gemfile:

gem 'flat_api', '~> 0.2.0'

Install from Git

If the Ruby gem is hosted at a git repository:, then add the following in the Gemfile:

gem 'flat_api', :git => ''

Include the Ruby code directly

Include the Ruby code directly using -I as follows:

ruby -Ilib script.rb

Getting Started

Please follow the installation procedure and then run the following code:

# Load the gem
require 'flat_api'

# Setup authorization
FlatApi.configure do |config|
  # Configure OAuth2 access token for authorization: OAuth2
  config.access_token = 'YOUR ACCESS TOKEN'

api_instance =

  #Get current user profile
  result = api_instance.get_authenticated_user
  p result
rescue FlatApi::ApiError => e
  puts "Exception when calling AccountApi->get_authenticated_user: #{e}"

Documentation for API Endpoints

All URIs are relative to

Class Method HTTP request Description
FlatApi::AccountApi get_authenticated_user GET /me Get current user profile
FlatApi::ClassApi activate_class POST /classes/class/activate Activate the class
FlatApi::ClassApi add_class_user PUT /classes/class/users/user Add a user to the class
FlatApi::ClassApi archive_class POST /classes/class/archive Archive the class
FlatApi::ClassApi copy_assignment POST /classes/class/assignments/assignment/copy Copy an assignment
FlatApi::ClassApi create_assignment POST /classes/class/assignments Assignment creation
FlatApi::ClassApi create_class POST /classes Create a new class
FlatApi::ClassApi create_submission PUT /classes/class/assignments/assignment/submissions Create or edit a submission
FlatApi::ClassApi delete_class_user DELETE /classes/class/users/user Remove a user from the class
FlatApi::ClassApi edit_submission PUT /classes/class/assignments/assignment/submissions/submission Edit a submission
FlatApi::ClassApi enroll_class POST /classes/enroll/enrollmentCode Join a class
FlatApi::ClassApi get_class GET /classes/class Get the details of a single class
FlatApi::ClassApi get_score_submissions GET /scores/score/submissions List submissions related to the score
FlatApi::ClassApi get_submission GET /classes/class/assignments/assignment/submissions/submission Get a student submission
FlatApi::ClassApi get_submissions GET /classes/class/assignments/assignment/submissions List the students' submissions
FlatApi::ClassApi list_assignments GET /classes/class/assignments Assignments listing
FlatApi::ClassApi list_class_student_submissions GET /classes/class/students/user/submissions List the submissions for a student
FlatApi::ClassApi list_classes GET /classes List the classes available for the current user
FlatApi::ClassApi unarchive_class DELETE /classes/class/archive Unarchive the class
FlatApi::ClassApi update_class PUT /classes/class Update the class
FlatApi::CollectionApi add_score_to_collection PUT /collections/collection/scores/score Add a score to the collection
FlatApi::CollectionApi create_collection POST /collections Create a new collection
FlatApi::CollectionApi delete_collection DELETE /collections/collection Delete the collection
FlatApi::CollectionApi delete_score_from_collection DELETE /collections/collection/scores/score Delete a score from the collection
FlatApi::CollectionApi edit_collection PUT /collections/collection Update a collection's metadata
FlatApi::CollectionApi get_collection GET /collections/collection Get collection details
FlatApi::CollectionApi list_collection_scores GET /collections/collection/scores List the scores contained in a collection
FlatApi::CollectionApi list_collections GET /collections List the collections
FlatApi::CollectionApi untrash_collection POST /collections/collection/untrash Untrash a collection
FlatApi::GroupApi get_group_details GET /groups/group Get group information
FlatApi::GroupApi get_group_scores GET /groups/group/scores List group's scores
FlatApi::GroupApi list_group_users GET /groups/group/users List group's users
FlatApi::OrganizationApi create_lti_credentials POST /organizations/lti/credentials Create a new couple of LTI 1.x credentials
FlatApi::OrganizationApi create_organization_invitation POST /organizations/invitations Create a new invitation to join the organization
FlatApi::OrganizationApi create_organization_user POST /organizations/users Create a new user account
FlatApi::OrganizationApi list_lti_credentials GET /organizations/lti/credentials List LTI 1.x credentials
FlatApi::OrganizationApi list_organization_invitations GET /organizations/invitations List the organization invitations
FlatApi::OrganizationApi list_organization_users GET /organizations/users List the organization users
FlatApi::OrganizationApi remove_organization_invitation DELETE /organizations/invitations/invitation Remove an organization invitation
FlatApi::OrganizationApi remove_organization_user DELETE /organizations/users/user Remove an account from Flat
FlatApi::OrganizationApi revoke_lti_credentials DELETE /organizations/lti/credentials/credentials Revoke LTI 1.x credentials
FlatApi::OrganizationApi update_organization_user PUT /organizations/users/user Update account information
FlatApi::ScoreApi add_score_collaborator POST /scores/score/collaborators Add a new collaborator
FlatApi::ScoreApi add_score_track POST /scores/score/tracks Add a new video or audio track to the score
FlatApi::ScoreApi create_score POST /scores Create a new score
FlatApi::ScoreApi create_score_revision POST /scores/score/revisions Create a new revision
FlatApi::ScoreApi delete_score DELETE /scores/score Delete a score
FlatApi::ScoreApi delete_score_comment DELETE /scores/score/comments/comment Delete a comment
FlatApi::ScoreApi delete_score_track DELETE /scores/score/tracks/track Remove an audio or video track linked to the score
FlatApi::ScoreApi edit_score PUT /scores/score Edit a score's metadata
FlatApi::ScoreApi fork_score POST /scores/score/fork Fork a score
FlatApi::ScoreApi ger_user_likes GET /users/user/likes List liked scores
FlatApi::ScoreApi get_group_scores GET /groups/group/scores List group's scores
FlatApi::ScoreApi get_score GET /scores/score Get a score's metadata
FlatApi::ScoreApi get_score_collaborator GET /scores/score/collaborators/collaborator Get a collaborator
FlatApi::ScoreApi get_score_collaborators GET /scores/score/collaborators List the collaborators
FlatApi::ScoreApi get_score_comments GET /scores/score/comments List comments
FlatApi::ScoreApi get_score_revision GET /scores/score/revisions/revision Get a score revision
FlatApi::ScoreApi get_score_revision_data GET /scores/score/revisions/revision/format Get a score revision data
FlatApi::ScoreApi get_score_revisions GET /scores/score/revisions List the revisions
FlatApi::ScoreApi get_score_submissions GET /scores/score/submissions List submissions related to the score
FlatApi::ScoreApi get_score_track GET /scores/score/tracks/track Retrieve the details of an audio or video track linked to a score
FlatApi::ScoreApi get_user_scores GET /users/user/scores List user's scores
FlatApi::ScoreApi list_score_tracks GET /scores/score/tracks List the audio or video tracks linked to a score
FlatApi::ScoreApi mark_score_comment_resolved PUT /scores/score/comments/comment/resolved Mark the comment as resolved
FlatApi::ScoreApi mark_score_comment_unresolved DELETE /scores/score/comments/comment/resolved Mark the comment as unresolved
FlatApi::ScoreApi post_score_comment POST /scores/score/comments Post a new comment
FlatApi::ScoreApi remove_score_collaborator DELETE /scores/score/collaborators/collaborator Delete a collaborator
FlatApi::ScoreApi untrash_score POST /scores/score/untrash Untrash a score
FlatApi::ScoreApi update_score_comment PUT /scores/score/comments/comment Update an existing comment
FlatApi::ScoreApi update_score_track PUT /scores/score/tracks/track Update an audio or video track linked to a score
FlatApi::UserApi ger_user_likes GET /users/user/likes List liked scores
FlatApi::UserApi get_user GET /users/user Get a public user profile
FlatApi::UserApi get_user_scores GET /users/user/scores List user's scores

Documentation for Models

Documentation for Authorization


  • Type: OAuth
  • Flow: accessCode
  • Authorization URL:
  • Scopes:
    • account.public_profile: Provides access to the basic person's public profile. Education profiles may be anonymized with this scope, you can request the scope `education_profile` to access to the a basic education account profile.
    • account.education_profile: Provides access to the basic person's education profile and public organization information.
    • scores.readonly: Allows read-only access to all a user's scores. You won't need this scope to read public scores.
    • Allow to post comments and like scores
    • scores: Full, permissive scope to access all of a user's scores.
    • collections.readonly: Allow read-only access to a user's collections.
    • collections.add_scores: Allow to add scores to a user's collections.
    • collections: Full, permissive scope to access all of a user's collections.
    • edu.classes: Full, permissive scope to manage the classes.
    • edu.classes.readonly: Read-only access to the classes.
    • edu.assignments: Read-write access to the assignments and submissions.
    • edu.assignments.readonly: Read-only access to the assignments and submissions.
    • edu.admin: Full, permissive scope to manage all the admin of an organization.
    • edu.admin.lti: Access and manage the LTI Credentials for an organization.
    • edu.admin.lti.readonly: Read-only access to the LTI Credentials of an organization.
    • edu.admin.users: Access and manage the users and invitations of the organization.
    • edu.admin.users.readonly: Read-only access to the users and invitations of the organization.