canonical: https://jentic.com/apis/flat.io/flat

# Flat API

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.

## For AI agents

Create, import, and export music scores; manage Flat for Education classes, assignments, and student submissions; and render notation to PDF, MIDI, or audio.

## Scope

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.

## Capabilities

- 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

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

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: Import a student MusicXML submission, render it to MP3, and post a feedback comment referencing measure 14

## Key endpoints

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

## Key resources

- **Score** — Create, import, export, and render music scores in multiple notation and audio formats
- **Class** — Create classes, manage enrollment, and post assignments for Flat for Education
- **Assignment** — Distribute notation tasks, archive completed work, and copy templates between classes
- **Submission** — Collect graded student work with per-submission comments and history
- **Collection** — Group scores into shared libraries with controlled member access
- **Organization** — Manage organization-level users, groups, and Flat for Education tenancy

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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

- **Google Classroom API** — Google Classroom hosts the wider class roster and grade book that Flat assignments feed into
- **SoundCloud API** — SoundCloud distributes the audio renders that Flat produces from a score
- **Spotify Web API** — Spotify exposes existing recordings rather than editable notation, so it is an alternative for listening-only flows

## FAQ

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