Flat API

Name: Flat API
Brand: Flat API
Availability: InStock

★ Only Publicly Available OpenAPI DocumentEducationLmsoauth281 EndpointsREST

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.

Jentic One on Github View OpenAPI Document

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.

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

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 instance

Jentic 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

GET STARTED

Start building with Flat API

Explore with Jentic One

View OpenAPI Document

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.

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.

Flat API

Connect the Flat API to your agent

Capabilities

Start building with Flat API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs