Flat API
Community OpenAPI document · agent-readyEducationLmsoauth281 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Create, import, and export music scores; manage Flat for Education classes, assignments, and student submissions; and render notation to PDF, MIDI, or audio.
Use for: I need to import a MusicXML file as a new Flat score, Export a score to PDF for printing in class, Create a new music assignment for a Flat class, List all student submissions for a given assignment
Not supported: Does not handle audio recording, music streaming distribution, or instrument tuning - use for music notation editing, score format conversion, and Flat for Education classroom workflows only.
The Flat API provides programmatic access to the Flat music notation platform, covering scores, collections, organizations, classes, assignments, and student submissions. It supports importing and exporting music notation in MusicXML, MIDI, Guitar Pro, MuseScore, PowerTab, and TuxGuitar formats, plus rendering scores to PDF, MP3, and image files. The Education endpoints expose classroom workflows including assignments, submissions, grading, and per-student histories for music teachers using Flat for Education.
Install Jentic One Beta
Connect the Flat API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Flat API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fflat.io%2Fflat" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fflat.io%2Fflat" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Flat API.
Import music scores from MusicXML, MIDI, Guitar Pro, PowerTab, TuxGuitar, and MuseScore files
Export scores to MusicXML, MIDI, MP3, WAV, PNG, or PDF for distribution and printing
Create classes, post assignments, and collect student score submissions through Flat for Education
Organize scores into collections and groups with shared edit and view permissions
Track per-student submission history and comment threads on graded assignments
Manage organization users, classes, and group memberships for school-wide deployments
Use Cases
Patterns agents use Flat API for, with concrete tasks.
★ Music classroom assignment grading
Music teachers using Flat for Education distribute notation assignments to students, collect submissions, and grade them through the API. Submissions can be exported as CSV or Excel rosters, and per-submission comment threads support iterative feedback. Endpoints under /classes/{class}/assignments handle the full lifecycle from posting an assignment to archiving it after grading.
Create an assignment in class C123 titled 'Bach Invention No. 1', wait for student submissions, then export the submission roster as CSV
Score format conversion pipeline
Convert music notation between MusicXML, MIDI, Guitar Pro, MuseScore, PowerTab, and TuxGuitar formats by uploading the source file and exporting the parsed Flat score in the target format. The same pipeline can render scores to PDF for print or MP3 for audio playback, supporting publisher and educator workflows that need consistent output across multiple formats.
Upload a MusicXML file, then export the resulting Flat score as both PDF and MP3
Collaborative score library management
Music groups, ensembles, and publishers can organize scores into shared collections and groups, controlling who can view or edit each score. The Collections and Groups endpoints support adding scores, listing members, and untrashing deleted items, which lets editorial teams maintain a single canonical library of arrangements and parts.
List all scores in collection C42, then move three specific scores to a different collection
AI agent music tutor integration
An AI tutor agent uses Flat through Jentic to import a student practice piece, render it to audio, and post structured feedback as comments on the student submission. Jentic's intent search returns the right Flat operation for each step so the agent does not have to browse the 81-endpoint surface manually.
Import a student MusicXML submission, render it to MP3, and post a feedback comment referencing measure 14
Key Endpoints
81 endpoints — the flat api provides programmatic access to the flat music notation platform, covering scores, collections, organizations, classes, assignments, and student submissions.
METHOD
PATH
DESCRIPTION
POST
/scores
Create or import a new score
GET
/scores/{score}
Retrieve score metadata and content
POST
/classes
Create a Flat for Education class
POST
/classes/enroll/{enrollmentCode}
Enroll the authenticated user into a class
GET
/classes/{class}/assignments
List assignments for a class
GET
/classes/{class}/assignments/{assignment}/submissions
List student submissions for an assignment
GET
/collections/{collection}/scores
List scores inside a collection
POST
/scores
Create or import a new score
GET
/scores/{score}
Retrieve score metadata and content
POST
/classes
Create a Flat for Education class
POST
/classes/enroll/{enrollmentCode}
Enroll the authenticated user into a class
GET
/classes/{class}/assignments
List assignments for a class
GET
/classes/{class}/assignments/{assignment}/submissions
List student submissions for an assignment
GET
/collections/{collection}/scores
List scores inside a collection
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Flat API by hand means running its OAuth2 flow for short-lived scoped tokens, spreading calls across 81 score, class, and collection endpoints, and handling retries yourself. Through Jentic you install once, import Flat from the API Directory, store the credential once, and your agent calls it.
Permission scoping
Flat puts the class id in the URL path (/classes/{class}/...), so a rule can pin your agent to one class: it can read that class's assignments and submissions and nothing else. You choose the operations it may call, so actions like creating scores or enrolling into classes are not included unless you add them.
Credential isolation
Your Flat OAuth2 credential is stored once, encrypted, by your own Jentic One instance and exchanged for a short-lived scoped token at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'import a music score' or 'list class assignments', and Jentic returns the matching Flat operation with its input schema so the agent calls the right one of 81 endpoints without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Flat API through Jentic.
What authentication does the Flat API use?
The Flat API uses OAuth 2.0 with scoped access tokens. Through Jentic, OAuth credentials are stored in the encrypted vault and exchanged for short-lived scoped tokens at execution time, so an agent never sees the raw client secret.
Can I import a MusicXML file with the Flat API?
Yes. POST a MusicXML, MIDI, Guitar Pro, PowerTab, TuxGuitar, or MuseScore file to /scores and Flat parses it into a structured score that can be re-exported in any of the supported formats.
How do I distribute and grade assignments through the Flat API?
Use /classes/{class}/assignments to post an assignment, then read /classes/{class}/assignments/{assignment}/submissions to collect graded work. Submissions support comment threads and CSV or Excel roster exports for record-keeping.
What are the rate limits for the Flat API?
Flat does not publish a single global rate limit in the spec; limits are applied per-endpoint and per-token. Treat 429 responses as the source of truth and back off using the Retry-After header.
How do I create a music score with the Flat API through Jentic?
Search Jentic for 'create a music score', load the schema for POST /scores, and execute the call with your MusicXML payload. Install Jentic with pip install jentic and run it through Jentic One, the self-hosted execution layer.
Is the Flat API free?
Read access for public scores is available on free tiers, but Flat for Education classroom endpoints and private score creation require a paid Flat plan. Confirm the current pricing on flat.io before integrating.
Can I limit what my agent is allowed to do with the Flat API?
Yes. Because you run Jentic One yourself, you decide which of Flat's 81 operations your agent may call and which credential it uses. Since Flat puts the class id in the URL path (/classes/{class}/...), a rule can pin the agent to a single class so it only reads that class's assignments and submissions and nothing else. Operations like creating scores at POST /scores or enrolling into a class are excluded unless you explicitly add them.
GET STARTED