diff --git a/spec/openapi-flatten.yaml b/spec/openapi-flatten.yaml index e966890..f690dbd 100644 --- a/spec/openapi-flatten.yaml +++ b/spec/openapi-flatten.yaml @@ -5,7 +5,7 @@ # Some style notes: # - This file is used by ReDoc, which allows GitHub Flavored Markdown in descriptions. # - There is no maximum line length, for ease of editing and pretty diffs. -openapi: 3.0.2 +openapi: 3.0.3 info: title: Flat API description: | @@ -33,7 +33,7 @@ info: name: Flat url: https://flat.io/developers/docs/api/ email: developers@flat.io - version: 2.17.0 + version: 2.18.0 x-logo: url: https://prod.flat-cdn.com/img/logo-flat.svg servers: @@ -42,7 +42,7 @@ tags: - name: Account description: | These API endpoints are related to the Flat account you are currently using. When using an OAuth2 access token, you can use [`GET /me`](#operation/getAuthenticatedUser) to get information about the account. - x-displayName: Flat Account + x-displayName: Accounts - name: Score description: | Sheet music is the main API object type available for all Flat account. @@ -70,23 +70,32 @@ tags: At this time, only `private` privacy mode is widely available. Privacy modes `public`, `organizationPublic` and `privateLink`, and 1:1 sharing will be available in an upcoming update later this year. x-displayName: Collections of music scores - - name: User - description: Flat users + x-displayName: Users profiles + description: API methods related to the Flat Community user profiles and Flat for Education profiles - name: Organization - description: Flat for Education organizations + x-displayName: Flat for Education Organizations + description: Flat for Education Organizations - name: Class - description: Flat for Education classes + x-displayName: Flat for Education Classes + description: Flat for Education Classes +- name: EduResources + x-displayName: Flat for Education Resources [Beta] + description: | + Resource libraries in Flat for Education. + These API endpoints are in beta and may include breaking changes over the upcoming months. - name: Group - description: Flat Groups + x-displayName: Flat for Education Groups + description: Flat for Education Groups - name: Task - description: Scheduled tasks + x-displayName: Asynchronous tasks + description: Scheduled and asynchronous tasks paths: /me: get: tags: - Account - summary: Get current user profile + summary: Get current user account description: | Get details about the current authenticated User. operationId: getAuthenticatedUser @@ -414,7 +423,6 @@ paths: post: tags: - Score - - Class summary: Fork a score description: | This API call will make a copy of the last revision of the specified score and create a new score. The copy of the score will have a privacy set to `private`. @@ -1233,7 +1241,6 @@ paths: - OAuth2: - scores.social - scores - /scores/{score}/revisions: parameters: - name: score @@ -2451,14 +2458,14 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/OrganizationUserSigninLinkCreation' + $ref: '#/components/schemas/UserSigninLinkCreation' responses: 200: description: Sign in link content: application/json: schema: - $ref: '#/components/schemas/OrganizationUserSigninLink' + $ref: '#/components/schemas/UserSigninLink' default: description: Error content: @@ -3050,7 +3057,7 @@ paths: schema: type: array items: - $ref: '#/components/schemas/Assignment' + $ref: '#/components/schemas/ClassAssignment' default: description: Error content: @@ -3071,12 +3078,12 @@ paths: Use this method as a teacher to create and post a new assignment to a class. If the class is synchronized with Google Classroom, the assignment will be automatically posted to your Classroom course. - operationId: createAssignment + operationId: createClassAssignment requestBody: content: application/json: schema: - $ref: '#/components/schemas/AssignmentCreation' + $ref: '#/components/schemas/ClassAssignmentUpdate' required: false responses: 200: @@ -3105,11 +3112,11 @@ paths: - Class summary: Copy an assignment description: | - Copy an assignment to a specified class. + Copy an assignment to a specified class or the resource library - If the original assignment has a due date in the past, this new assingment will be created without a due date. - - If the new class is synchronized with an external app (e.g. Google Classroom), the copied assignment will also be posted on the external app. + For class assignments: + - If the original assignment has a due date in the past, this new assignment will be created without a due date. + - If the class is synchronized with an external app (e.g. Google Classroom), the copied assignment will also be posted on the external app. operationId: copyAssignment requestBody: content: @@ -3119,11 +3126,11 @@ paths: required: true responses: 200: - description: The new created assingment + description: The new created assignment content: application/json: schema: - $ref: '#/components/schemas/Assignment' + $ref: '#/components/schemas/AssignmentCopyResponse' default: description: Error content: @@ -3374,17 +3381,21 @@ paths: delete: tags: - Class - summary: Delete a submission + summary: Reset a submission description: | - Use this method as a teacher to delete a submission and allow student to start over the assignment + Use this method as a teacher to reset a submission and allow student to start over the assignment operationId: deleteSubmission parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' - $ref: '#/components/parameters/submission' responses: - 204: - description: The submission has been deleted + 200: + description: The submission object once reset + content: + application/json: + schema: + $ref: '#/components/schemas/AssignmentSubmission' default: description: Error content: @@ -3581,6 +3592,45 @@ paths: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' + /classes/{class}/testStudent: + parameters: + - $ref: '#/components/parameters/class' + post: + tags: + - Class + summary: Create a test student account + description: | + Test students account can be created by teachers an admin and be used to experiment the assignments. + + - They are automatically added to the class. + - They can be reset using this API endpoint (a new account will be created and the previous one scheduled for deletion). + - These accounts don't use a user license. + operationId: createTestStudentAccount + parameters: + - name: reset + in: query + description: | + If true, the testing account will be re-created. + required: false + schema: + type: boolean + responses: + 200: + description: Test account created + content: + application/json: + schema: + $ref: '#/components/schemas/UserDetails' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.admin + - edu.classes /classes/enroll/{enrollmentCode}: parameters: - name: enrollmentCode @@ -3717,229 +3767,665 @@ paths: - OAuth2: - scores - scores.readonly -components: - securitySchemes: - OAuth2: - type: oauth2 - description: | - OAuth 2.0 authentication for your app or. Please only request the most restrictive and needed scopes. Using some of the scopes may require an additional review from our team. The Flat API supports **authorization code** and **implicit** flows. - flows: - authorizationCode: - authorizationUrl: https://flat.io/auth/oauth - tokenUrl: https://api.flat.io/oauth/access_token - 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.email: | - Provices access to the person's email. - 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. - scores.social: | - 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. - tasks.readonly: Read-only access to export tasks created by this account. - schemas: - FlatLocales: - type: string - description: The user language - default: en - enum: - - en - - en-GB - - es - - fr - - de - - it - - ja - - ja-HIRA - - ko - - nl - - pl - - pt - - pt-BR - - ro - - ru - - sv - - tr - - zh-Hans - OrganizationRoles: - type: string - description: User's Organization Role (for Edu users only) - enum: - - admin - - billing - - teacher - - user - ClassRoles: - type: string - description: User's Class Role (for Edu users only) - enum: - - teacher - - student - LicenseMode: - type: string - description: Mode of the license - enum: - - credit - - site - LicenseSources: - type: string - description: Source of the license - default: order - enum: - - order - - trial - - voucher - - distributor - - subscription - - appStore - UserPublicSummary: - type: object - properties: - username: - type: string - description: The user name (unique for the organization) - picture: - type: string - nullable: true - description: The URL of the picture to display - name: - type: string - description: A displayable name for the user (for consumer users) - firstname: - type: string - description: Firstname of the user (for education users) - isPowerUser: - type: boolean - description: User license status. 'true' if user is an individual Power user - isFlatTeam: - type: boolean - description: Will be 'true' if user is part of the Flat Team - lastname: - type: string - description: Lastname of the user (for education users) - htmlUrl: - type: string - description: Link to user profile (for Indiv. users only) - printableName: - type: string - description: The name that can be directly printed (name, firstname & lastname, or username) - organizationRole: - $ref: '#/components/schemas/OrganizationRoles' - classRole: - $ref: '#/components/schemas/ClassRoles' - organization: - type: string - description: Organization ID (for Edu users only) - type: - type: string - description: The type of user account - enum: [user, guest] - id: - type: string - description: The user unique identifier - UserPublic: - type: object - properties: - username: - type: string - description: The user name (unique for the organization) - picture: - type: string - nullable: true - description: The URL of the picture to display - followersCount: - type: integer - description: Number of followers the user have - firstname: - type: string - description: Firstname of the user (for education users) - isPowerUser: - type: boolean - description: User license status. 'true' if user is an individual Power user - lastname: - type: string - description: Lastname of the user (for education users) - htmlUrl: - type: string - description: Link to user profile (for Indiv. users only) - followingCount: - type: integer - description: Number of people the user follow - likedScoresCount: - type: integer - description: Number of the scores liked by the user - printableName: - type: string - description: The name that can be directly printed (name, firstname & lastname, or username) - bio: - type: string - description: User's biography - id: - type: string - description: The user unique identifier - name: + /eduResources: + get: + tags: + - EduResources + operationId: listEduResources + summary: List education resources in a library or folder + parameters: + - name: parent + in: query + description: | + List the resources contained in this `parent` library or folder + schema: type: string - description: A displayable name for the user (for consumer users) - isFlatTeam: - type: boolean - description: Will be 'true' if user is part of the Flat Team - organizationRole: - $ref: '#/components/schemas/OrganizationRoles' - profileTheme: + default: root + - name: type + in: query + description: | + Filter the returned resources by type + schema: type: string - description: Theme (background) for the profile - coverPicture: + enum: + - assignment + - folder + - name: sort + in: query + description: Sort + schema: type: string - description: Cover picture (backgroud) for the profile - ownedPublicScoresCount: + enum: + - creationDate + - updateDate + - title + default: creationDate + - $ref: '#/components/parameters/sortDirection' + - name: limit + in: query + description: This is the maximum number of resources that may be returned + schema: + maximum: 100 + minimum: 1 type: integer - description: Number of public scores the user have - instruments: - type: array - description: | - An array of the instrument identifiers. - The format of the strings is `{instrument-group}.{instrument-id}`. - items: - type: string - classRole: - $ref: '#/components/schemas/ClassRoles' + default: 25 + - $ref: '#/components/parameters/next' + - $ref: '#/components/parameters/previous' + responses: + 200: + description: List of resources + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.resources.readonly + - edu.assignments + - edu.assignments.readonly + post: + tags: + - EduResources + operationId: createEduResource + summary: Create a new education resource + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EduResourceCreation' + required: true + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/libraries: + get: + tags: + - EduResources + operationId: listEduLibraries + summary: List the education libraries + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + type: array + description: List of libraries to display + items: + $ref: '#/components/schemas/EduLibrary' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.resources.readonly + - edu.assignments + - edu.assignments.readonly + /eduResources/{resource}: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + get: + tags: + - EduResources + operationId: getEduResource + summary: Get an education resource + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.resources.readonly + - edu.assignments + - edu.assignments.readonly + put: + tags: + - EduResources + operationId: updateEduResource + summary: Update an education resource metadata + description: | + Update any resources metadata (e.g. title). + + Use this method to rename education resources folders or assignments. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EduResourceUpdate' + required: true + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + delete: + tags: + - EduResources + operationId: deleteEduResource + summary: Delete an education resource + responses: + 204: + description: Resource deleted + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/{resource}/move: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + post: + tags: + - EduResources + operationId: moveEduResource + summary: Move an education resource + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EduResourceMove' + required: true + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/{resource}/copy: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + post: + tags: + - EduResources + operationId: copyEduResource + summary: Copy an education resource to a Resource Library + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EduResourceCopy' + required: true + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/{resource}/copyToDemoClass: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + post: + tags: + - EduResources + operationId: copyEduResourceToDemoClass + summary: Copy an education assignment to a teacher demo class + description: | + Once a resource library can be published to a class (`Assignment.capabilities.canPublishInClass = true`), + this endpoint can be used for the feature "View as student". + + It will ensure the teacher has a demo class, then copy the assignment to the demo class. + You can then use `POST /classes/{class}/testStudent` to create a testing student account + in the demo class. + responses: + 200: + description: Assignment copied to the demo class + content: + application/json: + schema: + $ref: '#/components/schemas/ClassAssignment' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/{resource}/useInClass: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + post: + tags: + - EduResources + operationId: useEduResourceInClass + summary: Use an education resource in a class + description: | + This endpoint will copy a resource and the underlying resources. + The assignment will be created as a draft that can be completed with other options before publishing (e.g. due date, publication date for scheduling, etc.). + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EduResourceUseInClass' + required: true + responses: + 200: + description: Assignment copied to the chosen class + content: + application/json: + schema: + $ref: '#/components/schemas/ClassAssignment' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/{resource}/assignment: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + put: + tags: + - EduResources + operationId: updateEduResourceAssignment + summary: Update an education resource assignment + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AssignmentUpdate' + required: true + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/Assignment' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments +components: + securitySchemes: + OAuth2: + type: oauth2 + description: | + OAuth 2.0 authentication for your app or. Please only request the most restrictive and needed scopes. Using some of the scopes may require an additional review from our team. The Flat API supports **authorization code** and **implicit** flows. + flows: + authorizationCode: + authorizationUrl: https://flat.io/auth/oauth + tokenUrl: https://api.flat.io/oauth/access_token + 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.email: | + Provices access to the person's email. + 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. + scores.social: | + 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.resources: Read-write access to the resource library. + edu.resources.readonly: Read-only access to the resource library. + 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. + tasks.readonly: Read-only access to export tasks created by this account. + schemas: + FlatLocales: + type: string + description: The user language + default: en + enum: + - en + - en-GB + - es + - fr + - de + - it + - ja + - ja-HIRA + - ko + - nl + - pl + - pt + - pt-BR + - ro + - ru + - sv + - tr + - zh-Hans + OrganizationRoles: + type: string + description: User's Organization Role (for Edu users only) + enum: + - admin + - billing + - teacher + - user + ClassRoles: + type: string + description: User's Class Role (for Edu users only) + enum: + - teacher + - student + LicenseMode: + type: string + description: Mode of the license + enum: + - credit + - site + LicenseSources: + type: string + description: Source of the license + default: order + enum: + - order + - trial + - voucher + - distributor + - subscription + - appStore + - playStore + - musicfirst + UserPublicSummary: + type: object + properties: + id: + type: string + description: The user unique identifier + type: + type: string + description: The type of user account + enum: [user, guest] + username: + type: string + description: The user name (unique for the organization) + printableName: + type: string + description: The name that can be directly printed (name, firstname & lastname, or username) + firstname: + type: string + description: Firstname of the user (for education users) + lastname: + type: string + description: Lastname of the user (for education users) + name: + type: string + description: A displayable name for the user (for consumer users) + picture: + type: string + nullable: true + description: The URL of the picture to display + badges: + type: array + description: List of badges for the user profile + items: + type: string + description: Badge name, e.g. `power`, `staff`, `composerOfTheMonth` organization: type: string description: Organization ID (for Edu users only) + organizationRole: + $ref: '#/components/schemas/OrganizationRoles' + classRole: + $ref: '#/components/schemas/ClassRoles' + htmlUrl: + type: string + description: Link to user profile (for Indiv. users only) + UserPublic: + type: object + properties: + id: + type: string + description: The user unique identifier type: type: string description: The type of user account enum: [user, guest] + username: + type: string + description: The user name (unique for the organization) + printableName: + type: string + description: The name that can be directly printed (name, firstname & lastname, or username) + firstname: + type: string + description: Firstname of the user (for education users) + lastname: + type: string + description: Lastname of the user (for education users) + name: + type: string + description: A displayable name for the user (for consumer users) + picture: + type: string + nullable: true + description: The URL of the picture to display + badges: + type: array + description: List of badges for the user profile + items: + type: string + description: Badge name, e.g. `power`, `staff`, `composerOfTheMonth` + organization: + type: string + description: Organization ID (for Edu users only) + organizationRole: + $ref: '#/components/schemas/OrganizationRoles' + classRole: + $ref: '#/components/schemas/ClassRoles' + htmlUrl: + type: string + description: Link to user profile (for Indiv. users only) + bio: + type: string + description: User's biography registrationDate: type: string description: Date the user signed up format: date-time + likedScoresCount: + type: integer + description: Number of the scores liked by the user + followersCount: + type: integer + description: Number of followers the user have + followingCount: + type: integer + description: Number of people the user follow + ownedPublicScoresCount: + type: integer + description: Number of public scores the user have + coverPicture: + type: string + description: Cover picture (backgroud) for the profile + profileTheme: + type: string + description: Theme (background) for the profile + instruments: + type: array + description: | + An array of the instrument identifiers. + The format of the strings is `{instrument-group}.{instrument-id}`. + items: + type: string + links: + $ref: '#/components/schemas/UserCommunityProfileLinks' UserDetailsAdmin: type: object properties: + id: + type: string + description: The user unique identifier + type: + type: string + description: The type of user account + enum: [user, guest] username: type: string description: The user name (unique for the organization) + printableName: + type: string + description: The name that can be directly printed (name, firstname & lastname, or username) + firstname: + type: string + description: Firstname of the user (for education users) + lastname: + type: string + description: Lastname of the user (for education users) + name: + type: string + description: A displayable name for the user (for consumer users) picture: type: string nullable: true description: The URL of the picture to display + badges: + type: array + description: List of badges for the user profile + items: + type: string + description: Badge name, e.g. `power`, `staff`, `composerOfTheMonth` + organization: + type: string + description: Organization ID (for Edu users only) + organizationRole: + $ref: '#/components/schemas/OrganizationRoles' + classRole: + $ref: '#/components/schemas/ClassRoles' + htmlUrl: + type: string + description: Link to user profile (for Indiv. users only) + email: + type: string + description: Email of the user + format: email + lastActivityDate: + type: string + description: Date of the last user activity + format: date-time license: type: object properties: @@ -3958,49 +4444,12 @@ components: type: boolean description: ID of the current license description: Current active license of the user - name: - type: string - description: A displayable name for the user (for consumer users) - firstname: - type: string - description: Firstname of the user (for education users) - isPowerUser: - type: boolean - description: User license status. 'true' if user is an individual Power user - isFlatTeam: - type: boolean - description: Will be 'true' if user is part of the Flat Team - lastname: - type: string - description: Lastname of the user (for education users) - lastActivityDate: - type: string - description: Date of the last user activity - format: date-time - htmlUrl: - type: string - description: Link to user profile (for Indiv. users only) - email: - type: string - description: Email of the user - format: email - printableName: - type: string - description: The name that can be directly printed (name, firstname & lastname, or username) - organizationRole: - $ref: '#/components/schemas/OrganizationRoles' - classRole: - $ref: '#/components/schemas/ClassRoles' - organization: - type: string - description: Organization ID (for Edu users only) - type: - type: string - description: The type of user account - enum: [user, guest] - id: - type: string - description: The user unique identifier + groups: + description: For Flat for Education accounts, list of Group identifiers the user is part of. + type: array + items: + type: string + description: Unique group identifier UserCreation: required: - password @@ -4072,99 +4521,121 @@ components: description: Email of the account format: email description: User update as an organization admin + UserAzureDetails: + type: object + properties: + oid: + type: string + description: User object identifier on Azure AD + hd: + type: string + description: User tenant (domain name) + preferredUsername: + type: string + description: User Preferred Username (UPN), i.e. the main email of the user UserDetails: type: object properties: - username: + id: type: string - description: The user name (unique for the organization) - classRole: - $ref: '#/components/schemas/ClassRoles' - privateProfile: - type: boolean - description: Tell either this user profile is private or not (individual accounts only) - followersCount: - type: integer - description: Number of followers the user have - firstname: + description: Identifier of the user + type: type: string - description: Firstname of the user (for education users) - isPowerUser: - type: boolean - description: User license status. 'true' if user is an individual Power user - locale: - $ref: '#/components/schemas/FlatLocales' - instruments: - type: array - description: | - An array of the instrument identifiers. - The format of the strings is `{instrument-group}.{instrument-id}`. - items: - type: string - htmlUrl: + description: The type of account + enum: + - user + - guest + username: type: string - description: Link to user profile (for Indiv. users only) - likedScoresCount: - type: integer - description: Number of the scores liked by the user + description: The user name (unique for the organization) printableName: type: string description: The name that can be directly printed (name, firstname & lastname, or username) - bio: - type: string - description: User's biography - pictureFile: + firstname: type: string - nullable: true - description: The ID of the user profile picture - id: + description: Firstname of the user (for education users) + lastname: type: string - description: Identifier of the user - coverPictureFile: + description: Lastname of the user (for education users) + name: type: string - nullable: true - description: The ID of the user profile cover picture + description: A displayable name for the user (for consumer users) picture: type: string nullable: true description: The URL of the picture to display - name: + badges: + type: array + description: List of badges for the user profile + items: + type: string + description: Badge name, e.g. `power`, `staff`, `composerOfTheMonth` + organization: type: string - description: A displayable name for the user (for consumer users) - isFlatTeam: - type: boolean - description: Will be 'true' if user is part of the Flat Team + description: Organization ID (for Edu users only) organizationRole: $ref: '#/components/schemas/OrganizationRoles' - profileTheme: + classRole: + $ref: '#/components/schemas/ClassRoles' + htmlUrl: type: string - description: Theme (background) for the profile - coverPicture: + description: Link to user profile (for Indiv. users only) + bio: type: string - description: Cover picture (backgroud) for the profile - ownedPublicScoresCount: - type: integer - description: Number of public scores the user have - lastname: + description: User's biography + registrationDate: type: string - description: Lastname of the user (for education users) + description: Date the user signed up + format: date-time + likedScoresCount: + type: integer + description: Number of the scores liked by the user + followersCount: + type: integer + description: Number of followers the user have followingCount: type: integer description: Number of people the user follow - organization: + ownedPublicScoresCount: + type: integer + description: Number of public scores the user have + coverPicture: type: string - description: Organization ID (for Edu users only) - type: + description: Cover picture (backgroud) for the profile + profileTheme: type: string - description: The type of account - enum: - - user - - guest - registrationDate: + description: Theme (background) for the profile + instruments: + type: array + description: | + An array of the instrument identifiers. + The format of the strings is `{instrument-group}.{instrument-id}`. + items: + type: string + links: + $ref: '#/components/schemas/UserCommunityProfileLinks' + azureDetails: + $ref: '#/components/schemas/UserAzureDetails' + privateProfile: + type: boolean + description: Tell either this user profile is private or not (individual accounts only) + locale: + $ref: '#/components/schemas/FlatLocales' + groups: + description: For Flat for Education accounts, list of Group identifiers the user is part of. + type: array + items: + type: string + description: Unique group identifier + pictureFile: type: string - description: Date the user signed up - format: date-time - OrganizationUserSigninLinkCreation: + nullable: true + description: The ID of the user profile picture + coverPictureFile: + type: string + nullable: true + description: The ID of the user profile cover picture + UserSigninLinkCreation: type: object properties: destinationPath: @@ -4173,7 +4644,7 @@ components: default: / example: destinationPath: /class - OrganizationUserSigninLink: + UserSigninLink: type: object properties: url: @@ -4269,20 +4740,11 @@ components: ResourceCollaborator: type: object properties: - aclAdmin: - type: boolean - description: | - `True` if 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 the `capabilities` property as the end-user to have the complete possibilities with the collection. - default: false - isCollaborator: + aclRead: type: boolean description: | - `True` if the current user is a collaborator of the current document (direct or via group). + `True` if the current user can read the current document default: false - group: - $ref: '#/components/schemas/Group' aclWrite: type: boolean description: | @@ -4290,30 +4752,39 @@ components: If this is a right of a Collection, the capabilities of the associated user can be lower than this permission, check out the `capabilities` property as the end-user to have the complete possibilities with the collection. default: false - invited: + aclAdmin: type: boolean description: | - If this property is `true`, this is still a pending invitation - userEmail: - type: string + `True` if 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 the `capabilities` property as the end-user to have the complete possibilities with the collection. + default: false + isCollaborator: + type: boolean description: | - If the collaborator is not a user of Flat yet, this field will contain his email. - collection: + `True` if the current user is a collaborator of the current document (direct or via group). + default: false + id: type: string - description: If this object is a permission of a collection, this property will contain the unique identifier of the collection + description: The unique identifier of the permission score: type: string description: If this object is a permission of a score, this property will contain the unique identifier of the score + collection: + type: string + description: If this object is a permission of a collection, this property will contain the unique identifier of the collection user: $ref: '#/components/schemas/UserPublic' - id: + group: + $ref: '#/components/schemas/Group' + userEmail: type: string - description: The unique identifier of the permission - aclRead: + description: | + If the collaborator is not a user of Flat yet, this field will contain their email. + invited: type: boolean description: | - `True` if the current user can read the current document - default: false + If this property is `true`, this is still a pending invitation ResourceCollaboratorCreation: type: object properties: @@ -4375,117 +4846,117 @@ components: ScoreDetails: type: object properties: + id: + type: string + description: The unique identifier of the score + sharingKey: + type: string + description: The private sharing key of the score (available when the `privacy` mode is set to `privateLink`) + title: + type: string + description: The title of the score + privacy: + $ref: '#/components/schemas/ScorePrivacy' + user: + $ref: '#/components/schemas/UserPublicSummary' + htmlUrl: + type: string + description: The url where the score can be viewed in a web browser + format: url subtitle: type: string description: Subtitle of the score - instruments: - type: array - description: | - 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 the Flat's UI or instruments icons. The format of the strings is `{instrument-group}.{instrument-id}`. - items: - type: string lyricist: type: string description: Lyricist of the score - publicationDate: + arranger: type: string - description: The date when the score was published on Flat - format: date-time + description: Arranger of the score composer: type: string description: Composer of the score - licenseText: - type: string - description: Additional license text written on the exported/printed score - modificationDate: - type: string - description: The date of the last revision of the score - format: date-time - id: - type: string - description: The unique identifier of the score - plays: - $ref: '#/components/schemas/ScorePlaysCounts' - title: + description: type: string - description: The title of the score - creationType: - $ref: '#/components/schemas/ScoreCreationType' - comments: - $ref: '#/components/schemas/ScoreCommentsCounts' - collections: - type: array - description: The List of parent collections, which includes all the collections this score is included. Please note that you might not have access to all of them. - items: - type: string - samples: + description: Description of the creation + tags: type: array - description: | - An array of the audio samples identifiers used the different score parts. - The format of the strings is `{instrument-group}.{sample-id}`. + description: Tags describing the score items: + pattern: ^[a-zA-Z0-9]{1,30}$ type: string - numberMeasures: - type: integer - description: The number of measures in the score - googleDriveFileId: - type: string - description: | - 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}` - description: - type: string - description: Description of the creation - views: - $ref: '#/components/schemas/ScoreViewsCounts' - htmlUrl: + creationType: + $ref: '#/components/schemas/ScoreCreationType' + license: + $ref: '#/components/schemas/ScoreLicense' + licenseText: type: string - description: The url where the score can be viewed in a web browser - format: url + description: Additional license text written on the exported/printed score durationTime: type: number description: In seconds, an approximative duration of the score - user: - $ref: '#/components/schemas/UserPublicSummary' + numberMeasures: + type: integer + description: The number of measures in the score mainTempoQpm: type: number description: The main tempo of the score (in QPM) + rights: + $ref: '#/components/schemas/ResourceRights' + collaborators: + type: array + description: The list of the collaborators of the score + items: + $ref: '#/components/schemas/ResourceCollaborator' creationDate: type: string description: The date when the score was created format: date-time + modificationDate: + type: string + description: The date of the last revision of the score + format: date-time + publicationDate: + type: string + description: The date when the score was published on Flat + format: date-time + organization: + type: string + description: | + If the score has been created in an organization, the identifier of this organization. This property is especially used with the score privacy `organizationPublic`. parentScore: type: string description: | If the score has been forked, the unique identifier of the parent score. - tags: + instruments: type: array - description: Tags describing the score + description: | + 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 the Flat's UI or instruments icons. The format of the strings is `{instrument-group}.{instrument-id}`. items: - pattern: ^[a-zA-Z0-9]{1,30}$ type: string - collaborators: + samples: type: array - description: The list of the collaborators of the score + description: | + An array of the audio samples identifiers used the different score parts. + The format of the strings is `{instrument-group}.{sample-id}`. items: - $ref: '#/components/schemas/ResourceCollaborator' - sharingKey: - type: string - description: The private sharing key of the score (available when the `privacy` mode is set to `privateLink`) - license: - $ref: '#/components/schemas/ScoreLicense' - rights: - $ref: '#/components/schemas/ResourceRights' - privacy: - $ref: '#/components/schemas/ScorePrivacy' - arranger: - type: string - description: Arranger of the score - organization: + type: string + googleDriveFileId: type: string description: | - If the score has been created in an organization, the identifier of this organization. This property is especially used with the score privacy `organizationPublic`. + 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}` likes: $ref: '#/components/schemas/ScoreLikesCounts' + comments: + $ref: '#/components/schemas/ScoreCommentsCounts' + views: + $ref: '#/components/schemas/ScoreViewsCounts' + plays: + $ref: '#/components/schemas/ScorePlaysCounts' + collections: + type: array + description: The List of parent collections, which includes all the collections this score is included. Please note that you might not have access to all of them. + items: + type: string ScorePrivacy: type: string default: private @@ -4756,6 +5227,14 @@ components: deletions: type: number description: The number of deletions operations in the last revision + startDate: + type: string + format: date-time + description: The date of the first action included in this revision + endDate: + type: string + format: date-time + description: The date of the latest action included in this revision description: | The statistics related to the score revision (additions and deletions) example: @@ -4773,11 +5252,6 @@ components: ScoreCreation: type: object properties: - dataEncoding: - type: string - description: The optional encoding of the score data. This property must match the encoding used for the `data` property. - enum: - - base64 title: type: string description: | @@ -4789,6 +5263,15 @@ components: - Set a default title (e.g. "New Music Score") privacy: $ref: '#/components/schemas/ScorePrivacy' + collection: + type: string + description: | + Unique identifier of a collection where the score will be created. + If no collection identifier is provided, the score will be stored in the `root` directory. + googleDriveFolder: + type: string + description: | + If the user uses Google Drive and this properties is specified, the file will be created in this directory. The currently user creating the file must be granted to write in this directory. builderData: type: object required: @@ -4837,6 +5320,9 @@ components: shortName: type: string description: The abbreviation of the name of the instrument + hasQuarterTone: + type: boolean + description: True if the part can use quarter tone (prevent the part to have a TAB/chord grid) layoutData: type: object description: Control the appearance of the score. If missing, default values are used. @@ -4872,31 +5358,33 @@ components: filename: type: string description: If this is an imported file, its filename - source: - $ref: '#/components/schemas/ScoreSource' - collection: - type: string - description: | - Unique identifier of a collection where the score will be created. - If no collection identifier is provided, the score will be stored in the `root` directory. data: type: string description: | The data of the score file. It must be a MusicXML 3 file (`vnd.recordare.musicxml` or `vnd.recordare.musicxml+xml`), a MIDI file (`audio/midi`) or a Flat.json (aka Adagio.json) file. Binary payloads (`vnd.recordare.musicxml` and `audio/midi`) can be encoded in Base64, in this case the `dataEncoding` property must match the encoding used for the API request. - googleDriveFolder: + dataEncoding: type: string - description: | - If the user uses Google Drive and this properties is specified, the file will be created in this directory. The currently user creating the file must be granted to write in this directory. + description: The optional encoding of the score data. This property must match the encoding used for the `data` property. + enum: + - base64 + source: + $ref: '#/components/schemas/ScoreSource' ScoreFork: type: object properties: collection: type: string default: root + nullable: true description: | Unique identifier of a collection where the score will be copied. If no collection identifier is provided, the score will be stored in the `root` directory. + If null is provided, the score won't be added to any collections + keepOriginalTitle: + type: boolean + description: | + 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). description: Options to fork the score ScoreModification: type: object @@ -5407,6 +5895,8 @@ components: - collections.readonly - collections.add_scores - collections + - edu.resources + - edu.resources.readonly - edu.classes - edu.classes.readonly - edu.assignments @@ -5597,6 +6087,15 @@ components: maxLength: 255 type: string description: The section of the new class + level: + $ref: '#/components/schemas/ClassGradeLevel' + skillsFocused: + $ref: '#/components/schemas/EduSkillsFocused' + size: + type: number + minimum: 0 + nullable: true + description: Number of students in the classroom description: Creation of a classroom example: name: Music Theory Course @@ -5612,6 +6111,15 @@ components: maxLength: 255 type: string description: The section of the class + level: + $ref: '#/components/schemas/ClassGradeLevel' + skillsFocused: + $ref: '#/components/schemas/EduSkillsFocused' + size: + type: number + minimum: 0 + nullable: true + description: Number of students in the classroom description: Update of a classroom example: name: Music Theory Course @@ -5780,6 +6288,14 @@ components: description: End date of the term format: date-time description: Clever.com section-related information + level: + $ref: '#/components/schemas/ClassGradeLevel' + skillsFocused: + $ref: '#/components/schemas/EduSkillsFocused' + size: + type: number + nullable: true + description: Number of students in the classroom description: A classroom example: id: '100000000000000000000001' @@ -5811,52 +6327,142 @@ components: properties: type: type: string - description: The type of the attachment posted + description: | + The type of the attachment posted: + * `rich`, `photo`, `video` are attachment types that are automatically resolved from a `link` attachment. + * A `flat` attachment is a score document where the unique identifier will be specified in the `score` property. Its sharing mode will be provided in the `sharingMode` property. enum: - - flat + - rich + - photo + - video - link + - flat - googleDrive - worksheet + - performance score: type: string description: | - 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. - worksheet: + 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. + worksheet: + type: string + description: An unique worksheet identifier + sharingMode: + $ref: '#/components/schemas/MediaScoreSharingMode' + lockScoreTemplate: + type: boolean + description: To be used with a score attached in `sharingMode` `copy` (score used as template). If true, students won't be able to change the original notes of the template. + url: + type: string + description: The URL of the attachment. + googleDriveFileId: + type: string + description: The ID of the Google Drive File + description: | + Attachment creation for an assignment or stream post. + This attachment must contain a `score` or an `url`, all the details of this one will be resolved and returned as `ClassAttachment` once the assignment or stream post is created. + example: + type: flat + score: '000000000000000001' + sharingMode: copy + ClassGradeLevel: + type: string + description: Class grade level + enum: + - elementary + - middle + - high + - university + - other + EduSkillsFocused: + type: array + description: Specific skills that will be focused in classroom + items: + type: string + enum: + - notation + - sight-reading + - performance-instrumental + - ear-training + - music-theory + - composition + - jazz-ensemble + - music-technology + - other + AssignmentUpdate: + type: object + description: Assignment Resource Editing + properties: + type: + $ref: '#/components/schemas/AssignmentType' + title: + type: string + description: Title of the assignment + maxLength: 1000 + minLength: 1 + description: + type: string + description: Description and content of the assignment + attachments: + type: array + items: + $ref: '#/components/schemas/ClassAttachmentCreation' + nbPlaybackAuthorized: + type: number + nullable: true + description: The number of playback authorized on the scores of the assignment. + toolset: + type: string + nullable: true + description: | + The id of the toolset to apply to this assignment. + The toolset will be copied to the assignment as a dedicated object to prevent unexpected changes when making modifications to the template toolset. + This property can be set to null to delete the linked toolset and switch back to all the tools available for this assignment. + coverFile: + type: string + nullable: true + description: The id of the cover to display + cover: + type: string + nullable: true + description: The URL of the cover to display + maxPoints: + type: number + nullable: true + minimum: 0 + maximum: 100 + description: | + If set, the grading will be enabled for the assignement with this value as the maximum of points + releaseGrades: type: string - description: An unique worksheet identifier - sharingMode: - $ref: '#/components/schemas/MediaScoreSharingMode' - lockScoreTemplate: + enum: [auto, manual] + description: | + For worksheets, how grading will work for the assignment: + - If set to `auto`, the grades will be automatically released when the student submits the submissions + - If set to `manual`, the grades will only be set as `draftGrade` and will be released when the teacher returns the submissions + shuffleExercises: type: boolean - description: To be used with a score attached in `sharingMode` `copy` (score used as template). If true, students won't be able to change the original notes of the template. - url: - type: string - description: The URL of the attachment. - googleDriveFileId: - type: string - description: The ID of the Google Drive File - description: | - Attachment creation for an assignment or stream post. - This attachment must contain a `score` or an `url`, all the details of this one will be resolved and returned as `ClassAttachment` once the assignment or stream post is created. + description: Mixing worksheets exercises for each student example: - type: flat - score: '000000000000000001' - sharingMode: copy - AssignmentCreation: + title: First assignment + description: Get started with Flat + maxPoints: 100 + attachments: + - type: flat + score: '0000000000000000' + - type: link + url: https://flat.io/developers + ClassAssignmentUpdate: type: object properties: type: $ref: '#/components/schemas/AssignmentType' - state: - type: string - description: State of the assignment - enum: - - draft - - active title: type: string description: Title of the assignment + maxLength: 1000 + minLength: 1 description: type: string description: Description and content of the assignment @@ -5864,19 +6470,6 @@ components: type: array items: $ref: '#/components/schemas/ClassAttachmentCreation' - dueDate: - type: string - nullable: true - description: | - The due date of this assignment, late submissions will be marked as paste due. If not set, the assignment won't have a due date. - format: date-time - scheduledDate: - type: string - nullable: true - description: | - The publication (scheduled) date of the assignment. - If this one is specified, the assignment will only be listed to the teachers of the class. - format: date-time nbPlaybackAuthorized: type: number nullable: true @@ -5884,7 +6477,10 @@ components: toolset: type: string nullable: true - description: The id of the associated toolset + description: | + The id of the toolset to apply to this assignment. + The toolset will be copied to the assignment as a dedicated object to prevent unexpected changes when making modifications to the template toolset. + This property can be set to null to delete the linked toolset and switch back to all the tools available for this assignment. coverFile: type: string nullable: true @@ -5900,6 +6496,35 @@ components: maximum: 100 description: | If set, the grading will be enabled for the assignement with this value as the maximum of points + releaseGrades: + type: string + enum: [auto, manual] + description: | + For worksheets, how grading will work for the assignment: + - If set to `auto`, the grades will be automatically released when the student submits the submissions + - If set to `manual`, the grades will only be set as `draftGrade` and will be released when the teacher returns the submissions + shuffleExercises: + type: boolean + description: Mixing worksheets exercises for each student + state: + type: string + description: State of the assignment + enum: + - draft + - active + dueDate: + type: string + nullable: true + description: | + The due date of this assignment, late submissions will be marked as paste due. If not set, the assignment won't have a due date. + format: date-time + scheduledDate: + type: string + nullable: true + description: | + The publication (scheduled) date of the assignment. + If this one is specified, the assignment will only be listed to the teachers of the class. + format: date-time googleClassroom: type: object description: Google Classroom options for this assignment @@ -5929,21 +6554,6 @@ components: items: type: string description: Identifiers for the students that have access to the assignment - shuffleExercises: - type: boolean - description: Mixing exercises for each students - description: Assignment creation details - example: - title: First assignment - description: Get started with Flat - maxPoints: 100 - attachments: - - type: flat - score: '0000000000000000' - - type: link - url: https://flat.io/developers - scheduledDate: 2017-06-20T13:56:19.613000Z - dueDate: 2017-07-12T13:56:19.613000Z AssignmentCopy: type: object properties: @@ -5960,9 +6570,100 @@ components: If this one is specified, the assignment will only be listed to the teachers of the class. Alternatively the existing `scheduledDate` from the copied assignment will be used. format: date-time - description: Assignment copy operation - example: - classroom: '0000000000000000' + libraryParent: + type: string + description: Identifier of the parent resource where the new one will created, e.g. a folder id or `root` + AssignmentCopyResponse: + type: object + properties: + id: + type: string + description: Unique identifier of the assignment + type: + $ref: '#/components/schemas/AssignmentType' + capabilities: + required: + - canEdit + - canPublishInClass + - canArchive + - canUnarchive + type: object + description: Capabilities the current user has on this assignment. Each capability corresponds to a fine-grained action that a user may take. + properties: + canEdit: + type: boolean + description: | + Whether the current user can edit the assignment + canPublishInClass: + type: boolean + description: | + Whether this assignment can be published in a class + canPublishInClassError: + type: object + required: + - code + - message + description: | + If `canPublishInClass` and `canEdit` are false, the issue why this assignment cannot be published in a class + properties: + code: + type: string + description: A corresponding code for this error + message: + type: string + description: A printable and localized message for this error + canArchive: + type: boolean + description: | + Whether the current user can archive the assignment + canUnarchive: + type: boolean + description: | + Whether the current user can unarchive the assignment + title: + type: string + description: Title of the assignment + description: + type: string + description: Description and content of the assignment + cover: + type: string + description: The URL of the cover to display + coverFile: + type: string + description: The id of the cover to display + attachments: + type: array + items: + $ref: '#/components/schemas/MediaAttachment' + useDedicatedAttachments: + type: boolean + description: | + 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. + maxPoints: + type: number + description: | + If set, the grading will be enabled for the assignement + releaseGrades: + type: string + enum: [auto, manual] + description: | + For worksheets, how grading will work for the assignment: + - If set to `auto`, the grades will be automatically released when the student submits the submissions + - If set to `manual`, the grades will only be set as `draftGrade` and will be released when the teacher returns the submissions + shuffleExercises: + type: boolean + description: Mixing worksheets exercises for each student + toolset: + type: string + description: The id of the associated toolset + nbPlaybackAuthorized: + type: number + description: The number of playback authorized on the scores of the assignment. + resource: + type: string + description: If this assignment is stored as a resource in the Flat for Education Resource Library, the unique identifier of the resource. AssignmentType: type: string description: Type of the assignment @@ -5975,22 +6676,169 @@ components: - performance Assignment: type: object + required: + - id + - type + - title + - attachments + - capabilities properties: - state: + id: type: string - description: State of the assignment - enum: - - draft - - active - - archived + description: Unique identifier of the assignment + type: + $ref: '#/components/schemas/AssignmentType' + capabilities: + required: + - canEdit + - canPublishInClass + - canArchive + - canUnarchive + type: object + description: Capabilities the current user has on this assignment. Each capability corresponds to a fine-grained action that a user may take. + properties: + canEdit: + type: boolean + description: | + Whether the current user can edit the assignment + canPublishInClass: + type: boolean + description: | + Whether this assignment can be published in a class + canPublishInClassError: + type: object + required: + - code + - message + description: | + If `canPublishInClass` and `canEdit` are false, the issue why this assignment cannot be published in a class + properties: + code: + type: string + description: A corresponding code for this error + message: + type: string + description: A printable and localized message for this error + canArchive: + type: boolean + description: | + Whether the current user can archive the assignment + canUnarchive: + type: boolean + description: | + Whether the current user can unarchive the assignment + title: + type: string + description: Title of the assignment + description: + type: string + description: Description and content of the assignment + cover: + type: string + description: The URL of the cover to display + coverFile: + type: string + description: The id of the cover to display + attachments: + type: array + items: + $ref: '#/components/schemas/MediaAttachment' + useDedicatedAttachments: + type: boolean + description: | + 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. + maxPoints: + type: number + description: | + If set, the grading will be enabled for the assignement + releaseGrades: + type: string + enum: [auto, manual] + description: | + For worksheets, how grading will work for the assignment: + - If set to `auto`, the grades will be automatically released when the student submits the submissions + - If set to `manual`, the grades will only be set as `draftGrade` and will be released when the teacher returns the submissions + shuffleExercises: + type: boolean + description: Mixing worksheets exercises for each student + toolset: + type: string + description: The id of the associated toolset + nbPlaybackAuthorized: + type: number + description: The number of playback authorized on the scores of the assignment. + description: Assignment details + example: + id: 636a724a89a6eaa0a54c3900 + title: My first assignment + description: Get started with Flat + maxPoints: 100 + attachments: + - type: flat + score: '0000000000000000' + - type: link + url: https://flat.io/developers + - type: video + url: https://www.youtube.com/watch?v=SNbRUiBZ4Uw + title: Flat - The online collaborative music notation software + description: Discover Flat on https://flat.io + html: + thumbnailUrl: https://i.ytimg.com/vi/SNbRUiBZ4Uw/maxresdefault.jpg + thumbnailHeight: 1052 + thumbnailWidth: 1868 + authorName: Flat + authorUrl: https://www.youtube.com/channel/UCEUIbEP9Rba_g0r4eeGhmXw + ClassAssignment: + type: object + properties: + id: + type: string + description: Unique identifier of the assignment type: $ref: '#/components/schemas/AssignmentType' + capabilities: + required: + - canEdit + - canPublishInClass + - canArchive + - canUnarchive + type: object + description: Capabilities the current user has on this assignment. Each capability corresponds to a fine-grained action that a user may take. + properties: + canEdit: + type: boolean + description: | + Whether the current user can edit the assignment + canPublishInClass: + type: boolean + description: | + Whether this assignment can be published in a class + canPublishInClassError: + type: object + required: + - code + - message + description: | + If `canPublishInClass` and `canEdit` are false, the issue why this assignment cannot be published in a class + properties: + code: + type: string + description: A corresponding code for this error + message: + type: string + description: A printable and localized message for this error + canArchive: + type: boolean + description: | + Whether the current user can archive the assignment + canUnarchive: + type: boolean + description: | + Whether the current user can unarchive the assignment title: type: string description: Title of the assignment - classroom: - type: string - description: The unique identifier of the class where this assignment was posted description: type: string description: Description and content of the assignment @@ -6004,14 +6852,45 @@ components: type: array items: $ref: '#/components/schemas/MediaAttachment' - submissions: - type: array - items: - $ref: '#/components/schemas/AssignmentSubmission' + useDedicatedAttachments: + type: boolean + description: | + 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. + maxPoints: + type: number + description: | + If set, the grading will be enabled for the assignement + releaseGrades: + type: string + enum: [auto, manual] + description: | + For worksheets, how grading will work for the assignment: + - If set to `auto`, the grades will be automatically released when the student submits the submissions + - If set to `manual`, the grades will only be set as `draftGrade` and will be released when the teacher returns the submissions + shuffleExercises: + type: boolean + description: Mixing worksheets exercises for each student + toolset: + type: string + description: The id of the associated toolset + nbPlaybackAuthorized: + type: number + description: The number of playback authorized on the scores of the assignment. creator: type: string description: | The User unique identifier of the creator of this assignment + state: + type: string + description: State of the assignment + enum: + - draft + - active + - archived + classroom: + type: string + description: The unique identifier of the class where this assignment was posted creationDate: type: string description: The creation date of this assignment @@ -6028,10 +6907,21 @@ components: The due date of this assignment, late submissions will be marked as paste due. format: date-time - maxPoints: - type: number - description: | - If set, the grading will be enabled for the assignement + assigneeMode: + type: string + description: Possible modes of assigning assignments + enum: + - everyone + - selected + assignedStudents: + type: array + items: + type: string + description: Identifiers for the students that have access to the assignment + submissions: + type: array + items: + $ref: '#/components/schemas/AssignmentSubmission' googleClassroom: $ref: '#/components/schemas/GoogleClassroomCoursework' microsoftGraph: @@ -6063,55 +6953,9 @@ components: id: type: string description: Resource ID in the LMS - description: Assignment details - example: - title: My first assignment - description: Get started with Flat - state: active - creator: 5832bf149995c4024bd6de7d - classroom: 58c4725345cd836264f0b29e - creationDate: 2017-06-12T13:56:19.613000Z - dueDate: 2017-07-12T13:56:19.613000Z - scheduledDate: 2017-06-18T13:56:19.613000Z - maxPoints: 100 - attachments: - - type: flat - score: '0000000000000000' - - type: link - url: https://flat.io/developers - - type: video - url: https://www.youtube.com/watch?v=SNbRUiBZ4Uw - title: Flat - The online collaborative music notation software - description: Discover Flat on https://flat.io - html: - thumbnailUrl: https://i.ytimg.com/vi/SNbRUiBZ4Uw/maxresdefault.jpg - thumbnailHeight: 1052 - thumbnailWidth: 1868 - authorName: Flat - authorUrl: https://www.youtube.com/channel/UCEUIbEP9Rba_g0r4eeGhmXw - googleClassroom: - id: '1235665432' - alternateLink: http://classroom.google.com/c/music-theory/a/first-assignment/detail - lti: - id: '12345' - canvas: - id: '12345' - alternateLink: https://canvas.instructure.com/courses/00000/assignments/12345 - submissions: - - id: 58c4955c226ffff257211a90 - classroom: 58c4725345cd836264f0b29e - assignment: 58c49068524c03ec576ca43c - creator: 559eb5c7f0d4d5e46d03781d - creationDate: 2017-03-12T00:25:00.748000Z - submissionDate: 2017-03-12T00:25:22.748000Z - attachments: - - type: flat - score: 58c4955a226ffff257211a8d - title: Hello - Student - googleClassroom: - id: CgsI-00000000000 - state: turned_in - alternateLink: http://classroom.google.com/c/music-theory/a/first-assignment/submissions/student/my-submission + issue: + type: string + description: Detected issue for this assignment AssignmentSubmissionUpdate: type: object properties: @@ -6166,8 +7010,23 @@ components: - created - turnedIn - returned + AssignmentSubmissionHistoryState: + type: string + description: State of the submission history + enum: + - created + - turnedIn + - returned + - reset AssignmentSubmission: type: object + required: + - id + - state + - classroom + - assignment + - creator + - attachments properties: id: type: string @@ -6193,7 +7052,7 @@ components: $ref: '#/components/schemas/MediaAttachment' submissionDate: type: string - description: The date when the student submitted his work + description: The date when the student submitted their work returnDate: type: string description: The date when the teacher returned the work @@ -6291,8 +7150,15 @@ components: type: array items: type: string + source: + description: The source of the change if the change was made by a third-party software + type: string + enum: + - lti + - googleClassroom + - microsoftGraph state: - $ref: '#/components/schemas/AssignmentSubmissionState' + $ref: '#/components/schemas/AssignmentSubmissionHistoryState' draftGrade: type: number description: The numerator of the grade at this time in the submission grade history @@ -6302,6 +7168,13 @@ components: maxPoints: type: number description: The denominator of the grade at this time in the submission grade history + comment: + type: string + description: The comment that is made to this submission + dueDate: + type: string + description: The due date of this assignment + format: date-time attachment: type: object properties: @@ -6311,6 +7184,257 @@ components: revision: type: string description: The revision identifier that changed + title: + type: string + description: The title of the score that changed + EduLibrary: + description: A Flat for Education Library + type: object + properties: + id: + type: string + description: | + Unique identifier of the library. + + This one can be used to list the underlying resources using + `GET /v2/eduResources?parent={library-id}` + name: + type: string + description: Name of the lirbary + type: + type: string + description: Type of the library + enum: + - myResources + - flatEduSamples + visibility: + description: Visibility of the library + type: string + enum: + - private + - organization + - public + example: + id: root + name: My resources + visibility: private + EduResourcePrivacy: + type: string + description: | + The Education resource privacy mode. + default: private + enum: + - private + - public + EduResource: + description: A Flat for Education resource contained in a resources library + type: object + required: + - id + - type + - title + - capabilities + properties: + id: + type: string + description: Resource unique identifier + creator: + type: string + description: The User identifier of the resource creator + type: + $ref: '#/components/schemas/EduResourceType' + privacy: + $ref: '#/components/schemas/EduResourcePrivacy' + tags: + type: array + description: Specific attributes for the resource (e.g. sample resources with custom design) + items: + type: string + parent: + type: string + description: Identifier of the parent resource, e.g. a folder or root + title: + type: string + description: Title of the resource + creationDate: + type: string + format: date-time + description: The date when the resource was created + updateDate: + type: string + format: date-time + description: The date when the resource was updated + resource: + type: object + properties: + id: + type: string + description: Unique identifier of the assignment + type: + $ref: '#/components/schemas/AssignmentType' + capabilities: + required: + - canEdit + - canPublishInClass + - canArchive + - canUnarchive + type: object + description: Capabilities the current user has on this assignment. Each capability corresponds to a fine-grained action that a user may take. + properties: + canEdit: + type: boolean + description: | + Whether the current user can edit the assignment + canPublishInClass: + type: boolean + description: | + Whether this assignment can be published in a class + canPublishInClassError: + type: object + required: + - code + - message + description: | + If `canPublishInClass` and `canEdit` are false, the issue why this assignment cannot be published in a class + properties: + code: + type: string + description: A corresponding code for this error + message: + type: string + description: A printable and localized message for this error + canArchive: + type: boolean + description: | + Whether the current user can archive the assignment + canUnarchive: + type: boolean + description: | + Whether the current user can unarchive the assignment + title: + type: string + description: Title of the folder + description: + type: string + description: Description and content of the assignment + cover: + type: string + description: The URL of the cover to display + coverFile: + type: string + description: The id of the cover to display + attachments: + type: array + items: + $ref: '#/components/schemas/MediaAttachment' + useDedicatedAttachments: + type: boolean + description: | + 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. + maxPoints: + type: number + description: | + If set, the grading will be enabled for the assignement + releaseGrades: + type: string + enum: [auto, manual] + description: | + For worksheets, how grading will work for the assignment: + - If set to `auto`, the grades will be automatically released when the student submits the submissions + - If set to `manual`, the grades will only be set as `draftGrade` and will be released when the teacher returns the submissions + shuffleExercises: + type: boolean + description: Mixing worksheets exercises for each student + toolset: + type: string + description: The id of the associated toolset + nbPlaybackAuthorized: + type: number + description: The number of playback authorized on the scores of the assignment. + capabilities: + description: Capabilities available for this resource + type: object + properties: + canEdit: + type: boolean + description: | + Whether the current user can modify this resource + canAddResources: + type: boolean + description: | + Whether the current user can add resources within this resource (e.g. `assignment` inside a `folder`) + canAddFolders: + type: boolean + description: | + Whether the current user can add folders within this resource (e.g. `folder` inside `root`) + EduResourceCreation: + description: Creation of an education resource + type: object + required: + - type + - title + properties: + type: + $ref: '#/components/schemas/EduResourceType' + title: + type: string + description: Title of the resource + maxLength: 1000 + minLength: 1 + parent: + type: string + default: root + description: Identifier of the parent resource where the new one will created, e.g. a folder id or `root` + EduResourceUpdate: + description: Update of an education resource + type: object + properties: + title: + type: string + description: Title of the resource + maxLength: 1000 + minLength: 1 + EduResourceType: + description: Type of an education resource + type: string + enum: + - assignment + - folder + EduResourceMove: + description: Move an education resource + type: object + required: + - destination + properties: + destination: + type: string + description: | + Unique identifier of the destination of the folder where to move this resource. + This can also be `root` to move the resource at the root of the user resource library. + EduResourceCopy: + description: Copy an education resource + type: object + required: + - destination + properties: + destination: + type: string + description: | + Unique identifier of the destination of the folder where to copy this resource. + This can also be `root` to copy the resource at the root of the user resource library. + EduResourceUseInClass: + description: Use an education resource in class + type: object + required: + - classroom + properties: + classroom: + type: string + description: The destination classroom where the resource will be copied. + assignment: + type: string + description: An optional destination assignment where the original assignement will be copied. Must be a draft. MicrosoftGraphAssignment: type: object description: A Microsoft Teams asignment @@ -6449,12 +7573,14 @@ components: - performance MediaAttachment: type: object + required: + - type properties: type: type: string description: | The type of the assignment resolved: - * `rich`, `photo`, `video` are attachment types that are automatically resolved from a `link` attachment. + * `rich`, `photo`, `video` are automatically resolved as `link` * A `flat` attachment is a score document where the unique identifier will be specified in the `score` property. Its sharing mode will be provided in the `sharingMode` property. enum: - rich @@ -6474,6 +7600,9 @@ components: worksheet: type: string description: An unique worksheet identifier + dedicated: + type: boolean + description: 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 track: type: string description: A unique track identifier @@ -6553,10 +7682,7 @@ components: description: Unique identifier of the task type: type: string - description: Type of the task - enum: - - audio-export - - audio-low-prio + description: Type of the task (e.g. audio-export) state: type: string description: State of the Task @@ -6566,6 +7692,12 @@ components: - done - canceled - error + format: + type: string + description: For files processing, the file format (e.g. `mp3`, `wav`) + score: + type: string + description: The score unique identifier for tasks related to scores progress: type: object description: Details about the task progression @@ -6588,16 +7720,34 @@ components: type: string description: The date when the task has been completed format: date-time + result: + type: object + description: Optional result information about this task + properties: + url: + description: URL returned by the task worker + type: string + error: + description: Error returned by task worker + type: string + errorHistory: + type: array + description: If any errors happened when processing this task, the list of errors identifiers + items: + type: string FlatErrorResponse: description: An API Error response type: object + required: + - code + - message properties: code: type: string description: A corresponding code for this error message: type: string - description: A printable message for this message + description: A printable message for this error id: type: string description: An unique error identifier generated for the request @@ -6608,6 +7758,34 @@ components: code: CLIENT_ERROR message: Invalid request id: '123456789' + UserCommunityProfileLinks: + type: object + description: Social networks links + properties: + spotifyUrl: + type: string + nullable: true + description: Spotify Profile URL + youtubeUrl: + type: string + nullable: true + description: YouTube channel URL + soundcloudUrl: + type: string + nullable: true + description: SoundCloud Profile URL + tiktokUrl: + type: string + nullable: true + description: TikTok profile URL. For updates, also accepts TikTok usernames + instagramUrl: + type: string + nullable: true + description: Instagram profile URL. For updates, also accepts Instagram usernames + websiteUrl: + type: string + nullable: true + description: Personnal website URL parameters: limit: name: limit diff --git a/spec/openapi.yaml b/spec/openapi.yaml index e34b07e..108fbbf 100644 --- a/spec/openapi.yaml +++ b/spec/openapi.yaml @@ -5,7 +5,7 @@ # Some style notes: # - This file is used by ReDoc, which allows GitHub Flavored Markdown in descriptions. # - There is no maximum line length, for ease of editing and pretty diffs. -openapi: 3.0.2 +openapi: 3.0.3 info: title: Flat API description: | @@ -33,7 +33,7 @@ info: name: Flat url: https://flat.io/developers/docs/api/ email: developers@flat.io - version: 2.17.0 + version: 2.18.0 x-logo: url: https://prod.flat-cdn.com/img/logo-flat.svg servers: @@ -42,7 +42,7 @@ tags: - name: Account description: | These API endpoints are related to the Flat account you are currently using. When using an OAuth2 access token, you can use [`GET /me`](#operation/getAuthenticatedUser) to get information about the account. - x-displayName: Flat Account + x-displayName: Accounts - name: Score description: | Sheet music is the main API object type available for all Flat account. @@ -70,23 +70,32 @@ tags: At this time, only `private` privacy mode is widely available. Privacy modes `public`, `organizationPublic` and `privateLink`, and 1:1 sharing will be available in an upcoming update later this year. x-displayName: Collections of music scores - - name: User - description: Flat users + x-displayName: Users profiles + description: API methods related to the Flat Community user profiles and Flat for Education profiles - name: Organization - description: Flat for Education organizations + x-displayName: Flat for Education Organizations + description: Flat for Education Organizations - name: Class - description: Flat for Education classes + x-displayName: Flat for Education Classes + description: Flat for Education Classes +- name: EduResources + x-displayName: Flat for Education Resources [Beta] + description: | + Resource libraries in Flat for Education. + These API endpoints are in beta and may include breaking changes over the upcoming months. - name: Group - description: Flat Groups + x-displayName: Flat for Education Groups + description: Flat for Education Groups - name: Task - description: Scheduled tasks + x-displayName: Asynchronous tasks + description: Scheduled and asynchronous tasks paths: /me: get: tags: - Account - summary: Get current user profile + summary: Get current user account description: | Get details about the current authenticated User. operationId: getAuthenticatedUser @@ -414,7 +423,6 @@ paths: post: tags: - Score - - Class summary: Fork a score description: | This API call will make a copy of the last revision of the specified score and create a new score. The copy of the score will have a privacy set to `private`. @@ -1233,7 +1241,6 @@ paths: - OAuth2: - scores.social - scores - /scores/{score}/revisions: parameters: - name: score @@ -2451,14 +2458,14 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/OrganizationUserSigninLinkCreation' + $ref: '#/components/schemas/UserSigninLinkCreation' responses: 200: description: Sign in link content: application/json: schema: - $ref: '#/components/schemas/OrganizationUserSigninLink' + $ref: '#/components/schemas/UserSigninLink' default: description: Error content: @@ -3050,7 +3057,7 @@ paths: schema: type: array items: - $ref: '#/components/schemas/Assignment' + $ref: '#/components/schemas/ClassAssignment' default: description: Error content: @@ -3071,12 +3078,12 @@ paths: Use this method as a teacher to create and post a new assignment to a class. If the class is synchronized with Google Classroom, the assignment will be automatically posted to your Classroom course. - operationId: createAssignment + operationId: createClassAssignment requestBody: content: application/json: schema: - $ref: '#/components/schemas/AssignmentCreation' + $ref: '#/components/schemas/ClassAssignmentUpdate' required: false responses: 200: @@ -3105,11 +3112,11 @@ paths: - Class summary: Copy an assignment description: | - Copy an assignment to a specified class. + Copy an assignment to a specified class or the resource library - If the original assignment has a due date in the past, this new assingment will be created without a due date. - - If the new class is synchronized with an external app (e.g. Google Classroom), the copied assignment will also be posted on the external app. + For class assignments: + - If the original assignment has a due date in the past, this new assignment will be created without a due date. + - If the class is synchronized with an external app (e.g. Google Classroom), the copied assignment will also be posted on the external app. operationId: copyAssignment requestBody: content: @@ -3119,11 +3126,11 @@ paths: required: true responses: 200: - description: The new created assingment + description: The new created assignment content: application/json: schema: - $ref: '#/components/schemas/Assignment' + $ref: '#/components/schemas/AssignmentCopyResponse' default: description: Error content: @@ -3374,17 +3381,21 @@ paths: delete: tags: - Class - summary: Delete a submission + summary: Reset a submission description: | - Use this method as a teacher to delete a submission and allow student to start over the assignment + Use this method as a teacher to reset a submission and allow student to start over the assignment operationId: deleteSubmission parameters: - $ref: '#/components/parameters/class' - $ref: '#/components/parameters/assignment' - $ref: '#/components/parameters/submission' responses: - 204: - description: The submission has been deleted + 200: + description: The submission object once reset + content: + application/json: + schema: + $ref: '#/components/schemas/AssignmentSubmission' default: description: Error content: @@ -3581,6 +3592,45 @@ paths: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' + /classes/{class}/testStudent: + parameters: + - $ref: '#/components/parameters/class' + post: + tags: + - Class + summary: Create a test student account + description: | + Test students account can be created by teachers an admin and be used to experiment the assignments. + + - They are automatically added to the class. + - They can be reset using this API endpoint (a new account will be created and the previous one scheduled for deletion). + - These accounts don't use a user license. + operationId: createTestStudentAccount + parameters: + - name: reset + in: query + description: | + If true, the testing account will be re-created. + required: false + schema: + type: boolean + responses: + 200: + description: Test account created + content: + application/json: + schema: + $ref: '#/components/schemas/UserDetails' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.admin + - edu.classes /classes/enroll/{enrollmentCode}: parameters: - name: enrollmentCode @@ -3717,215 +3767,610 @@ paths: - OAuth2: - scores - scores.readonly -components: - securitySchemes: - OAuth2: - type: oauth2 - description: | - OAuth 2.0 authentication for your app or. Please only request the most restrictive and needed scopes. Using some of the scopes may require an additional review from our team. The Flat API supports **authorization code** and **implicit** flows. - flows: - authorizationCode: - authorizationUrl: https://flat.io/auth/oauth - tokenUrl: https://api.flat.io/oauth/access_token - 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.email: | - Provices access to the person's email. - 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. - scores.social: | - 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. - tasks.readonly: Read-only access to export tasks created by this account. - schemas: - FlatLocales: - type: string - description: The user language - default: en - enum: - - en - - en-GB - - es - - fr - - de - - it - - ja - - ja-HIRA - - ko - - nl - - pl - - pt - - pt-BR - - ro - - ru - - sv - - tr - - zh-Hans - OrganizationRoles: - type: string - description: User's Organization Role (for Edu users only) - enum: - - admin - - billing - - teacher - - user - ClassRoles: - type: string - description: User's Class Role (for Edu users only) - enum: - - teacher - - student - LicenseMode: - type: string - description: Mode of the license - enum: - - credit - - site - LicenseSources: - type: string - description: Source of the license - default: order - enum: - - order - - trial - - voucher - - distributor - - subscription - - appStore - UserBasics: - type: object - properties: - id: - type: string - description: The user unique identifier - type: - type: string - description: The type of user account - enum: [user, guest] - username: - type: string - description: The user name (unique for the organization) - printableName: - type: string - description: The name that can be directly printed (name, firstname & lastname, or username) - firstname: - type: string - description: Firstname of the user (for education users) - lastname: + /eduResources: + get: + tags: + - EduResources + operationId: listEduResources + summary: List education resources in a library or folder + parameters: + - name: parent + in: query + description: | + List the resources contained in this `parent` library or folder + schema: type: string - description: Lastname of the user (for education users) - name: + default: root + - name: type + in: query + description: | + Filter the returned resources by type + schema: type: string - description: A displayable name for the user (for consumer users) - picture: + enum: + - assignment + - folder + - name: sort + in: query + description: Sort + schema: type: string - nullable: true - description: The URL of the picture to display - isPowerUser: - type: boolean - description: User license status. 'true' if user is an individual Power user - isFlatTeam: - type: boolean - description: Will be 'true' if user is part of the Flat Team - example: - id: '000000000000000000000001' - username: flat - name: Flat Team - printableName: Flat Team - picture: https://flat.io/img/logo_flat.svg - isPowerUser: true - isFlatTeam: true - discriminator: - propertyName: type - UserPublicSummary: - description: Public User details summary - allOf: - - $ref: '#/components/schemas/UserBasics' - - type: object - properties: - organization: - type: string - description: Organization ID (for Edu users only) - organizationRole: - $ref: '#/components/schemas/OrganizationRoles' - classRole: - $ref: '#/components/schemas/ClassRoles' - htmlUrl: - type: string - description: Link to user profile (for Indiv. users only) - UserPublic: - description: Public User details - allOf: - - $ref: '#/components/schemas/UserPublicSummary' - - type: object - properties: - bio: - type: string - description: User's biography - registrationDate: - type: string - description: Date the user signed up - format: date-time - likedScoresCount: - type: integer - description: Number of the scores liked by the user - followersCount: - type: integer - description: Number of followers the user have - followingCount: - type: integer - description: Number of people the user follow - ownedPublicScoresCount: - type: integer - description: Number of public scores the user have - coverPicture: - type: string - description: Cover picture (backgroud) for the profile - profileTheme: - type: string - description: Theme (background) for the profile - instruments: - type: array - description: | - An array of the instrument identifiers. - The format of the strings is `{instrument-group}.{instrument-id}`. - items: - type: string - UserDetailsAdmin: - description: User details (view for organization teacher / admin) - allOf: - - $ref: '#/components/schemas/UserPublicSummary' - - type: object - properties: - email: - type: string - description: Email of the user - format: email - lastActivityDate: - type: string - description: Date of the last user activity - format: date-time - license: - type: object - properties: - id: - type: string + enum: + - creationDate + - updateDate + - title + default: creationDate + - $ref: '#/components/parameters/sortDirection' + - name: limit + in: query + description: This is the maximum number of resources that may be returned + schema: + maximum: 100 + minimum: 1 + type: integer + default: 25 + - $ref: '#/components/parameters/next' + - $ref: '#/components/parameters/previous' + responses: + 200: + description: List of resources + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.resources.readonly + - edu.assignments + - edu.assignments.readonly + post: + tags: + - EduResources + operationId: createEduResource + summary: Create a new education resource + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EduResourceCreation' + required: true + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/libraries: + get: + tags: + - EduResources + operationId: listEduLibraries + summary: List the education libraries + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + type: array + description: List of libraries to display + items: + $ref: '#/components/schemas/EduLibrary' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.resources.readonly + - edu.assignments + - edu.assignments.readonly + /eduResources/{resource}: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + get: + tags: + - EduResources + operationId: getEduResource + summary: Get an education resource + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.resources.readonly + - edu.assignments + - edu.assignments.readonly + put: + tags: + - EduResources + operationId: updateEduResource + summary: Update an education resource metadata + description: | + Update any resources metadata (e.g. title). + + Use this method to rename education resources folders or assignments. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EduResourceUpdate' + required: true + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + delete: + tags: + - EduResources + operationId: deleteEduResource + summary: Delete an education resource + responses: + 204: + description: Resource deleted + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/{resource}/move: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + post: + tags: + - EduResources + operationId: moveEduResource + summary: Move an education resource + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EduResourceMove' + required: true + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/{resource}/copy: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + post: + tags: + - EduResources + operationId: copyEduResource + summary: Copy an education resource to a Resource Library + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EduResourceCopy' + required: true + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/EduResource' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/{resource}/copyToDemoClass: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + post: + tags: + - EduResources + operationId: copyEduResourceToDemoClass + summary: Copy an education assignment to a teacher demo class + description: | + Once a resource library can be published to a class (`Assignment.capabilities.canPublishInClass = true`), + this endpoint can be used for the feature "View as student". + + It will ensure the teacher has a demo class, then copy the assignment to the demo class. + You can then use `POST /classes/{class}/testStudent` to create a testing student account + in the demo class. + responses: + 200: + description: Assignment copied to the demo class + content: + application/json: + schema: + $ref: '#/components/schemas/ClassAssignment' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/{resource}/useInClass: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + post: + tags: + - EduResources + operationId: useEduResourceInClass + summary: Use an education resource in a class + description: | + This endpoint will copy a resource and the underlying resources. + The assignment will be created as a draft that can be completed with other options before publishing (e.g. due date, publication date for scheduling, etc.). + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EduResourceUseInClass' + required: true + responses: + 200: + description: Assignment copied to the chosen class + content: + application/json: + schema: + $ref: '#/components/schemas/ClassAssignment' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments + /eduResources/{resource}/assignment: + parameters: + - name: resource + in: path + required: true + description: Unique identifier of the resource + schema: + type: string + put: + tags: + - EduResources + operationId: updateEduResourceAssignment + summary: Update an education resource assignment + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AssignmentUpdate' + required: true + responses: + 200: + description: Fetched resource + content: + application/json: + schema: + $ref: '#/components/schemas/Assignment' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - edu.resources + - edu.assignments +components: + securitySchemes: + OAuth2: + type: oauth2 + description: | + OAuth 2.0 authentication for your app or. Please only request the most restrictive and needed scopes. Using some of the scopes may require an additional review from our team. The Flat API supports **authorization code** and **implicit** flows. + flows: + authorizationCode: + authorizationUrl: https://flat.io/auth/oauth + tokenUrl: https://api.flat.io/oauth/access_token + 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.email: | + Provices access to the person's email. + 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. + scores.social: | + 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.resources: Read-write access to the resource library. + edu.resources.readonly: Read-only access to the resource library. + 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. + tasks.readonly: Read-only access to export tasks created by this account. + schemas: + FlatLocales: + type: string + description: The user language + default: en + enum: + - en + - en-GB + - es + - fr + - de + - it + - ja + - ja-HIRA + - ko + - nl + - pl + - pt + - pt-BR + - ro + - ru + - sv + - tr + - zh-Hans + OrganizationRoles: + type: string + description: User's Organization Role (for Edu users only) + enum: + - admin + - billing + - teacher + - user + ClassRoles: + type: string + description: User's Class Role (for Edu users only) + enum: + - teacher + - student + LicenseMode: + type: string + description: Mode of the license + enum: + - credit + - site + LicenseSources: + type: string + description: Source of the license + default: order + enum: + - order + - trial + - voucher + - distributor + - subscription + - appStore + - playStore + - musicfirst + UserBasics: + type: object + required: + - id + - type + - username + - picture + properties: + id: + type: string + description: The user unique identifier + type: + type: string + description: The type of user account + enum: [user, guest] + username: + type: string + description: The user name (unique for the organization) + printableName: + type: string + description: The name that can be directly printed (name, firstname & lastname, or username) + firstname: + type: string + description: Firstname of the user (for education users) + lastname: + type: string + description: Lastname of the user (for education users) + name: + type: string + description: A displayable name for the user (for consumer users) + picture: + type: string + nullable: true + description: The URL of the picture to display + badges: + type: array + description: List of badges for the user profile + items: + type: string + description: Badge name, e.g. `power`, `staff`, `composerOfTheMonth` + example: + id: '000000000000000000000001' + username: flat + name: Flat Team + printableName: Flat Team + picture: https://flat.io/img/logo_flat.svg + badges: [power, staff] + UserPublicSummary: + description: Public User details summary + allOf: + - $ref: '#/components/schemas/UserBasics' + - type: object + properties: + organization: + type: string + description: Organization ID (for Edu users only) + organizationRole: + $ref: '#/components/schemas/OrganizationRoles' + classRole: + $ref: '#/components/schemas/ClassRoles' + htmlUrl: + type: string + description: Link to user profile (for Indiv. users only) + UserPublic: + description: Public User details + allOf: + - $ref: '#/components/schemas/UserPublicSummary' + - type: object + properties: + bio: + type: string + description: User's biography + registrationDate: + type: string + description: Date the user signed up + format: date-time + likedScoresCount: + type: integer + description: Number of the scores liked by the user + followersCount: + type: integer + description: Number of followers the user have + followingCount: + type: integer + description: Number of people the user follow + ownedPublicScoresCount: + type: integer + description: Number of public scores the user have + coverPicture: + type: string + description: Cover picture (backgroud) for the profile + profileTheme: + type: string + description: Theme (background) for the profile + instruments: + type: array + description: | + An array of the instrument identifiers. + The format of the strings is `{instrument-group}.{instrument-id}`. + items: + type: string + links: + $ref: '#/components/schemas/UserCommunityProfileLinks' + UserDetailsAdmin: + description: User details (view for organization teacher / admin) + allOf: + - $ref: '#/components/schemas/UserPublicSummary' + - type: object + properties: + email: + type: string + description: Email of the user + format: email + lastActivityDate: + type: string + description: Date of the last user activity + format: date-time + license: + type: object + properties: + id: + type: string description: ID of the current license expirationDate: type: string @@ -3939,6 +4384,12 @@ components: type: boolean description: ID of the current license description: Current active license of the user + groups: + description: For Flat for Education accounts, list of Group identifiers the user is part of. + type: array + items: + type: string + description: Unique group identifier UserCreation: required: - password @@ -4010,6 +4461,18 @@ components: description: Email of the account format: email description: User update as an organization admin + UserAzureDetails: + type: object + properties: + oid: + type: string + description: User object identifier on Azure AD + hd: + type: string + description: User tenant (domain name) + preferredUsername: + type: string + description: User Preferred Username (UPN), i.e. the main email of the user UserDetails: description: User details allOf: @@ -4025,11 +4488,19 @@ components: enum: - user - guest + azureDetails: + $ref: '#/components/schemas/UserAzureDetails' privateProfile: type: boolean description: Tell either this user profile is private or not (individual accounts only) locale: $ref: '#/components/schemas/FlatLocales' + groups: + description: For Flat for Education accounts, list of Group identifiers the user is part of. + type: array + items: + type: string + description: Unique group identifier pictureFile: type: string nullable: true @@ -4038,7 +4509,7 @@ components: type: string nullable: true description: The ID of the user profile cover picture - OrganizationUserSigninLinkCreation: + UserSigninLinkCreation: type: object properties: destinationPath: @@ -4047,7 +4518,7 @@ components: default: / example: destinationPath: /class - OrganizationUserSigninLink: + UserSigninLink: type: object properties: url: @@ -4163,7 +4634,7 @@ components: userEmail: type: string description: | - If the collaborator is not a user of Flat yet, this field will contain his email. + If the collaborator is not a user of Flat yet, this field will contain their email. invited: type: boolean description: | @@ -4208,6 +4679,12 @@ components: aclAdmin: false ScoreSummary: type: object + required: + - id + - title + - privacy + - user + - htmlUrl properties: id: type: string @@ -4628,6 +5105,14 @@ components: deletions: type: number description: The number of deletions operations in the last revision + startDate: + type: string + format: date-time + description: The date of the first action included in this revision + endDate: + type: string + format: date-time + description: The date of the latest action included in this revision description: | The statistics related to the score revision (additions and deletions) example: @@ -4769,6 +5254,9 @@ components: shortName: type: string description: The abbreviation of the name of the instrument + hasQuarterTone: + type: boolean + description: True if the part can use quarter tone (prevent the part to have a TAB/chord grid) layoutData: type: object description: Control the appearance of the score. If missing, default values are used. @@ -4831,9 +5319,15 @@ components: collection: type: string default: root + nullable: true description: | Unique identifier of a collection where the score will be copied. If no collection identifier is provided, the score will be stored in the `root` directory. + If null is provided, the score won't be added to any collections + keepOriginalTitle: + type: boolean + description: | + 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). description: Options to fork the score ScoreModification: type: object @@ -5344,6 +5838,8 @@ components: - collections.readonly - collections.add_scores - collections + - edu.resources + - edu.resources.readonly - edu.classes - edu.classes.readonly - edu.assignments @@ -5534,6 +6030,15 @@ components: maxLength: 255 type: string description: The section of the new class + level: + $ref: '#/components/schemas/ClassGradeLevel' + skillsFocused: + $ref: '#/components/schemas/EduSkillsFocused' + size: + type: number + minimum: 0 + nullable: true + description: Number of students in the classroom description: Creation of a classroom example: name: Music Theory Course @@ -5549,6 +6054,15 @@ components: maxLength: 255 type: string description: The section of the class + level: + $ref: '#/components/schemas/ClassGradeLevel' + skillsFocused: + $ref: '#/components/schemas/EduSkillsFocused' + size: + type: number + minimum: 0 + nullable: true + description: Number of students in the classroom description: Update of a classroom example: name: Music Theory Course @@ -5717,6 +6231,14 @@ components: description: End date of the term format: date-time description: Clever.com section-related information + level: + $ref: '#/components/schemas/ClassGradeLevel' + skillsFocused: + $ref: '#/components/schemas/EduSkillsFocused' + size: + type: number + nullable: true + description: Number of students in the classroom description: A classroom example: id: '100000000000000000000001' @@ -5748,12 +6270,19 @@ components: properties: type: type: string - description: The type of the attachment posted + description: | + The type of the attachment posted: + * `rich`, `photo`, `video` are attachment types that are automatically resolved from a `link` attachment. + * A `flat` attachment is a score document where the unique identifier will be specified in the `score` property. Its sharing mode will be provided in the `sharingMode` property. enum: - - flat + - rich + - photo + - video - link + - flat - googleDrive - worksheet + - performance score: type: string description: | @@ -5780,20 +6309,41 @@ components: type: flat score: '000000000000000001' sharingMode: copy - AssignmentCreation: + ClassGradeLevel: + type: string + description: Class grade level + enum: + - elementary + - middle + - high + - university + - other + EduSkillsFocused: + type: array + description: Specific skills that will be focused in classroom + items: + type: string + enum: + - notation + - sight-reading + - performance-instrumental + - ear-training + - music-theory + - composition + - jazz-ensemble + - music-technology + - other + AssignmentUpdate: type: object + description: Assignment Resource Editing properties: type: $ref: '#/components/schemas/AssignmentType' - state: - type: string - description: State of the assignment - enum: - - draft - - active title: type: string description: Title of the assignment + maxLength: 1000 + minLength: 1 description: type: string description: Description and content of the assignment @@ -5801,19 +6351,6 @@ components: type: array items: $ref: '#/components/schemas/ClassAttachmentCreation' - dueDate: - type: string - nullable: true - description: | - The due date of this assignment, late submissions will be marked as paste due. If not set, the assignment won't have a due date. - format: date-time - scheduledDate: - type: string - nullable: true - description: | - The publication (scheduled) date of the assignment. - If this one is specified, the assignment will only be listed to the teachers of the class. - format: date-time nbPlaybackAuthorized: type: number nullable: true @@ -5821,7 +6358,10 @@ components: toolset: type: string nullable: true - description: The id of the associated toolset + description: | + The id of the toolset to apply to this assignment. + The toolset will be copied to the assignment as a dedicated object to prevent unexpected changes when making modifications to the template toolset. + This property can be set to null to delete the linked toolset and switch back to all the tools available for this assignment. coverFile: type: string nullable: true @@ -5837,39 +6377,16 @@ components: maximum: 100 description: | If set, the grading will be enabled for the assignement with this value as the maximum of points - googleClassroom: - type: object - description: Google Classroom options for this assignment - properties: - topicId: - type: string - nullable: true - description: Identifier of the topic where the assignment is created - microsoftGraph: - type: object - description: Microsoft Graph options for this assignment - properties: - categories: - description: List of categories this assignment belongs to - type: array - nullable: true - items: - type: string - assigneeMode: + releaseGrades: type: string - description: Possible modes of assigning assignments - enum: - - everyone - - selected - assignedStudents: - type: array - items: - type: string - description: Identifiers for the students that have access to the assignment + enum: [auto, manual] + description: | + For worksheets, how grading will work for the assignment: + - If set to `auto`, the grades will be automatically released when the student submits the submissions + - If set to `manual`, the grades will only be set as `draftGrade` and will be released when the teacher returns the submissions shuffleExercises: type: boolean - description: Mixing exercises for each students - description: Assignment creation details + description: Mixing worksheets exercises for each student example: title: First assignment description: Get started with Flat @@ -5879,10 +6396,92 @@ components: score: '0000000000000000' - type: link url: https://flat.io/developers - scheduledDate: 2017-06-20T13:56:19.613000Z - dueDate: 2017-07-12T13:56:19.613000Z + ClassAssignmentUpdate: + type: object + allOf: + - $ref: '#/components/schemas/AssignmentUpdate' + - type: object + properties: + state: + type: string + description: State of the assignment + enum: + - draft + - active + dueDate: + type: string + nullable: true + description: | + The due date of this assignment, late submissions will be marked as paste due. If not set, the assignment won't have a due date. + format: date-time + scheduledDate: + type: string + nullable: true + description: | + The publication (scheduled) date of the assignment. + If this one is specified, the assignment will only be listed to the teachers of the class. + format: date-time + googleClassroom: + type: object + description: Google Classroom options for this assignment + properties: + topicId: + type: string + nullable: true + description: Identifier of the topic where the assignment is created + microsoftGraph: + type: object + description: Microsoft Graph options for this assignment + properties: + categories: + description: List of categories this assignment belongs to + type: array + nullable: true + items: + type: string + assigneeMode: + type: string + description: Possible modes of assigning assignments + enum: + - everyone + - selected + assignedStudents: + type: array + items: + type: string + description: Identifiers for the students that have access to the assignment + description: Assignment creation details + example: + title: First assignment + description: Get started with Flat + maxPoints: 100 + attachments: + - type: flat + score: '0000000000000000' + - type: link + url: https://flat.io/developers + scheduledDate: 2017-06-20T13:56:19.613000Z + dueDate: 2017-07-12T13:56:19.613000Z AssignmentCopy: + oneOf: + - $ref: '#/components/schemas/AssignmentCopyToClass' + - $ref: '#/components/schemas/AssignmentCopyToResourceLibrary' + AssignmentCopyToResourceLibrary: + type: object + description: Copy the assignment to the EDU Resource Library + required: + - libraryParent + properties: + libraryParent: + type: string + description: Identifier of the parent resource where the new one will created, e.g. a folder id or `root` + example: + libraryParent: '0000000000000000' + AssignmentCopyToClass: type: object + description: Copy the assignment to a class + required: + - classroom properties: classroom: type: string @@ -5897,9 +6496,16 @@ components: If this one is specified, the assignment will only be listed to the teachers of the class. Alternatively the existing `scheduledDate` from the copied assignment will be used. format: date-time - description: Assignment copy operation example: classroom: '0000000000000000' + AssignmentCopyResponse: + allOf: + - $ref: '#/components/schemas/Assignment' + - type: object + properties: + resource: + type: string + description: If this assignment is stored as a resource in the Flat for Education Resource Library, the unique identifier of the resource. AssignmentType: type: string description: Type of the assignment @@ -5912,22 +6518,60 @@ components: - performance Assignment: type: object - properties: - state: - type: string - description: State of the assignment - enum: - - draft - - active - - archived + required: + - id + - type + - title + - attachments + - capabilities + properties: + id: + type: string + description: Unique identifier of the assignment type: $ref: '#/components/schemas/AssignmentType' + capabilities: + required: + - canEdit + - canPublishInClass + - canArchive + - canUnarchive + type: object + description: Capabilities the current user has on this assignment. Each capability corresponds to a fine-grained action that a user may take. + properties: + canEdit: + type: boolean + description: | + Whether the current user can edit the assignment + canPublishInClass: + type: boolean + description: | + Whether this assignment can be published in a class + canPublishInClassError: + type: object + required: + - code + - message + description: | + If `canPublishInClass` and `canEdit` are false, the issue why this assignment cannot be published in a class + properties: + code: + type: string + description: A corresponding code for this error + message: + type: string + description: A printable and localized message for this error + canArchive: + type: boolean + description: | + Whether the current user can archive the assignment + canUnarchive: + type: boolean + description: | + Whether the current user can unarchive the assignment title: type: string description: Title of the assignment - classroom: - type: string - description: The unique identifier of the class where this assignment was posted description: type: string description: Description and content of the assignment @@ -5941,75 +6585,36 @@ components: type: array items: $ref: '#/components/schemas/MediaAttachment' - submissions: - type: array - items: - $ref: '#/components/schemas/AssignmentSubmission' - creator: - type: string - description: | - The User unique identifier of the creator of this assignment - creationDate: - type: string - description: The creation date of this assignment - format: date-time - scheduledDate: - type: string - description: | - The publication (scheduled) date of the assignment. - If this one is specified, the assignment will only be listed to the teachers of the class. - format: date-time - dueDate: - type: string + useDedicatedAttachments: + type: boolean description: | - The due date of this assignment, late submissions will be marked as - paste due. - format: date-time + 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. maxPoints: type: number description: | If set, the grading will be enabled for the assignement - googleClassroom: - $ref: '#/components/schemas/GoogleClassroomCoursework' - microsoftGraph: - $ref: '#/components/schemas/MicrosoftGraphAssignment' - mfc: - type: object - description: A MusicFirst Classroom assignment - properties: - id: - type: string - description: Unique identifier of the course on MusicFirst Task - alternateLink: - type: string - description: Link to MusicFirst Classroom task - canvas: - type: object - description: A Canvas LMS assignment - properties: - id: - type: string - description: Unique identifier of the course on Canvas assignment - alternateLink: - type: string - description: Link to Canvas assignment - lti: - type: object - description: An LTI assignment - properties: - id: - type: string - description: Resource ID in the LMS + releaseGrades: + type: string + enum: [auto, manual] + description: | + For worksheets, how grading will work for the assignment: + - If set to `auto`, the grades will be automatically released when the student submits the submissions + - If set to `manual`, the grades will only be set as `draftGrade` and will be released when the teacher returns the submissions + shuffleExercises: + type: boolean + description: Mixing worksheets exercises for each student + toolset: + type: string + description: The id of the associated toolset + nbPlaybackAuthorized: + type: number + description: The number of playback authorized on the scores of the assignment. description: Assignment details example: + id: 636a724a89a6eaa0a54c3900 title: My first assignment description: Get started with Flat - state: active - creator: 5832bf149995c4024bd6de7d - classroom: 58c4725345cd836264f0b29e - creationDate: 2017-06-12T13:56:19.613000Z - dueDate: 2017-07-12T13:56:19.613000Z - scheduledDate: 2017-06-18T13:56:19.613000Z maxPoints: 100 attachments: - type: flat @@ -6026,29 +6631,143 @@ components: thumbnailWidth: 1868 authorName: Flat authorUrl: https://www.youtube.com/channel/UCEUIbEP9Rba_g0r4eeGhmXw - googleClassroom: - id: '1235665432' - alternateLink: http://classroom.google.com/c/music-theory/a/first-assignment/detail - lti: - id: '12345' - canvas: - id: '12345' - alternateLink: https://canvas.instructure.com/courses/00000/assignments/12345 - submissions: - - id: 58c4955c226ffff257211a90 + ClassAssignment: + allOf: + - $ref: '#/components/schemas/Assignment' + - type: object + required: + - state + - creationDate + - submissions + properties: + creator: + type: string + description: | + The User unique identifier of the creator of this assignment + state: + type: string + description: State of the assignment + enum: + - draft + - active + - archived + classroom: + type: string + description: The unique identifier of the class where this assignment was posted + creationDate: + type: string + description: The creation date of this assignment + format: date-time + scheduledDate: + type: string + description: | + The publication (scheduled) date of the assignment. + If this one is specified, the assignment will only be listed to the teachers of the class. + format: date-time + dueDate: + type: string + description: | + The due date of this assignment, late submissions will be marked as + paste due. + format: date-time + assigneeMode: + type: string + description: Possible modes of assigning assignments + enum: + - everyone + - selected + assignedStudents: + type: array + items: + type: string + description: Identifiers for the students that have access to the assignment + submissions: + type: array + items: + $ref: '#/components/schemas/AssignmentSubmission' + googleClassroom: + $ref: '#/components/schemas/GoogleClassroomCoursework' + microsoftGraph: + $ref: '#/components/schemas/MicrosoftGraphAssignment' + mfc: + type: object + description: A MusicFirst Classroom assignment + properties: + id: + type: string + description: Unique identifier of the course on MusicFirst Task + alternateLink: + type: string + description: Link to MusicFirst Classroom task + canvas: + type: object + description: A Canvas LMS assignment + properties: + id: + type: string + description: Unique identifier of the course on Canvas assignment + alternateLink: + type: string + description: Link to Canvas assignment + lti: + type: object + description: An LTI assignment + properties: + id: + type: string + description: Resource ID in the LMS + issue: + type: string + description: Detected issue for this assignment + example: + id: 636a724a89a6eaa0a54c3900 + title: My first assignment + description: Get started with Flat + state: active + creator: 5832bf149995c4024bd6de7d classroom: 58c4725345cd836264f0b29e - assignment: 58c49068524c03ec576ca43c - creator: 559eb5c7f0d4d5e46d03781d - creationDate: 2017-03-12T00:25:00.748000Z - submissionDate: 2017-03-12T00:25:22.748000Z + creationDate: 2017-06-12T13:56:19.613000Z + dueDate: 2017-07-12T13:56:19.613000Z + scheduledDate: 2017-06-18T13:56:19.613000Z + maxPoints: 100 attachments: - type: flat - score: 58c4955a226ffff257211a8d - title: Hello - Student + score: '0000000000000000' + - type: link + url: https://flat.io/developers + - type: video + url: https://www.youtube.com/watch?v=SNbRUiBZ4Uw + title: Flat - The online collaborative music notation software + description: Discover Flat on https://flat.io + html: + thumbnailUrl: https://i.ytimg.com/vi/SNbRUiBZ4Uw/maxresdefault.jpg + thumbnailHeight: 1052 + thumbnailWidth: 1868 + authorName: Flat + authorUrl: https://www.youtube.com/channel/UCEUIbEP9Rba_g0r4eeGhmXw googleClassroom: - id: CgsI-00000000000 - state: turned_in - alternateLink: http://classroom.google.com/c/music-theory/a/first-assignment/submissions/student/my-submission + id: '1235665432' + alternateLink: http://classroom.google.com/c/music-theory/a/first-assignment/detail + lti: + id: '12345' + canvas: + id: '12345' + alternateLink: https://canvas.instructure.com/courses/00000/assignments/12345 + submissions: + - id: 58c4955c226ffff257211a90 + classroom: 58c4725345cd836264f0b29e + assignment: 58c49068524c03ec576ca43c + creator: 559eb5c7f0d4d5e46d03781d + creationDate: 2017-03-12T00:25:00.748000Z + submissionDate: 2017-03-12T00:25:22.748000Z + attachments: + - type: flat + score: 58c4955a226ffff257211a8d + title: Hello - Student + googleClassroom: + id: CgsI-00000000000 + state: turned_in + alternateLink: http://classroom.google.com/c/music-theory/a/first-assignment/submissions/student/my-submission AssignmentSubmissionUpdate: type: object properties: @@ -6103,8 +6822,23 @@ components: - created - turnedIn - returned + AssignmentSubmissionHistoryState: + type: string + description: State of the submission history + enum: + - created + - turnedIn + - returned + - reset AssignmentSubmission: type: object + required: + - id + - state + - classroom + - assignment + - creator + - attachments properties: id: type: string @@ -6130,7 +6864,7 @@ components: $ref: '#/components/schemas/MediaAttachment' submissionDate: type: string - description: The date when the student submitted his work + description: The date when the student submitted their work returnDate: type: string description: The date when the teacher returned the work @@ -6228,8 +6962,15 @@ components: type: array items: type: string + source: + description: The source of the change if the change was made by a third-party software + type: string + enum: + - lti + - googleClassroom + - microsoftGraph state: - $ref: '#/components/schemas/AssignmentSubmissionState' + $ref: '#/components/schemas/AssignmentSubmissionHistoryState' draftGrade: type: number description: The numerator of the grade at this time in the submission grade history @@ -6239,6 +6980,13 @@ components: maxPoints: type: number description: The denominator of the grade at this time in the submission grade history + comment: + type: string + description: The comment that is made to this submission + dueDate: + type: string + description: The due date of this assignment + format: date-time attachment: type: object properties: @@ -6248,6 +6996,180 @@ components: revision: type: string description: The revision identifier that changed + title: + type: string + description: The title of the score that changed + EduLibrary: + description: A Flat for Education Library + type: object + properties: + id: + type: string + description: | + Unique identifier of the library. + + This one can be used to list the underlying resources using + `GET /v2/eduResources?parent={library-id}` + name: + type: string + description: Name of the lirbary + type: + type: string + description: Type of the library + enum: + - myResources + - flatEduSamples + visibility: + description: Visibility of the library + type: string + enum: + - private + - organization + - public + example: + id: root + name: My resources + visibility: private + EduResourcePrivacy: + type: string + description: | + The Education resource privacy mode. + default: private + enum: + - private + - public + EduResource: + description: A Flat for Education resource contained in a resources library + type: object + required: + - id + - type + - title + - capabilities + properties: + id: + type: string + description: Resource unique identifier + creator: + type: string + description: The User identifier of the resource creator + type: + $ref: '#/components/schemas/EduResourceType' + privacy: + $ref: '#/components/schemas/EduResourcePrivacy' + tags: + type: array + description: Specific attributes for the resource (e.g. sample resources with custom design) + items: + type: string + parent: + type: string + description: Identifier of the parent resource, e.g. a folder or root + title: + type: string + description: Title of the resource + creationDate: + type: string + format: date-time + description: The date when the resource was created + updateDate: + type: string + format: date-time + description: The date when the resource was updated + resource: + oneOf: + - $ref: '#/components/schemas/Assignment' + - $ref: '#/components/schemas/EduResourceFolder' + capabilities: + description: Capabilities available for this resource + type: object + properties: + canEdit: + type: boolean + description: | + Whether the current user can modify this resource + canAddResources: + type: boolean + description: | + Whether the current user can add resources within this resource (e.g. `assignment` inside a `folder`) + canAddFolders: + type: boolean + description: | + Whether the current user can add folders within this resource (e.g. `folder` inside `root`) + EduResourceCreation: + description: Creation of an education resource + type: object + required: + - type + - title + properties: + type: + $ref: '#/components/schemas/EduResourceType' + title: + type: string + description: Title of the resource + maxLength: 1000 + minLength: 1 + parent: + type: string + default: root + description: Identifier of the parent resource where the new one will created, e.g. a folder id or `root` + EduResourceUpdate: + description: Update of an education resource + type: object + properties: + title: + type: string + description: Title of the resource + maxLength: 1000 + minLength: 1 + EduResourceType: + description: Type of an education resource + type: string + enum: + - assignment + - folder + EduResourceFolder: + description: Education resources folder + type: object + properties: + title: + type: string + description: Title of the folder + EduResourceMove: + description: Move an education resource + type: object + required: + - destination + properties: + destination: + type: string + description: | + Unique identifier of the destination of the folder where to move this resource. + This can also be `root` to move the resource at the root of the user resource library. + EduResourceCopy: + description: Copy an education resource + type: object + required: + - destination + properties: + destination: + type: string + description: | + Unique identifier of the destination of the folder where to copy this resource. + This can also be `root` to copy the resource at the root of the user resource library. + EduResourceUseInClass: + description: Use an education resource in class + type: object + required: + - classroom + properties: + classroom: + type: string + description: The destination classroom where the resource will be copied. + assignment: + type: string + description: An optional destination assignment where the original assignement will be copied. Must be a draft. MicrosoftGraphAssignment: type: object description: A Microsoft Teams asignment @@ -6386,12 +7308,14 @@ components: - performance MediaAttachment: type: object + required: + - type properties: type: type: string description: | The type of the assignment resolved: - * `rich`, `photo`, `video` are attachment types that are automatically resolved from a `link` attachment. + * `rich`, `photo`, `video` are automatically resolved as `link` * A `flat` attachment is a score document where the unique identifier will be specified in the `score` property. Its sharing mode will be provided in the `sharingMode` property. enum: - rich @@ -6411,6 +7335,9 @@ components: worksheet: type: string description: An unique worksheet identifier + dedicated: + type: boolean + description: 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 track: type: string description: A unique track identifier @@ -6490,10 +7417,7 @@ components: description: Unique identifier of the task type: type: string - description: Type of the task - enum: - - audio-export - - audio-low-prio + description: Type of the task (e.g. audio-export) state: type: string description: State of the Task @@ -6503,6 +7427,12 @@ components: - done - canceled - error + format: + type: string + description: For files processing, the file format (e.g. `mp3`, `wav`) + score: + type: string + description: The score unique identifier for tasks related to scores progress: type: object description: Details about the task progression @@ -6525,16 +7455,34 @@ components: type: string description: The date when the task has been completed format: date-time + result: + type: object + description: Optional result information about this task + properties: + url: + description: URL returned by the task worker + type: string + error: + description: Error returned by task worker + type: string + errorHistory: + type: array + description: If any errors happened when processing this task, the list of errors identifiers + items: + type: string FlatErrorResponse: description: An API Error response type: object + required: + - code + - message properties: code: type: string description: A corresponding code for this error message: type: string - description: A printable message for this message + description: A printable message for this error id: type: string description: An unique error identifier generated for the request @@ -6545,6 +7493,34 @@ components: code: CLIENT_ERROR message: Invalid request id: '123456789' + UserCommunityProfileLinks: + type: object + description: Social networks links + properties: + spotifyUrl: + type: string + nullable: true + description: Spotify Profile URL + youtubeUrl: + type: string + nullable: true + description: YouTube channel URL + soundcloudUrl: + type: string + nullable: true + description: SoundCloud Profile URL + tiktokUrl: + type: string + nullable: true + description: TikTok profile URL. For updates, also accepts TikTok usernames + instagramUrl: + type: string + nullable: true + description: Instagram profile URL. For updates, also accepts Instagram usernames + websiteUrl: + type: string + nullable: true + description: Personnal website URL parameters: limit: name: limit