API Documentation
Digital Arabic Maqām Archive (DiArMaqAr) — programmatic access to historically documented maqāmāt, ajnās, and tuning systems spanning from al-Kindī (874 CE) to contemporary approaches.
Quick Start
Try this first:
curl "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents"Base URL: https://diarmaqar.net/api
Documentation Resources
For Humans
- Endpoints Reference - Complete endpoint documentation with parameters and responses
- Interactive Playground - Test API calls live in your browser
- Representative Examples - Recommended examples for proper API usage
For LLMs
- OpenAPI Specification: openapi.json | openapi.yaml
- LLM-optimized: llms.txt | llms-full.txt
API Endpoints
All API endpoints are organized by resource type. Each endpoint includes a link to detailed documentation with parameters, examples, and response formats.
Total: 27 endpoints across 7 resource categories.
Maqāmāt
Documented modal frameworks with historical source attribution.
Endpoints (8):
GET /maqamat- List all maqāmāt → DetailsGET /maqamat/families- List maqām families → DetailsGET /maqamat/{idName}- Get detailed maqām data → Details · Every maqām form in one requestGET /maqamat/{idName}/availability- Check maqām availability across tuning systems → DetailsGET /maqamat/{idName}/transpositions- List transpositions for a maqām → DetailsGET /maqamat/{idName}/compare- Compare maqām data across multiple tuning systems → DetailsGET /maqamat/classification/12-pitch-class-sets- Classify maqāmāt by 12-pitch-class sets → Details · Transpositions that do not fitGET /maqamat/classification/maqam-pitch-class-sets- Classify maqāmāt by maqam-based pitch class sets → Details
Ajnās
Documented tri/tetra/penta-chords with historical source attribution.
Endpoints (5):
GET /ajnas- List all ajnās → DetailsGET /ajnas/{idName}- Get detailed jins data → DetailsGET /ajnas/{idName}/availability- Check jins availability across tuning systems → DetailsGET /ajnas/{idName}/transpositions- List transpositions for a jins → DetailsGET /ajnas/{idName}/compare- Compare jins data across multiple tuning systems → Details
Tuning Systems
Historical tuning systems spanning from al-Kindī (874 CE) to contemporary approaches.
Endpoints (4):
GET /tuning-systems- List all tuning systems → DetailsGET /tuning-systems/{id}/{startingNote}/pitch-classes- Get tuning system details (pitch classes) → DetailsGET /tuning-systems/{id}/{startingNote}/maqamat- List maqāmāt available in a tuning system → DetailsGET /tuning-systems/{id}/{startingNote}/ajnas- List ajnās available in a tuning system → Details
Pitch Classes
Note names and pitch class data across all tuning systems.
Endpoints (4):
GET /pitch-classes/note-names- List all note names → DetailsGET /pitch-classes/note-names/{noteName}- Get pitch class details by note name → DetailsGET /pitch-classes/note-names/{noteName}/availability- Check note name availability across tuning systems → DetailsGET /pitch-classes/note-names/{noteName}/compare- Compare pitch class by note name across tuning systems → Details
Intervals
Calculate intervals between note names.
Endpoints (2):
GET /intervals- Calculate intervals by note names → DetailsGET /intervals/compare- Compare intervals across tuning systems → Details
Sources
Bibliographic sources documenting the historical foundation of the archive's musical data.
Endpoints (5):
GET /sources- List all bibliographic sources → DetailsGET /sources/{id}- Get a single bibliographic source → DetailsGET /sources/{id}/tuning-systems- List tuning systems by source → DetailsGET /sources/{id}/maqamat- List maqamat by source → DetailsGET /sources/{id}/ajnas- List ajnas by source → Details
Modulations
Modulation routes between maqāmāt using al-Shawwā's 1946 modulation guidelines.
Endpoints (1):
GET /modulation-routes- Find modulation routes between maqāmāt → Details
Statistics
What the archive holds, and for every tuning system on every starting note: the ajnās and maqāmāt it can build, their transpositions (taṣwīr) and octave renderings, and the modulations from base forms, transpositions and octave renderings.
Endpoints (1):
GET /statistics- Get archive statistics → Details
Identifiers of transpositions
A transposed maqām or jins has one idName, and every endpoint returns the same one. It is the base idName, then _al_, then the tonic's note-name idName:
| Display name | idName |
|---|---|
| maqām rāst al-qarār chahārgāh | maqam_rast_al_qarar_chahargah |
| jins segāh al-tīk ḥiṣār | jins_segah_al_tik_hisar |
| maqām ḥijāz (al-Ṣabbāgh/ʿAbbās) al-saham/ramal tūtī | maqam_hijaz_alsabbagh_abbas_al_saham_ramal_tuti |
The separator is always _al_. The "al" inside a base name is closed up, so it never looks like a separator: maqam_hijaz_alsabbagh_abbas and jins_buselik_alhilu are base names, not transpositions.
The base form is its bare idName (maqam_rast). A rendering an octave away from the base form, such as maqām rāst on qarār rāst, is not a taṣwīr (isTransposed: false, isBaseForm: false), but it still names its tonic: maqam_rast_al_qarar_rast.
So the idName in a maqām's availableTranspositions list is exactly the maqam.idName you get back when you request that transposition. The same idName appears in:
- each entry of
GET /maqamat/{idName}/transpositionsandGET /ajnas/{idName}/transpositions; - each entry of the
transpositionsarray thatincludeTranspositions=trueadds toGET /tuning-systems/{id}/{startingNote}/maqamatand.../ajnas; - the 12-pitch-class-set and maqām-pitch-class-set classifications;
- ajnās named inside maqām responses;
- modulation routes.
A classification set is named after one of its members, so its setIdName is that member's idName plus _set. A set that holds a base form is named after one (maqam_hijaz_kar_kurd_set); a set that holds none is named after a transposition (maqam_rast_al_kawasht_set). The rule is given in the 12-pitch-class sets endpoint description.
Using a transposed idName in the path
A transposed idName can go straight into the path. It means the same as the base idName with the tonic given separately:
| Path | Same as |
|---|---|
/maqamat/maqam_rast_al_qarar_chahargah | /maqamat/maqam_rast?transposeTo=qarar_chahargah |
/maqamat/maqam_rast_al_nawa/compare | /maqamat/maqam_rast/compare?transposeTo=nawa |
/maqamat/maqam_rast_al_nawa/availability | /maqamat/maqam_rast/availability?transpositionNoteName=nawa |
/ajnas/jins_segah_al_tik_hisar | /ajnas/jins_segah?transposeTo=tik_hisar |
You still pass the usual tuning-system and starting-note parameters. Whether a tonic is reachable depends on the tuning system and starting note, so a transposed idName that cannot be built there gets the same 400 as the matching transposeTo would.
Name the tonic once. A transposed idName together with a transposeTo (or transpositionNoteName) for a different tonic is a 400. Giving the same tonic both ways is fine.
/maqamat/{idName}/transpositions and /ajnas/{idName}/transpositions list every transposition, so they take the base idName only. A transposed idName there is a 400 whose hint names the base idName to use.
Older spelling. Until October 2026, some endpoints closed up the separator, spelling maqām rāst on qarār chahārgāh as maqam_rast_alqarar_chahargah. These were the base response's availableTranspositions, the compare endpoints, both classification endpoints (including set IDs), and modulation routes. Separately, a request with transposeTo set to a note an octave away from the base form (transposeTo=qarar_rast for maqām rāst) used to return the bare base idName and display name; it now returns maqam_rast_al_qarar_rast, matching the rest of the API. If you stored one of the closed-up IDs, it is still accepted wherever an idName is: in the path of every /maqamat/{idName} and /ajnas/{idName} route, and in the maqamId and setId filters on the classification endpoints. It is read as the current spelling. Responses use only the current spelling.
Ajnās an octave from their own tonic. Until November 2026, a jins found at a maqām degree an octave from its own tonic kept its bare base idName: jins yegāh on nawā came back as jins_yegah with isBaseForm: false. It now names its tonic like every other form, jins_yegah_al_nawa, the same idName the jins endpoints give it.
Lower-octave modulation targets. Until November 2026, a target in lowerOctaveModulations could carry a name no other endpoint used. Maqām yegāh on nawā, moved down an octave, came back as maqam_yegah_al_yegah, although it is maqām yegāh itself. Every lower-octave target is now the same form, with the same idName, that the listings and GET /maqamat/all give.
Every maqām form in one request
GET /maqamat/all describes every maqām a tuning system can build from a starting note, so a client does not need one GET /maqamat/{idName} call per form.
Each item in maqamat is exactly the body GET /maqamat/{idName} returns for that form with the same options, minus the envelope (parameters, context, links). The response carries the envelope once. Code that reads one maqām response can read each item unchanged.
| Parameter | Values | What it does |
|---|---|---|
forms | base (default), transpositions, all | The base form of each maqām, its transpositions (taṣwīr), or both |
includeOctaveRenderings | true / false | Also returns each maqām an octave from its base form, such as maqam_rast_al_qarar_rast. These are neither the base form nor a taṣwīr, and they appear as modulation targets |
fields | e.g. ajnas,primaryJins,modulations | Keeps only these top-level fields in each item. maqam is always kept. A field left out is not computed, so leaving out modulations, lowerOctaveModulations and stats skips the modulation analysis |
offset | integer | Where a page starts. Leave it out and follow next |
includeModulations, includeModulations8vb, includeIntervals, includeSuyur, includeArabic, pitchClassDataType and centsTolerance work as they do for one maqām.
Pages. A full analysis is larger than one response can be. For al-Fārābī (950g) from ʿushayrān, all 440 forms (101 base forms and 339 taṣwīr) with both kinds of modulation are about 25 MB. So the response is cut into pages of at most about 5 MB. total counts every selected form, count counts the forms on this page, and next is the URL of the next page, or null on the last one. Requests without modulations usually fit on one page.
# First page; then request each `next` URL until it is null
curl "https://diarmaqar.net/api/maqamat/all?tuningSystem=alfarabi_950g&startingNote=ushayran&forms=all&includeModulations=true&includeModulations8vb=true&pitchClassDataType=cents&fields=pitchData,ajnas,primaryJins,secondaryJins,tertiaryJins,ghammaz,modulations,lowerOctaveModulations"Every page is cached at the edge and carries an ETag, so a client can check for changes with If-None-Match and get a 304 when nothing changed.
Kinds of maqām and jins form
Every maqām and jins form in a response carries formType, read from the form itself:
formType | Meaning | Example |
|---|---|---|
base | The base form: the form on the tonic the sources give | maqām rāst on rāst, maqam_rast |
transposition | A taṣwīr: the form moved to another modal degree | maqām rāst on nawā, maqam_rast_al_nawa |
octaveRendering | The base form an octave or more away, on the same modal degree | maqām rāst on qarār rāst, maqam_rast_al_qarar_rast |
A form's idName is its identifier. It is unique within a tuning system and starting note, and the same form has the same idName in every response. formType is on the maqam of a maqām response, on the jins of a jins response, on every entry of ajnas, on modulation targets, in the listings, and as jinsFormType on the structural jins entries.
Listing every form. GET /tuning-systems/{id}/{startingNote}/maqamat and /ajnas take includeOctaveRenderings=true. Each entry then has an octaveRenderings array next to transpositions, with the same shape. The base forms, transpositions and octaveRenderings together are every form a maqām response can refer to. In al-Fārābī (950g) from ʿushayrān, the octave renderings add 206 maqām forms and 108 jins forms, such as maqām yegāh on nawā (maqam_yegah_al_nawa) and jins yegāh on nawā (jins_yegah_al_nawa). In a maqām response, availableOctaveRenderings lists them next to availableTranspositions. GET /maqamat/all with includeOctaveRenderings=true returns the full detail of each.
Structural ajnās and the ghammāz
The sources give each structural jins as a degree: maqām rāst has its primary jins on rāst and its secondary jins on nawā. primaryJins, secondaryJins and tertiaryJins name that degree and the first jins the archive finds starting on it in the ascending form. primaryJinsDescending, secondaryJinsDescending and tertiaryJinsDescending read the same degree in the descending form. The sources give one degree per slot, not a separate descending one, so the descending jins is the archive's match, not a source statement.
Each entry has a jinsStatus:
jinsStatus | Meaning |
|---|---|
matched | A jins in the archive starts on this degree |
noMatchingJins | The degree is in the maqām, but no jins in the archive starts there in this tuning system. Maqām lāmī, degree IV (nawā), is one. The jins fields are null |
degreeNotInMaqam | The stored degree is not one of the notes of this direction. maqamDegree and the jins fields are null |
Each direction is read on its own. Until November 2026, an ascending entry with no jins took the jins of the descending form instead.
Each ghammaz entry has intervalFromTonic: the interval from the tonic up to the ghammāz, as cents, fraction and decimalRatio. For maqām rāst the ghammāz is nawā, at 3/2 (702 cents). fraction is exact in tuning systems defined by ratios and an approximation in the others.
Citing sources
GET /sources and GET /sources/{id} give each source a citation: the authors' family names and the year, such as al-Shawwā 1946. A book with both an original and an edition year gives both: al-Khulaʿī 1904/2011. Two authors are joined with "and", three or more become "et al.". With includeArabic=true, citationAr gives the same in Arabic, with western digits: الشوا 1946. displayName is unchanged: it is an identifier, not a citation.
Transpositions that do not fit a 12-pitch-class set
GET /maqamat/classification/12-pitch-class-sets groups maqām transpositions into 12-pitch-class sets. A few transpositions cannot form one. For what that means, see Maqāmāt that cannot form a 12-pitch-class set. The endpoint never skips these transpositions silently. It reports each one, with the key and the pitch classes that need it.
Counts and lists
- Every response includes
statistics.incompatibleMaqamatCount, the number of transpositions in this tuning system, from this starting note, that do not fit. includeIncompatible=trueadds the full list inincompatibleMaqamat, with its count inincompatibleMaqamatCount.
Each transposition that does not fit
| Field | Description |
|---|---|
compatible | Always false |
reason | Always "shared_key": two or more pitch classes need the same key, and the keys next to it are taken. This replaces the former "duplicate_ipn_reference". |
explanation | One plain sentence, e.g. "ʿirāq (B-b2) and nīm kawasht (B-2) both need the B key, and the keys next to it are taken." |
clashes | One entry for each key that more than one pitch class needs |
clashes[].key | The key, e.g. "B" |
clashes[].notes | The notes that need that key. Each note has noteName (URL-safe), displayName, englishName, cents and centsInOctave. With includeArabic=true, each note also has displayNameAr. |
centsInOctave is the note's position above the transposition's tonic, with the octave ignored. It is the value the 12-pitch-class set compares. Two notes in the same clash with different centsInOctave values are different pitch classes competing for one key.
Filtering by maqām (maqamId)
- Some transpositions fit: the response has
compatible: trueand returns their sets as before. It addsincompatibleTranspositions, listing the transpositions that do not fit. - No transposition fits: the response is still
200. It hascompatible: false,sets: [],incompatibleTranspositions, and anexplanationof the form"No transposition of maqām X fits a 12-pitch-class set in <tuning system> from <starting note>." - The maqām cannot be built in this tuning system from this starting note (the tuning system lacks some of its notes): the response is still
200, withcompatible: false,sets: [], an emptyincompatibleTranspositionsand anexplanationsaying so. - The maqām does not exist: the response is
404.
maqamId accepts a maqām's idName, its numeric id, or the idName of one of its transpositions. It matches exactly: maqam_hijaz does not also match maqam_hijaz_kar. The older closed-up spelling of a transposition (maqam_rast_alqarar_chahargah) is also accepted. See Identifiers of transpositions.
Example
In al-Ṣabbāgh (1954) from rāst, maqām faraḥnāk (al-Ḥilū) on qarār segāh does not fit. ʿirāq (B-b2) and nīm kawasht (B-2) are 29.5 cents apart, and both need the B key. The keys next to it are taken: nīm ʿajam is on Bb and rāst is on C.
curl "https://diarmaqar.net/api/maqamat/classification/12-pitch-class-sets?tuningSystem=alsabbagh_1954&startingNote=rast&maqamId=maqam_farahnak_alhilu"The entry for that transposition in incompatibleTranspositions:
{
"maqam": {
"id": "145",
"idName": "maqam_farahnak_alhilu",
"displayName": "maqām faraḥnāk (al-Ḥilū)"
},
"transposition": {
"idName": "maqam_farahnak_alhilu_al_qarar_segah",
"displayName": "maqām faraḥnāk (al-Ḥilū) al-qarār segāh",
"isTransposed": true,
"isBaseForm": false
},
"compatible": false,
"reason": "shared_key",
"explanation": "ʿirāq (B-b2) and nīm kawasht (B-2) both need the B key, and the keys next to it are taken.",
"clashes": [
{
"key": "B",
"notes": [
{ "noteName": "iraq", "displayName": "ʿirāq", "englishName": "B-b2", "cents": -141.2, "centsInOctave": 701.9 },
{ "noteName": "nim_kawasht", "displayName": "nīm kawasht", "englishName": "B-2", "cents": -111.7, "centsInOctave": 731.4 }
]
}
]
}The two centsInOctave values, 701.9 and 731.4, differ by 29.5 cents. They are two pitch classes, and both need the B key.
Getting Started
All endpoints return JSON. No authentication required.
Common parameters:
includeArabic(default: "true") - Include Arabic script alongside transliterationincludeSources(default varies) - Include bibliographic source references
For complete parameter documentation, see the Endpoints Reference.
For recommended example values, see Representative Examples.