Flat API

Name: Flat API 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.

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.

Install Jentic One Beta (Self-Hosted)

Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | 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 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 API

Explore with Jentic

View OpenAPI Document

Jentic publishes the only available OpenAPI document for Flat API, keeping it validated and agent-ready.

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.

Use Cases

Patterns agents use Flat API 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

Why though Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

Flat OAuth 2.0 client secrets and refresh tokens are stored encrypted in the Jentic vault. Agents receive short-lived scoped access tokens at execution time, so raw secrets never enter the agent context.

Intent-based discovery

Agents search Jentic by intent such as 'import a music score' and Jentic returns the matching Flat operation with its input schema, so the agent can call the right endpoint without browsing the 81-endpoint surface.

Time to first call

Direct Flat integration: 2-4 days for OAuth setup, multipart upload handling, and async render polling. Through Jentic: under 1 hour to search, load the schema, and execute.

Related APIs

Alternatives and complements available in the Jentic catalogue.

Complementary

Google Classroom API

Google Classroom hosts the wider class roster and grade book that Flat assignments feed into

Choose Google Classroom when the agent needs to post grades back to a school's primary LMS after grading music assignments in Flat

Complementary

SoundCloud API

SoundCloud distributes the audio renders that Flat produces from a score

Use SoundCloud when the agent needs to publish the MP3 render of a Flat score to a public listening audience

Alternative

Spotify Web API

Spotify exposes existing recordings rather than editable notation, so it is an alternative for listening-only flows

Choose Spotify when the agent only needs reference recordings of a piece, not editable music notation

FAQs

Specific to using Flat API 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 sign up at https://app.jentic.com/sign-up.

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.