Skip to content

API Endpoints Reference ​

Complete documentation for all API endpoints. For quick start, see API Documentation. For examples, see Representative Examples.


Quick Reference ​

Base URL ​

  • Production: https://diarmaqar.net/api
  • Development: http://localhost:3000/api

OpenAPI Specification ​

Machine-readable OpenAPI 3.1.0 specification:

Authentication ​

The API does not require authentication. All endpoints are publicly accessible.

Response Format ​

All API responses are in JSON format. List endpoints return:

json
{
  "count": <number>,
  "data": [<array>]
}

Rate Limiting ​

Currently, there are no rate limits. Please use the API responsibly.

Common Parameters ​

Most endpoints support these optional parameters:

  • includeArabic (default: "true"): Include Arabic script alongside transliteration

    • "true": Bilingual responses with *Ar suffixed fields (displayNameAr, noteNameDisplayAr, etc.)
    • "false": English transliteration only
  • includeSources (default: "true" for list endpoints, "false" for detail endpoints): Include bibliographic source references

    • "true": Include sources array with {sourceId, page} objects
    • "false": Omit source references for performance

Endpoints ​

Maqāmāt ​

Documented modal frameworks with historical source attribution.

List all maqāmāt ​

GET /maqamat

Retrieve all available maqāmāt with optional filtering and sorting.

Returns: All maqāmāt with their tuning system availability information. This endpoint does not include note names or pitch class data—only metadata about which tuning systems can realize each maqām.

Returns concise metadata including:

  • URL-safe identifiers and display names for each maqām
  • Maqām family and maqām tonic identifiers (both URL-safe and display formats)
  • Availability counts across tuning systems with their valid starting note names (e.g., "ʿushayrān", "yegāh" etc...)
  • Optional bibliographic source references (sourceId and page) when includeSources=true
  • Filter values must be URL-safe; see parameter enums for complete list of valid options

Note: For detailed pitch class data, note names, and ajnās information, use the /maqamat/{idName} endpoint.

Query Parameters:

  • filterByFamily (optional): Filter by maqām family name (URL-safe, case-insensitive, diacritics-insensitive). Use GET /maqamat/families to retrieve valid family values.. Use GET /maqamat/families to retrieve valid family values.
  • Type: string - Valid values: ajam, athar_kurd, awj_ara, bayyat, buselik, ... (16 total)
  • Example: rast
  • filterByTonic (optional): Filter by maqām tonic/first note (URL-safe, case-insensitive, diacritics-insensitive) - Type: string - Valid values: ajam_ushayran, chahargah, dugah, iraq, nawa, rast, segah, ushayran, yegah
  • sortBy (optional): Sort order for results. including empty string) return HTTP 400.
  • Type: string - Valid values: alphabetical, tonic - Default: alphabetical
  • Example: alphabetical - Sort alphabetically by display name (default)
  • Example: tonic - Sort by tonic note priority across the full NoteName.ts octave-stratified order, alphabetical tiebreak
  • includeSources (optional): Include bibliographic source references (sourceId and page) for each maqām - Type: string - Valid values: true, false - Default: false
    • Example: true
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/maqamat?includeSources=true&includeArabic=true"

Response: List of maqāmāt retrieved successfully

Example response — default:

json
{
  "count": 105,
  "data": [
    {
      "maqam": {
        "id": "102",
        "idName": "maqam_ajam_buselik",
        "displayName": "maqām ʿajam būselīk",
        "version": "2026-07-20T16:38:38.320Z"
      },
      "family": {
        "idName": "bayyat",
        "displayName": "bayyāt"
      },
      "tonic": {
        "idName": "dugah",
        "displayName": "dūgāh"
      },
      "stats": {
        "numberOfPitchClasses": 7,
        "availableInTuningSystems": 6
      },
      "characteristics": {
        "isOctaveRepeating": true,
        "hasAsymmetricDescending": true,
        "hasSuyur": true
      },
      "availability": {
        "tuningSystems": [
          {
            "tuningSystem": {
              "id": "alfarabi_950i",
              "idName": "alfarabi_950i",
              "displayName": "al-Fārābī (950i) Second Oud Tuning 22-Tone",
              "version": "2026-08-05T14:18:59.205Z"
            },
            "startingNotes": {
              "idNames": [
                "yegah"
              ],
              "displayNames": [
                "yegāh"
              ]
            }
          },
          {
            "tuningSystem": {
              "id": "alfarabi_950g",
              "idName": "alfarabi_950g",
              "displayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave) 27-Tone",
              "version": "2026-08-05T14:18:59.205Z"
            },
            "startingNotes": {
              "idNames": [
                "ushayran"
              ],
              "displayNames": [
                "ʿushayrān"
              ]
            }
          }
        ]
      },
      "links": {
        "detail": "https://diarmaqar.net/api/maqamat/maqam_ajam_buselik"
      }
    }
  ]
}

List maqām families ​

GET /maqamat/families

Retrieve maqām families for maqāmāt available in the specified tuning system. Families are classified by the first jins at scale degree 1. Use the maqamat link to filter maqāmāt by family via GET /maqamat?filterByFamily={idName}.

Query Parameters:

  • tuningSystem (required): Tuning system identifier (e.g., ibnsina_1037, alsabbagh_1954) - Type: string
    • Example: ibnsina_1037
  • startingNote (required): Starting note name (URL-safe, diacritics-insensitive) - Type: string
    • Example: yegah
  • includeArabic (optional): Include Arabic display names in family objects - Type: string - Valid values: true, false - Default: false
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/maqamat/families?tuningSystem=ibnsina_1037&startingNote=yegah&includeArabic=false"

Response: Maqām families retrieved successfully

Example response:

json
{
  "count": 16,
  "data": [
    {
      "family": {
        "idName": "rast",
        "displayName": "rāst"
      }
    },
    {
      "family": {
        "idName": "bayyat",
        "displayName": "bayyāt"
      }
    },
    {
      "family": {
        "idName": "hijaz",
        "displayName": "ḥijāz"
      }
    },
    {
      "family": {
        "idName": "ajam",
        "displayName": "ʿajam"
      }
    }
  ]
}

Get detailed maqām data ​

GET /maqamat/{idName}

Retrieve comprehensive data for a specific maqām on its conventional or a transposed tonic, in a specific tuning system on a specific starting note name.

Special Path Parameter Value:

  • The {idName} path parameter accepts the special value "all" to retrieve every maqām form a tuning system can build from a starting note, in one request
  • When using "all", both tuningSystem and startingNote query parameters are required
  • Each item of maqamat is exactly the body this endpoint returns for that form with the same options, without the envelope (parameters, context, links), which the bulk response carries once
  • forms chooses the base forms (default), their transpositions (taṣwīr), or both; includeOctaveRenderings=true adds the octave-register renderings (e.g. maqam_rast_al_qarar_rast), which are neither
  • fields keeps only the named top-level fields of each item (maqam is always kept) and skips the work for the others
  • Responses are paged by size: a page holds at most about 5 MB of items. total counts every selected form, count the forms on this page, and next is the URL of the next page (null on the last). Follow next until it is null

Returns:

  • Comprehensive pitch class data in the requested tuning system and starting note name
  • All ajnās present at each maqām degree in the ascending and descending maqām structure, keyed by each degree's URL-safe noteName (the same value as pitchData[].noteName, e.g. segah)
  • The maqām's primary, secondary, and (when defined) tertiary jins positions as transposed per-degree entries — each carrying the note name, maqām degree (roman numeral), and the resolved jins entity {jinsId, jinsIdName, jinsDisplayName}
  • The maqām's ghammāz (modulation emphasis note) as a note-name + maqām-degree entry (no jins fields — the ghammāz is a melodic-emphasis note, not a jins)
  • All four of primaryJins, secondaryJins, tertiaryJins, and ghammaz are transposed in sync with the selected transposition (e.g. when transposeTo=nawa is used, every entry reflects the new tonic and the new maqām-degree position of each note). They are returned as arrays of per-degree objects to accommodate alternatives, or null when a maqām has no entry for that slot (e.g. rāst has no tertiary).
  • Optional includeIntervals data, transposition to different tonics, tuning-system-specific modulations (including lower octave), and suyūr

Parameter Discovery:

  • Use options=true to discover valid values for all parameters including dynamically calculated transposition options
  • Especially useful for finding valid tuning system starting notes and transposition tonics for a specific maqām

Important:

  • When options=true, the endpoint returns parameter discovery metadata instead of maqām data
  • This mode is mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, include suyūr, pitch class data type, includeIntervals)
  • If data-returning parameters are provided with options=true, the API returns a 400 Bad Request error with details about conflicting parameters

Requirements:

  • Tuning system is required for all requests; a starting note is required for data retrieval and optional in discovery mode (options=true), where omitting it returns the tuning system's valid starting notes
  • These are fundamental to all pitch class calculations

Path Parameters:

  • idName: URL-safe maqām identifier: A maqām's idName (maqam_rast), its numeric id, or the idName of one of its transpositions (maqam_rast_al_qarar_chahargah). A transposed idName works like adding transposeTo for its tonic; giving it together with a different transposeTo is a 400. The older closed-up spelling (maqam_rast_alqarar_chahargah) is also accepted.

Special value: Use "all" to retrieve every maqām form in a specific tuning system and starting note at once (see forms, includeOctaveRenderings, fields and offset). When using "all", both tuningSystem and startingNote query parameters are required. (string) (required)

  • Example: maqam_rast - Maqām Rāst (representative example)
  • Example: maqam_bayyat - Maqām Bayyāt (representative example)
  • Example: maqam_saba - Maqām Ṣabā (representative example)
  • Example: all - All maqāmāt (requires tuningSystem and startingNote query parameters)

Query Parameters:

  • tuningSystem (required): Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899') - Type: string
    • Example: ibnsina_1037 - Ibn Sīnā (1037) - 7-Fret Oud 17-Tone (representative example)
    • Example: alfarabi_950g - al-Fārābī (950g) - First Oud Tuning 27-Tone (representative example)
  • startingNote (required): Tuning system starting note name (URL-safe, diacritics-insensitive).
    • Different starting notes represent different theoretical frameworks within the same tuning system
    • Use yegah for IbnSina/Meshshaqa, ushayran for al-Farabi/al-Kindi, rast for CairoCongress/al-Sabbagh
  • Type: string
  • Example: yegah - yegāh (for IbnSina, Meshshaqa)
  • Example: ushayran - ʿushayrān (for al-Farabi, al-Kindi)
  • options (optional): When true, returns available parameter options instead of maqām data.
    • Tuning system is required for all requests; a starting note is required for data retrieval and optional in discovery mode (options=true), where omitting it returns the tuning system's valid starting notes
    • These are fundamental to all pitch class calculations and calculate valid starting note options and transposition tonics
    • Mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, include suyūr, pitch class data type, includeIntervals)
    • Transposition options are dynamically calculated based on the specific maqām, tuning system, and starting note combination
    • Only tonics where the maqām can be validly transposed (preserving interval pattern) are included, not all possible pitch classes
    • If data-returning parameters are provided, returns 400 Bad Request error with details about conflicting parameters
  • Type: string - Valid values: true, false - Default: false
  • pitchClassDataType (optional): Specifies which pitch class data type to return for each pitch class.
    • When provided, returns the specified data type for all pitch classes in the maqām
    • In discovery mode (when options=true), this parameter is optional since the response returns parameter metadata instead of formatted data
    • Use 'all' for complete pitch class data across all available formats
    • pitchClassIndex and scaleDegree return the minimal field set explicitly
  • Type: string - Valid values: all, abjadName, englishName, solfege, fraction, ... (16 total)
  • Example: cents
  • transposeTo (optional): Transpose the maqām to a new tonic by preserving the interval patterns (URL-safe, diacritics-insensitive).
    • To see all valid transposition options, request available parameter options instead of maqām data
  • Type: string
  • includeIntervals (optional): Include interval data between maqām degrees - Type: string - Valid values: true, false - Default: false
    • Example: true
  • includeModulations (optional): Include modulation possibilities to other maqāmāt and ajnās - Type: string - Valid values: true, false - Default: false
    • Example: true
  • includeModulations8vb (optional): Include available modulations an octave below - Type: string - Valid values: true, false - Default: false
    • Example: true
  • includeSuyur (optional): Include the suyūr (melodic paths) that can be played on the maqām form requested, each moved onto that form. each moved onto that form. See suyur in the response.
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5
  • forms (optional): Only with idName all.
    • transpositions: every transposition (taṣwīr) of each maqām in this tuning system and starting note
    • all: both, the base form of each maqām followed by its transpositions
  • Type: string - Valid values: base, transpositions, all - Default: base
  • includeOctaveRenderings (optional): Only with idName all. same maqām an octave from its base form (e.g. maqam_rast_al_qarar_rast). They are neither the base form nor a transposition, and they appear as modulation targets.
  • Type: string - Valid values: true, false - Default: false
  • fields (optional): Only with idName all. ajnas,primaryJins,modulations. maqam is always kept. A field left out is not computed, so leaving out modulations, lowerOctaveModulations and stats skips the modulation analysis. Unknown or empty values are a 400. Valid fields: family, tonic, transposition, stats, characteristics, availableTranspositions, availableOctaveRenderings, comments, sources, pitchData, intervals, ajnas, primaryJins, secondaryJins, tertiaryJins, primaryJinsDescending, secondaryJinsDescending, tertiaryJinsDescending, ghammaz, suyur, modulations, lowerOctaveModulations.
  • Type: string
  • offset (optional): Only with idName all. out for the first page, then follow the next URL of each response, which sets it. A negative, fractional or too large value is a 400.
  • Type: integer - Default: 0

Example:

bash
curl "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&includeArabic=true"

Response: Maqām data retrieved successfully.

  • With idName all, the response is a MaqamBulkResponse: one page of maqām forms, each shaped as below without parameters, context and links
  • When options is true, the response structure differs and returns available parameter options instead of maqām data
  • In that case, transposition options contain only valid transposition tonics for this specific maqām, tuning system, and starting note combination

Example response — basic:

json
{
  "maqam": {
    "id": "1",
    "idName": "maqam_rast",
    "displayName": "maqām rāst",
    "version": "2026-08-11T19:43:52.080Z",
    "isBaseForm": true,
    "formType": "base"
  },
  "family": {
    "idName": "rast",
    "displayName": "rāst"
  },
  "tonic": {
    "idName": "rast",
    "displayName": "rāst"
  },
  "stats": {
    "numberOfTranspositions": 3,
    "numberOfPitchClasses": 7,
    "numberOfMaqamModulations": 79,
    "numberOfAjnasModulations": 49
  },
  "characteristics": {
    "isOctaveRepeating": true,
    "hasAsymmetricDescending": true,
    "hasSuyur": true
  },
  "availableTranspositions": [
    {
      "idName": "maqam_rast_al_qarar_chahargah",
      "displayName": "maqām rāst al-qarār chahārgāh",
      "formType": "transposition",
      "tonic": {
        "idName": "qarar_chahargah",
        "displayName": "qarār chahārgāh"
      }
    },
    {
      "idName": "maqam_rast_al_chahargah",
      "displayName": "maqām rāst al-chahārgāh",
      "formType": "transposition",
      "tonic": {
        "idName": "chahargah",
        "displayName": "chahārgāh"
      }
    },
    {
      "idName": "maqam_rast_al_mahuran",
      "displayName": "maqām rāst al-māhūrān",
      "formType": "transposition",
      "tonic": {
        "idName": "mahuran",
        "displayName": "māhūrān"
      }
    }
  ],
  "availableOctaveRenderings": [
    {
      "idName": "maqam_rast_al_qarar_rast",
      "displayName": "maqām rāst al-qarār rāst",
      "formType": "octaveRendering",
      "tonic": {
        "idName": "qarar_rast",
        "displayName": "qarār rāst"
      }
    },
    {
      "idName": "maqam_rast_al_kurdan",
      "displayName": "maqām rāst al-kurdān",
      "formType": "octaveRendering",
      "tonic": {
        "idName": "kurdan",
        "displayName": "kurdān"
      }
    }
  ],
  "comments": {
    "english": "This maqām's data is compiled from al-Shawwā (1946, p.42), al-Ṣabbāgh (1950, p.41) and al-Ḥilū (1961, p.107). The sources agree on the scale in both directions: al-Ḥilū's construction runs two identical disjunct octaves, rāst to jawāb kurdān, and his printed note against awj, \"and in the descent it is substituted by ʿajam\", independently reproduces al-Shawwā's descending ʿajam; his ḥusaynī row is annotated \"to make būselīk on nawā\" (1961, p.107). On the maqām's character: \"it rests on presenting the jins rāst on the two degrees nawā and yegāh\" (1961, p.107), agreeing with the ghammāz nawā assigned here. His footnote explains the maqām's canonical standing: \"this maqām rāst is composed of the succession of the natural tonal degrees, as we indicated earlier; for that disposition, and because from each of these eight notes, that is its degrees, an Arab maqām standing in its own right is composed, it has been considered the fundamental scale in Arab music. In view of this standing of it, we ought to have presented it in analysis and notation before the other maqāms, were it not that the necessity of our ordering the maqāms in this book according to the degrees of their finals, from the deepest note upwards in sequence, made us fix it here in its rank, that is, in the centre of the tonal register on which it rests\" (1961, p.107).",
    "arabic": "جُمعت بيانات هذا المقام من الشوا (1946، ص42) والصباغ (1950، ص41) والحلو (1961، ص107). تتفق المصادر على السلّم في الاتجاهين: تكوين الحلو ديوانان منفصلان متطابقان من الراست الى جواب الكردان، وملاحظته المطبوعة عند الاوج «وفي الهبوط يستبدل بالعجم» تعيد باستقلال انتاج العجم في هبوط الشوا؛ وصف الحسيني عنده معلّم «لعمل بوسليك على النوا» (1961، ص107). عن شخصية المقام: «تقوم على اظهار جنس الراست على درجتي النوا واليكاه» (1961، ص107)، بما يوافق الغماز النوا المعتمد هنا. تشرح حاشيته مكانة المقام: «ان مقام الراست هذا يتألف من تتابع الدرجات الصوتية الطبيعية كما اشرنا سابقاً ، فهو لذلك الوضع ولكون اصواته أي درجاته الثمانية هــذه يتألف من كل منها مقام عربي قائم في ذاته . قد اعتبر السلم الاساسي في الموسيقى العربية . ونظراً لمقامه هذا ، فقد كان يجب علينا ان نقدمه في التحليل والتدوين على سواه من المقامات لولا ان وجوب ترتيبنا وضع المقامات في هذا الكتاب بحسب درجات ارتكازاتها من اغلظ صوت الى ما فوقه حدّةً على التوالي جعلنا نثبته هنا في صفه ، اي في مركز طبقته الصوتية التي يستقر عليها» (1961، ص107)."
  },
  "sources": [
    {
      "sourceId": "alshawwa_1946",
      "page": "42"
    },
    {
      "sourceId": "alhilu_1961",
      "page": "107"
    },
    {
      "sourceId": "abbas_1986",
      "page": "30/36/91"
    }
  ],
  "parameters": {
    "pitchClassDataType": null,
    "includeIntervals": false,
    "includeModulations": false,
    "includeModulations8vb": false,
    "includeSuyur": false,
    "transposeTo": null,
    "centsTolerance": 5
  },
  "context": {
    "tuningSystem": {
      "id": "ibnsina_1037",
      "idName": "ibnsina_1037",
      "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
      "version": "2026-08-16T22:20:52.549Z",
      "startingNotes": {
        "idNames": [
          "ushayran",
          "yegah",
          "rast"
        ],
        "displayNames": [
          "ʿushayrān",
          "yegāh",
          "rāst"
        ]
      },
      "selectedStartingNote": {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      "pitchClassCounts": {
        "singleOctave": 17,
        "allOctaves": 68
      },
      "originalValueType": "fraction",
      "referenceFrequency": 98
    }
  },
  "links": {
    "self": "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah",
    "detail": "https://diarmaqar.net/api/maqamat/maqam_rast",
    "availability": "https://diarmaqar.net/api/maqamat/maqam_rast/availability",
    "compare": "https://diarmaqar.net/api/maqamat/maqam_rast/compare"
  },
  "pitchData": {
    "ascending": [
      {
        "pitchClassIndex": 7,
        "octave": 1,
        "scaleDegree": "I",
        "noteName": "rast",
        "noteNameDisplay": "rāst"
      },
      {
        "pitchClassIndex": 10,
        "octave": 1,
        "scaleDegree": "II",
        "noteName": "dugah",
        "noteNameDisplay": "dūgāh"
      },
      {
        "pitchClassIndex": 12,
        "octave": 1,
        "scaleDegree": "III",
        "noteName": "segah",
        "noteNameDisplay": "segāh"
      },
      {
        "pitchClassIndex": 14,
        "octave": 1,
        "scaleDegree": "IV",
        "noteName": "chahargah",
        "noteNameDisplay": "chahārgāh"
      },
      {
        "pitchClassIndex": 0,
        "octave": 2,
        "scaleDegree": "V",
        "noteName": "nawa",
        "noteNameDisplay": "nawā"
      },
      {
        "pitchClassIndex": 3,
        "octave": 2,
        "scaleDegree": "VI",
        "noteName": "husayni",
        "noteNameDisplay": "ḥusaynī"
      },
      {
        "pitchClassIndex": 5,
        "octave": 2,
        "scaleDegree": "VII",
        "noteName": "awj",
        "noteNameDisplay": "awj"
      }
    ],
    "descending": [
      {
        "pitchClassIndex": 4,
        "octave": 2,
        "scaleDegree": "VII",
        "noteName": "ajam",
        "noteNameDisplay": "ʿajam"
      },
      {
        "pitchClassIndex": 3,
        "octave": 2,
        "scaleDegree": "VI",
        "noteName": "husayni",
        "noteNameDisplay": "ḥusaynī"
      },
      {
        "pitchClassIndex": 0,
        "octave": 2,
        "scaleDegree": "V",
        "noteName": "nawa",
        "noteNameDisplay": "nawā"
      },
      {
        "pitchClassIndex": 14,
        "octave": 1,
        "scaleDegree": "IV",
        "noteName": "chahargah",
        "noteNameDisplay": "chahārgāh"
      },
      {
        "pitchClassIndex": 12,
        "octave": 1,
        "scaleDegree": "III",
        "noteName": "segah",
        "noteNameDisplay": "segāh"
      },
      {
        "pitchClassIndex": 10,
        "octave": 1,
        "scaleDegree": "II",
        "noteName": "dugah",
        "noteNameDisplay": "dūgāh"
      },
      {
        "pitchClassIndex": 7,
        "octave": 1,
        "scaleDegree": "I",
        "noteName": "rast",
        "noteNameDisplay": "rāst"
      }
    ]
  },
  "ajnas": {
    "ascending": {
      "rast": [
        {
          "id": "19",
          "idName": "jins_rast",
          "displayName": "jins rāst",
          "isBaseForm": true,
          "formType": "base"
        },
        {
          "id": "32",
          "idName": "jins_yegah_al_rast",
          "displayName": "jins yegāh al-rāst",
          "isBaseForm": false,
          "formType": "transposition"
        }
      ],
      "dugah": [
        {
          "id": "2",
          "idName": "jins_bayyat",
          "displayName": "jins bayyāt",
          "isBaseForm": true,
          "formType": "base"
        }
      ],
      "segah": [
        {
          "id": "3",
          "idName": "jins_segah_alhilu",
          "displayName": "jins segāh (al-Ḥilū)",
          "isBaseForm": true,
          "formType": "base"
        },
        {
          "id": "52",
          "idName": "jins_mayeh_al_segah",
          "displayName": "jins māyeh al-segāh",
          "isBaseForm": false,
          "formType": "transposition"
        },
        {
          "id": "16",
          "idName": "jins_segah",
          "displayName": "jins segāh",
          "isBaseForm": true,
          "formType": "base"
        },
        {
          "id": "36",
          "idName": "jins_farahnak_al_segah",
          "displayName": "jins faraḥnāk al-segāh",
          "isBaseForm": false,
          "formType": "transposition"
        }
      ],
      "chahargah": [
        {
          "id": "41",
          "idName": "jins_mahran_al_chahargah",
          "displayName": "jins mahrān al-chahārgāh",
          "isBaseForm": false,
          "formType": "transposition"
        }
      ],
      "nawa": [
        {
          "id": "19",
          "idName": "jins_rast_al_nawa",
          "displayName": "jins rāst al-nawā",
          "isBaseForm": false,
          "formType": "transposition"
        },
        {
          "id": "32",
          "idName": "jins_yegah_al_nawa",
          "displayName": "jins yegāh al-nawā",
          "isBaseForm": false,
          "formType": "octaveRendering"
        }
      ],
      "husayni": [
        {
          "id": "2",
          "idName": "jins_bayyat_al_husayni",
          "displayName": "jins bayyāt al-ḥusaynī",
          "isBaseForm": false,
          "formType": "transposition"
        }
      ],
      "awj": [
        {
          "id": "51",
          "idName": "jins_awj",
          "displayName": "jins awj",
          "isBaseForm": true,
          "formType": "base"
        },
        {
          "id": "26",
          "idName": "jins_iraq_al_awj",
          "displayName": "jins ʿirāq al-awj",
          "isBaseForm": false,
          "formType": "octaveRendering"
        },
        {
          "id": "16",
          "idName": "jins_segah_al_awj",
          "displayName": "jins segāh al-awj",
          "isBaseForm": false,
          "formType": "transposition"
        }
      ]
    },
    "descending": {
      "ajam": [
        {
          "id": "41",
          "idName": "jins_mahran_al_ajam",
          "displayName": "jins mahrān al-ʿajam",
          "isBaseForm": false,
          "formType": "octaveRendering"
        }
      ],
      "husayni": [
        {
          "id": "7",
          "idName": "jins_kurd_al_husayni",
          "displayName": "jins kurd al-ḥusaynī",
          "isBaseForm": false,
          "formType": "transposition"
        }
      ],
      "nawa": [
        {
          "id": "22",
          "idName": "jins_buselik_alhilu_al_nawa",
          "displayName": "jins būselīk (al-Ḥilū) al-nawā",
          "isBaseForm": false,
          "formType": "transposition"
        },
        {
          "id": "6",
          "idName": "jins_nahawand_al_nawa",
          "displayName": "jins nahāwand al-nawā",
          "isBaseForm": false,
          "formType": "transposition"
        }
      ],
      "chahargah": [
        {
          "id": "5",
          "idName": "jins_ajam_ushayran_al_chahargah",
          "displayName": "jins ʿajam ʿushayrān al-chahārgāh",
          "isBaseForm": false,
          "formType": "transposition"
        },
        {
          "id": "31",
          "idName": "jins_chahargah",
          "displayName": "jins chahārgāh",
          "isBaseForm": true,
          "formType": "base"
        }
      ],
      "segah": [
        {
          "id": "3",
          "idName": "jins_segah_alhilu",
          "displayName": "jins segāh (al-Ḥilū)",
          "isBaseForm": true,
          "formType": "base"
        },
        {
          "id": "52",
          "idName": "jins_mayeh_al_segah",
          "displayName": "jins māyeh al-segāh",
          "isBaseForm": false,
          "formType": "transposition"
        },
        {
          "id": "16",
          "idName": "jins_segah",
          "displayName": "jins segāh",
          "isBaseForm": true,
          "formType": "base"
        },
        {
          "id": "36",
          "idName": "jins_farahnak_al_segah",
          "displayName": "jins faraḥnāk al-segāh",
          "isBaseForm": false,
          "formType": "transposition"
        }
      ],
      "dugah": [
        {
          "id": "2",
          "idName": "jins_bayyat",
          "displayName": "jins bayyāt",
          "isBaseForm": true,
          "formType": "base"
        }
      ],
      "rast": [
        {
          "id": "19",
          "idName": "jins_rast",
          "displayName": "jins rāst",
          "isBaseForm": true,
          "formType": "base"
        },
        {
          "id": "32",
          "idName": "jins_yegah_al_rast",
          "displayName": "jins yegāh al-rāst",
          "isBaseForm": false,
          "formType": "transposition"
        }
      ]
    }
  },
  "primaryJins": [
    {
      "noteName": "rast",
      "noteNameDisplay": "rāst",
      "maqamDegree": "I",
      "jinsStatus": "matched",
      "jinsId": "19",
      "jinsIdName": "jins_rast",
      "jinsDisplayName": "jins rāst",
      "jinsIsBaseForm": true,
      "jinsFormType": "base"
    }
  ],
  "primaryJinsDescending": [
    {
      "noteName": "rast",
      "noteNameDisplay": "rāst",
      "maqamDegree": "I",
      "jinsStatus": "matched",
      "jinsId": "19",
      "jinsIdName": "jins_rast",
      "jinsDisplayName": "jins rāst",
      "jinsIsBaseForm": true,
      "jinsFormType": "base"
    }
  ],
  "secondaryJins": [
    {
      "noteName": "nawa",
      "noteNameDisplay": "nawā",
      "maqamDegree": "V",
      "jinsStatus": "matched",
      "jinsId": "19",
      "jinsIdName": "jins_rast_al_nawa",
      "jinsDisplayName": "jins rāst al-nawā",
      "jinsIsBaseForm": false,
      "jinsFormType": "transposition"
    }
  ],
  "secondaryJinsDescending": [
    {
      "noteName": "nawa",
      "noteNameDisplay": "nawā",
      "maqamDegree": "V",
      "jinsStatus": "matched",
      "jinsId": "22",
      "jinsIdName": "jins_buselik_alhilu_al_nawa",
      "jinsDisplayName": "jins būselīk (al-Ḥilū) al-nawā",
      "jinsIsBaseForm": false,
      "jinsFormType": "transposition"
    }
  ],
  "tertiaryJins": null,
  "tertiaryJinsDescending": null,
  "ghammaz": [
    {
      "noteName": "nawa",
      "noteNameDisplay": "nawā",
      "maqamDegree": "V",
      "intervalFromTonic": {
        "cents": 701.9550008653875,
        "fraction": "3/2",
        "decimalRatio": 1.5
      }
    }
  ]
}

Check maqām availability across tuning systems ​

GET /maqamat/{idName}/availability

Return tuning-system availability for a maqām.

  • Shows which tuning systems on which starting note names can realize the specified maqām
  • If transpositionNoteName is provided, filters results to show only tuning systems where the maqām can be transposed to that specific note
  • Validity is computed against each tuning system's note name sets and the maqām's pitch class intervals
  • Tuning system starting note names are returned as both display values (with diacritics) and URL-safe identifiers

Path Parameters:

  • idName: URL-safe maqām identifier: A maqām's idName (maqam_rast), its numeric id, or the idName of one of its transpositions (maqam_rast_al_nawa). A transposed idName works like transpositionNoteName for its tonic; giving it together with a different transpositionNoteName is a 400. The older closed-up spelling is also accepted. (string) (required)
    • Example: maqam_bayyat

Query Parameters:

  • transpositionNoteName (optional): Filter results to show only tuning systems where the maqām can be transposed to this specific note (URL-safe, diacritics-insensitive). - Type: string
    • Example: nawa
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/maqamat/maqam_bayyat/availability?includeArabic=true"

Response: Availability information retrieved successfully

Example response — withoutTransposition:

json
{
  "maqam": {
    "id": "1",
    "idName": "maqam_rast",
    "displayName": "Maqam Rāst",
    "version": "2025-10-18T19:41:17.132Z"
  },
  "availability": {
    "count": 29,
    "tuningSystems": [
      {
        "tuningSystemId": "ibnsina_1037",
        "tuningSystemDisplayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
        "tuningSystemStartingNoteNames": [
          "ʿushayrān",
          "yegāh"
        ],
        "tuningSystemStartingNoteNamesIds": [
          "ushayran",
          "yegah"
        ]
      },
      {
        "tuningSystemId": "alfarabi_950g",
        "tuningSystemDisplayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave)",
        "tuningSystemStartingNoteNames": [
          "ʿushayrān",
          "yegāh"
        ],
        "tuningSystemStartingNoteNamesIds": [
          "ushayran",
          "yegah"
        ]
      }
    ]
  }
}

List transpositions for a maqām ​

GET /maqamat/{idName}/transpositions

Lists distinct transpositions (taswīr) for a maqām within a specific tuning system and starting note. The base form is excluded. Octave renderings of the same modal degree (e.g. qarār dūgāh vs dūgāh vs muḥayyar) are not treated as distinct taswīr.

If there are no distinct taswīr for this tuning-system + starting-note combination, this endpoint returns 422 with an { error, hint } payload (it does not return a 200 with an empty list).

Path Parameters:

  • idName: URL-safe maqām identifier: A maqām's idName (maqam_rast) or its numeric id. This route lists every transposition of the maqām, so the idName of a single transposition (maqam_rast_al_nawa) is rejected with a 400 that names the base idName to use. (string) (required)
    • Example: maqam_rast

Query Parameters:

  • tuningSystem (required): Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899') - Type: string
    • Example: ibnsina_1037
  • startingNote (required): Tuning system starting note name (URL-safe, diacritics-insensitive). - Type: string
    • Example: yegah
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/maqamat/maqam_rast/transpositions?tuningSystem=ibnsina_1037&startingNote=yegah&includeArabic=true"

Response: Transpositions retrieved successfully

Example response:

json
{
  "maqam": {
    "id": "1",
    "idName": "maqam_rast",
    "displayName": "maqām rāst",
    "version": "2026-08-11T19:43:52.080Z",
    "isBaseForm": true,
    "formType": "base"
  },
  "tuningSystem": {
    "id": "ibnsina_1037",
    "idName": "ibnsina_1037",
    "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
    "version": "2026-08-16T22:20:52.549Z",
    "numberOfPitchClassesSingleOctave": 17
  },
  "startingNote": {
    "idName": "yegah",
    "displayName": "yegāh"
  },
  "transpositions": {
    "total": 3,
    "options": {
      "idNames": [
        "qarar_chahargah",
        "chahargah",
        "mahuran"
      ],
      "displayNames": [
        "qarār chahārgāh",
        "chahārgāh",
        "māhūrān"
      ]
    },
    "detailed": [
      {
        "idName": "maqam_rast_al_qarar_chahargah",
        "displayName": "maqām rāst al-qarār chahārgāh",
        "tonic": {
          "idName": "qarar_chahargah",
          "displayName": "qarār chahārgāh"
        },
        "pitchClass": {
          "pitchClassIndex": 14,
          "octave": 0
        },
        "isBaseForm": false,
        "formType": "transposition",
        "primaryJins": [
          {
            "noteName": "qarar_chahargah",
            "noteNameDisplay": "qarār chahārgāh",
            "maqamDegree": "I",
            "jinsStatus": "matched",
            "jinsId": "19",
            "jinsIdName": "jins_rast_al_qarar_chahargah",
            "jinsDisplayName": "jins rāst al-qarār chahārgāh",
            "jinsIsBaseForm": false,
            "jinsFormType": "transposition"
          }
        ],
        "secondaryJins": [
          {
            "noteName": "rast",
            "noteNameDisplay": "rāst",
            "maqamDegree": "V",
            "jinsStatus": "matched",
            "jinsId": "19",
            "jinsIdName": "jins_rast",
            "jinsDisplayName": "jins rāst",
            "jinsIsBaseForm": true,
            "jinsFormType": "base"
          }
        ],
        "tertiaryJins": null,
        "primaryJinsDescending": [
          {
            "noteName": "qarar_chahargah",
            "noteNameDisplay": "qarār chahārgāh",
            "maqamDegree": "I",
            "jinsStatus": "matched",
            "jinsId": "19",
            "jinsIdName": "jins_rast_al_qarar_chahargah",
            "jinsDisplayName": "jins rāst al-qarār chahārgāh",
            "jinsIsBaseForm": false,
            "jinsFormType": "transposition"
          }
        ],
        "secondaryJinsDescending": [
          {
            "noteName": "rast",
            "noteNameDisplay": "rāst",
            "maqamDegree": "V",
            "jinsStatus": "matched",
            "jinsId": "6",
            "jinsIdName": "jins_nahawand",
            "jinsDisplayName": "jins nahāwand",
            "jinsIsBaseForm": true,
            "jinsFormType": "base"
          }
        ],
        "tertiaryJinsDescending": null,
        "ghammaz": [
          {
            "noteName": "rast",
            "noteNameDisplay": "rāst",
            "maqamDegree": "V",
            "intervalFromTonic": {
              "cents": 701.9550008653874,
              "fraction": "3/2",
              "decimalRatio": 1.5
            }
          }
        ],
        "links": {
          "detail": "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=qarar_chahargah"
        }
      },
      {
        "idName": "maqam_rast_al_chahargah",
        "displayName": "maqām rāst al-chahārgāh",
        "tonic": {
          "idName": "chahargah",
          "displayName": "chahārgāh"
        },
        "pitchClass": {
          "pitchClassIndex": 14,
          "octave": 1
        },
        "isBaseForm": false,
        "formType": "transposition",
        "primaryJins": [
          {
            "noteName": "chahargah",
            "noteNameDisplay": "chahārgāh",
            "maqamDegree": "I",
            "jinsStatus": "matched",
            "jinsId": "19",
            "jinsIdName": "jins_rast_al_chahargah",
            "jinsDisplayName": "jins rāst al-chahārgāh",
            "jinsIsBaseForm": false,
            "jinsFormType": "transposition"
          }
        ],
        "secondaryJins": [
          {
            "noteName": "kurdan",
            "noteNameDisplay": "kurdān",
            "maqamDegree": "V",
            "jinsStatus": "matched",
            "jinsId": "19",
            "jinsIdName": "jins_rast_al_kurdan",
            "jinsDisplayName": "jins rāst al-kurdān",
            "jinsIsBaseForm": false,
            "jinsFormType": "octaveRendering"
          }
        ],
        "tertiaryJins": null,
        "primaryJinsDescending": [
          {
            "noteName": "chahargah",
            "noteNameDisplay": "chahārgāh",
            "maqamDegree": "I",
            "jinsStatus": "matched",
            "jinsId": "19",
            "jinsIdName": "jins_rast_al_chahargah",
            "jinsDisplayName": "jins rāst al-chahārgāh",
            "jinsIsBaseForm": false,
            "jinsFormType": "transposition"
          }
        ],
        "secondaryJinsDescending": [
          {
            "noteName": "kurdan",
            "noteNameDisplay": "kurdān",
            "maqamDegree": "V",
            "jinsStatus": "matched",
            "jinsId": "6",
            "jinsIdName": "jins_nahawand_al_kurdan",
            "jinsDisplayName": "jins nahāwand al-kurdān",
            "jinsIsBaseForm": false,
            "jinsFormType": "octaveRendering"
          }
        ],
        "tertiaryJinsDescending": null,
        "ghammaz": [
          {
            "noteName": "kurdan",
            "noteNameDisplay": "kurdān",
            "maqamDegree": "V",
            "intervalFromTonic": {
              "cents": 701.9550008653874,
              "fraction": "3/2",
              "decimalRatio": 1.5
            }
          }
        ],
        "links": {
          "detail": "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=chahargah"
        }
      },
      {
        "idName": "maqam_rast_al_mahuran",
        "displayName": "maqām rāst al-māhūrān",
        "tonic": {
          "idName": "mahuran",
          "displayName": "māhūrān"
        },
        "pitchClass": {
          "pitchClassIndex": 14,
          "octave": 2
        },
        "isBaseForm": false,
        "formType": "transposition",
        "primaryJins": [
          {
            "noteName": "mahuran",
            "noteNameDisplay": "māhūrān",
            "maqamDegree": "I",
            "jinsStatus": "matched",
            "jinsId": "19",
            "jinsIdName": "jins_rast_al_mahuran",
            "jinsDisplayName": "jins rāst al-māhūrān",
            "jinsIsBaseForm": false,
            "jinsFormType": "transposition"
          }
        ],
        "secondaryJins": [
          {
            "noteName": "jawab_kurdan",
            "noteNameDisplay": "jawāb kurdān",
            "maqamDegree": "V",
            "jinsStatus": "matched",
            "jinsId": "19",
            "jinsIdName": "jins_rast_al_jawab_kurdan",
            "jinsDisplayName": "jins rāst al-jawāb kurdān",
            "jinsIsBaseForm": false,
            "jinsFormType": "octaveRendering"
          }
        ],
        "tertiaryJins": null,
        "primaryJinsDescending": [
          {
            "noteName": "mahuran",
            "noteNameDisplay": "māhūrān",
            "maqamDegree": "I",
            "jinsStatus": "matched",
            "jinsId": "19",
            "jinsIdName": "jins_rast_al_mahuran",
            "jinsDisplayName": "jins rāst al-māhūrān",
            "jinsIsBaseForm": false,
            "jinsFormType": "transposition"
          }
        ],
        "secondaryJinsDescending": [
          {
            "noteName": "jawab_kurdan",
            "noteNameDisplay": "jawāb kurdān",
            "maqamDegree": "V",
            "jinsStatus": "matched",
            "jinsId": "6",
            "jinsIdName": "jins_nahawand_al_jawab_kurdan",
            "jinsDisplayName": "jins nahāwand al-jawāb kurdān",
            "jinsIsBaseForm": false,
            "jinsFormType": "octaveRendering"
          }
        ],
        "tertiaryJinsDescending": null,
        "ghammaz": [
          {
            "noteName": "jawab_kurdan",
            "noteNameDisplay": "jawāb kurdān",
            "maqamDegree": "V",
            "intervalFromTonic": {
              "cents": 701.9550008653873,
              "fraction": "3/2",
              "decimalRatio": 1.5
            }
          }
        ],
        "links": {
          "detail": "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=mahuran"
        }
      }
    ]
  },
  "links": {
    "self": "https://diarmaqar.net/api/maqamat/maqam_rast/transpositions?tuningSystem=ibnsina_1037&startingNote=yegah",
    "availability": "https://diarmaqar.net/api/maqamat/maqam_rast/availability",
    "detail": "https://diarmaqar.net/api/maqamat/maqam_rast"
  }
}

Compare maqām data across multiple tuning systems and starting notes ​

GET /maqamat/{idName}/compare

Compare comprehensive maqām data across multiple tuning systems and multiple starting notes in a single request. Given N tuning systems and M starting notes, the response contains the Cartesian product of N × M comparison cells in user-supplied order (outer loop = tuningSystems, inner loop = startingNotes).

Each successful cell includes ascending/descending pitch class sequences, optional interval data, ajnās mapping, family classification, and transposition details. When a requested starting note is not available in a given tuning system the cell carries an informational note field (not error) together with validStartingNotes. When a hard failure occurs (tuning system not found, maqām not realizable in this configuration, or a transposeTo target that is unreachable) the cell carries an error field. The overall response is always HTTP 200 — per-cell outcomes do not affect the HTTP status.

The following invariant always holds:

successfulComparisons + unavailableStartingNotes + failedComparisons === totalComparisons

This endpoint is ideal for comparative musicological analysis across historical tuning systems and/or multiple modal transpositions.

Path Parameters:

  • idName: URL-safe maqām identifier: A maqām's idName (maqam_rast), its numeric id, or the idName of one of its transpositions (maqam_rast_al_qarar_chahargah). A transposed idName works like adding transposeTo for its tonic; giving it together with a different transposeTo is a 400. The older closed-up spelling (maqam_rast_alqarar_chahargah) is also accepted. (string) (required)
    • Example: maqam_bayyat

Query Parameters:

  • tuningSystems (required): Comma-separated list of tuning system IDs. product of these tuning systems with the requested startingNotes (outer loop = tuningSystems, inner loop = startingNotes). Use all to include every tuning system in the archive (cannot be combined with explicit IDs).
  • Type: string
  • Example: alsabbagh_1954,ibnsina_1037
  • startingNotes (required): Comma-separated list of starting note names (URL-safe, diacritics-insensitive). response contains N × M cells for N tuning systems × M starting notes, in user-supplied order. If a starting note is not available in a given tuning system that cell carries an informational note field (with a validStartingNotes namespace) rather than pitch data.
  • Type: string
  • Example: rast,yegah,ushayran
  • pitchClassDataType (optional): Output format for pitch class data. Defaults to all when omitted. - Type: string - Valid values: all, englishName, solfege, fraction, cents, ... (14 total) - Default: all
    • Example: cents
  • includeIntervals (optional): Whether to include interval data between adjacent pitch classes on each cell. Defaults to "false" when omitted.. Defaults to "false" when omitted.
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • transposeTo (optional): Transpose every successful cell to the given tonic note (applies to every cell in the Cartesian product). Cartesian product). If the requested target is not reachable in a given cell the cell carries an error plus an availableTranspositions list.
  • Type: string
  • Example: nawa
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with Ar suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Tuning system display names get Arabic versions in displayNameAr if available
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/maqamat/maqam_bayyat/compare?tuningSystems=alsabbagh_1954,ibnsina_1037&startingNotes=rast,yegah,ushayran&includeArabic=true"

Response: Comparison data retrieved successfully. Note that the response is always HTTP 200 regardless of per-cell outcomes; individual failures (missing starting note, tuning system not found, maqām not realizable, unreachable transposeTo) are reported on the respective cell via note or error fields. The counters successfulComparisons + unavailableStartingNotes + failedComparisons always equal totalComparisons.

Example response — twoTuningSystems:

json
{
  "maqam": {
    "id": "1",
    "idName": "maqam_rast",
    "displayName": "maqām rāst",
    "version": "2025-12-10T17:03:34.565Z"
  },
  "comparisons": {
    "count": 1,
    "totalComparisons": 1,
    "successfulComparisons": 1,
    "unavailableStartingNotes": 0,
    "failedComparisons": 0,
    "data": [
      {
        "tuningSystem": {
          "id": "alsabbagh_1954",
          "idName": "alsabbagh_1954",
          "displayName": "al-Ṣabbāgh (1954) Contemporary Arabic Tuning 24-Tone",
          "version": "2025-10-18T19:42:23.643Z"
        },
        "startingNote": {
          "idName": "rast",
          "displayName": "rāst"
        },
        "maqam": {
          "id": "1",
          "idName": "maqam_rast",
          "displayName": "maqām rāst",
          "version": "2025-12-10T17:03:34.565Z",
          "maqamFamilyId": "rast",
          "maqamFamilyDisplayName": "rāst"
        },
        "tonic": {
          "idName": "rast",
          "displayName": "rāst"
        },
        "stats": {
          "tuningSystem": {
            "numberOfPitchClassesSingleOctave": 24,
            "referenceFrequency": 130.665
          },
          "maqam": {
            "numberOfPitchClasses": 7,
            "isOctaveRepeating": true
          }
        },
        "availableTranspositions": [],
        "pitchData": {
          "ascending": [
            {
              "pitchClassIndex": 0,
              "octave": 1,
              "scaleDegree": "I",
              "noteName": "rast",
              "noteNameDisplay": "rāst",
              "cents": 0
            },
            {
              "pitchClassIndex": 4,
              "octave": 1,
              "scaleDegree": "II",
              "noteName": "dugah",
              "noteNameDisplay": "dūgāh",
              "cents": 203.91000173077484
            }
          ],
          "descending": [
            {
              "pitchClassIndex": 20,
              "octave": 1,
              "scaleDegree": "VII",
              "noteName": "ajam",
              "noteNameDisplay": "ʿajam",
              "cents": 1019.5580263750745
            },
            {
              "pitchClassIndex": 18,
              "octave": 1,
              "scaleDegree": "VI",
              "noteName": "husayni",
              "noteNameDisplay": "ḥusaynī",
              "cents": 905.8650025961623
            }
          ]
        },
        "ajnas": {
          "ascending": {
            "rast": [
              {
                "id": "19",
                "idName": "jins_rast",
                "displayName": "jins rāst"
              }
            ],
            "dugah": [
              {
                "id": "2",
                "idName": "jins_bayyat",
                "displayName": "jins bayyāt"
              }
            ],
            "chahargah": []
          },
          "descending": {
            "ajam": [],
            "husayni": [
              {
                "id": "30",
                "idName": "jins_kurd_ushayran",
                "displayName": "jins kurd ʿushayrān"
              }
            ]
          }
        },
        "intervals": {
          "ascending": [
            {
              "cents": 203.91000173077484
            },
            {
              "cents": 152.95309101871007
            }
          ],
          "descending": [
            {
              "cents": 113.69302377891222
            },
            {
              "cents": 203.91000173077487
            }
          ]
        },
        "parameters": {
          "pitchClassDataType": "cents",
          "includeIntervals": true,
          "transposeTo": null
        },
        "links": {
          "detail": "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=alsabbagh_1954&startingNote=r%C4%81st&pitchClassDataType=cents&includeIntervals=true",
          "availability": "https://diarmaqar.net/api/maqamat/maqam_rast/availability"
        }
      }
    ]
  },
  "parameters": {
    "tuningSystems": {
      "idNames": [
        "alsabbagh_1954"
      ],
      "displayNames": [
        "alsabbagh_1954"
      ]
    },
    "startingNotes": {
      "idNames": [
        "rast"
      ],
      "displayNames": [
        "rast"
      ]
    },
    "pitchClassDataType": "cents",
    "includeIntervals": true,
    "transposeTo": null
  },
  "links": {
    "self": "https://diarmaqar.net/api/maqamat/maqam_rast/compare?tuningSystems=alsabbagh_1954&startingNotes=rast&pitchClassDataType=cents",
    "detail": "https://diarmaqar.net/api/maqamat/maqam_rast",
    "availability": "https://diarmaqar.net/api/maqamat/maqam_rast/availability"
  }
}

Classify maqāmāt by 12-pitch-class sets ​

GET /maqamat/classification/12-pitch-class-sets

Groups maqāmāt according to sets of 12 pitch classes suitable for MIDI keyboard tuning and Scala file export. Each set is created by merging pitch classes from the specified tuning system with alkindi_874 filler pitch classes, based on matching IPN reference note names.

Critical Design Principles:

  • Octave Alignment: Both the maqām tuning system and alkindi_874 use the same startingNote to ensure octaves align correctly
  • Chromatic Order: Each set contains exactly 12 pitch classes ordered chromatically starting from the maqām's tonic (e.g., C, C#, D, D#... for Rāst)
  • Arabic Musicological Logic: IPN references follow Arabic maqām theory: a note's quarter-tone or comma spelling names the note it is a variant of (E-b is a variant of E), not the nearest 12-EDO semitone
  • Direct Tuning System Values: All cent values come directly from tuning systems without post-processing or calculation

The Algorithm:

  1. Loads pitch classes from both the specified tuning system and alkindi_874 using the same startingNote
  2. For each maqām transposition:
    • Extracts IPN reference note names from ascending and descending sequences
    • Puts every degree of the maqām on its key; each key the maqām leaves empty takes al-Kindī's (alkindi_874) pitch on that key. Nothing else enters a set: maqām nairūz's set holds tīk ḥiṣār on G#, its own degree; the set holding maqām lāmī has ḥiṣār there.
    • Places the tonic in the first octave above startingNote (0 to 1200 cents) and each following key in the lowest octave above the key before, so every set ascends from its tonic within both tuning systems. A set has no register: one made from qarār dūgāh is listed from dūgāh.
  3. Groups compatible maqāmāt together: a transposition joins a set only when every pitch of its ascending and descending sequences is in the set
  4. Names each group after one of its members (see Set names) and lists the 12 pitch classes from that member's tonic

Set names: A set is named after one of its members, chosen by one rule. The name never changes which maqāmāt are in the set or which 12 pitches it holds.

  1. A set that holds one or more base forms is named after the base form whose maqām has the lowest id. Maqām lāmī (allami_2022 from ʿushayrān) is in the maqām ḥijāz kār kurd set: that set holds the base forms of ḥijāz kār kurd (id 4), lāmī (id 9) and others.
  2. A set with no base form is named after its commonest family (the jins on the first degree of each member's maqām, as /maqamat/families reads it; "no jins" is not counted). Of that family, the maqām with the lowest id names the set. Two families with the same count: the one whose lowest maqām id is lower. When every member is "no jins", the lowest maqām id of all names the set.
  3. When that maqām is in the set more than once, the form whose tonic has no qarār or jawāb prefix is used, else any form; between several, the lowest tonic in pitch. The set ID is the chosen member's idName plus _set, and sourceMaqam and sourceTransposition are that member.

Compatibility:

  • A 12-pitch-class set has one pitch class per key. Each pitch class of a maqām takes the key of its own note letter, or a neighbouring key when that one is taken.
  • A maqām transposition is incompatible when two different pitch classes would need the same key and the keys next to it are already taken. For example, maqām faraḥnāk (al-Ḥilū) on qarār segāh needs both ʿirāq (B-b2) and nīm kawasht (B-2) on the B key.
  • Each incompatible transposition says which keys clash, which notes need them, and gives the same in one plain sentence (explanation).
  • The number of incompatible transpositions is always in statistics.incompatibleMaqamatCount; the full list is included on request.
  • A maqām transposition is compatible with a set when every one of its pitches, octave ignored, is within centsTolerance of one of the set's 12 pitches. Only the pitch is compared, not the key it sits on. Maqām chahārgāh (al-Ṣabbāgh) needs nīm ʿajam (60.41 cents above the octave in allami_2022), so it is not in a set that has ʿajam (90.22) instead.
  • Compatible maqāmāt can be performed entirely within a single 12-pitch-class set

Output Format:

  • Pitch classes ordered chromatically (C, C#, D, D#, E, F, F#, G, G#, A, A#, B)
  • Starting from the tonic of the member the set is named after, in the first octave above startingNote (default), OR from IPN "C" at or below that tonic (if startSetFromC=true)
  • Relative cents from 0 (reference note) to ~1050-1200 (octave)
  • maqamTonic field indicates the actual maqām tonic position and note name
  • Suitable for MIDI keyboard tuning and Scala (.scl) file generation

Filtering Options:

  • Use setId to retrieve a specific set and its compatible maqāmāt
  • Use maqamId to find all sets containing a specific maqām, together with its transpositions that fit no set. A maqām with no transposition that fits still returns 200, with compatible: false, an explanation and an empty sets list. Only an id that names no maqām or transposition returns 404.

Query Parameters:

  • tuningSystem (required): Tuning system ID for maqāmāt - Type: string
    • Example: cairocongresstuningcommittee_1929
  • startingNote (required): Starting note for both the maqām tuning system and alkindi_874. IMPORTANT: Both tuning systems must use the same starting note to ensure octaves align correctly and pitch classes can be properly selected from matching octaves. IMPORTANT: Both tuning systems must use the same starting note to ensure octaves align correctly and pitch classes can be properly selected from matching octaves. Use yegah for IbnSina/Meshshaqa, ushayran for al-Farabi/al-Kindi, rast for CairoCongress/al-Sabbagh
  • Type: string
  • Example: yegah
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5
  • includeIncompatible (optional): Include the full list of maqām transpositions that cannot form a 12-pitch-class set, with the clashing keys and notes of each (their number is always in the statistics). - Type: string - Valid values: true, false - Default: false
    • Example: true
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • startSetFromC (optional): Start pitch class set from IPN reference "C" (degree 0) instead of from the maqām's tonic. When true, the set is reordered to start from C at 0.00 cents (relative), making it directly compatible with Scala (.scl) file format which maps degree 0 to middle C by default. When true, the set is reordered to start from C at 0.00 cents (relative), making it directly compatible with Scala (.scl) file format which maps degree 0 to middle C by default. Technical Implementation:
    1. Octave Selection: For maqāmāt starting mid-octave (e.g., D), pitch classes before the tonic in chromatic order (C, C#) are taken from octave 1, while those at or after the tonic use their original octaves
    2. Array Rotation: The 12 pitch classes are rotated to place C first
    3. Relative Cents: Calculated from C (0.00 cents), with octave wrap-around handling (negative values + 1200)
    4. Note Names: Arabic note names follow the NoteName model's octave conventions (e.g., C octave 1 = rāst, C octave 2 = kurdān)
    5. Tonic Tracking: The maqamTonic field indicates the actual maqām tonic's IPN, note names, and position in the reordered set Use Cases:
    • false (default): For understanding maqām structure starting from its tonic
    • true: For Scala .scl export (no .kbm file needed) or MIDI keyboard mapping where C = degree 0 Example:
    • Maqām ḥijāz (tonic D/dūgāh at 702.13 cents): - Default mode: D at position 0 (0.00 cents relative) - Scala mode: C (rāst, 498.04 cents) at position 0 (0.00 cents relative), D at position 2 (204.08 cents relative)
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • pitchClassDataType (optional): Controls which pitch class data fields are returned in the response.
    • all: Returns all available pitch class data fields
    • englishName: English note name with octave (e.g., "D2", "E-b3")
    • fraction: Frequency ratio as a fraction string
    • cents: Absolute cents value from the tuning system
    • decimalRatio: Frequency ratio as decimal number
    • stringLength: String length for oud/qanun (if available)
    • frequency: Frequency in Hz
    • abjadName: Arabic abjad notation (if available)
    • fretDivision: Fret position for oud (if available)
    • midiNoteNumber: MIDI note number as decimal
    • midiNoteDeviation: MIDI note with cents deviation string
    • centsDeviation: Cents deviation from 12-EDO
    • referenceNoteName: IPN reference note name
    • relativeCents: Cents relative to the first pitch class (0.00 for tonic or C) Default Behavior (parameter omitted):
    • Returns minimal fields: ipnReferenceNoteName, noteName, relativeCents, octave Example:
    • ?pitchClassDataType=cents returns only IPN, note name, and cents values
    • ?pitchClassDataType=all returns all available data fields
  • Type: string - Valid values: all, abjadName, englishName, solfege, fraction, ... (15 total)
  • Example: cents
  • setId (optional): Filter by specific set ID to retrieve that set and its compatible maqāmāt (e.g., 'maqam_rast_set'). - Type: string
    • Example: maqam_rast_set
  • maqamId (optional): Filter by maqām to find all sets containing it and list its transpositions that fit no set: a maqām idName (e.g., 'maqam_rast'), its numeric id, or one transposition's idName (e.g., 'maqam_rast_al_qarar_chahargah'; the older closed-up spelling 'maqam_rast_alqarar_chahargah' is also accepted). - Type: string
    • Example: maqam_rast

Example:

bash
curl "https://diarmaqar.net/api/maqamat/classification/12-pitch-class-sets?tuningSystem=cairocongresstuningcommittee_1929&startingNote=yegah&includeArabic=true"

Response: Classification results with sets and compatible maqāmāt; with a maqām filter, also whether the maqām fits any set and which of its transpositions do not

Example response — default:

json
{
  "summary": [
    {
      "setIdName": "maqam_rast_set",
      "setDisplayName": "maqām rāst set",
      "compatibleMaqamat": [
        {
          "maqamIdName": "maqam_rast",
          "maqamDisplayName": "maqām rāst",
          "isTransposed": false,
          "isBaseForm": true
        }
      ]
    }
  ],
  "statistics": {
    "totalSets": 1,
    "sets": [
      {
        "setIdName": "maqam_rast_set",
        "setDisplayName": "maqām rāst set",
        "compatibleMaqamatCount": 1
      }
    ],
    "totalCompatibleMaqamat": 1,
    "incompatibleMaqamatCount": 0
  },
  "sets": [
    {
      "id": "maqam_rast_set",
      "setIdName": "maqam_rast_set",
      "setDisplayName": "maqām rāst set",
      "sourceMaqam": {
        "id": "1",
        "idName": "maqam_rast",
        "displayName": "maqām rāst"
      },
      "sourceTransposition": {
        "idName": "maqam_rast",
        "displayName": "maqām rāst",
        "isTransposed": false,
        "isBaseForm": true
      },
      "pitchClassSet": [
        {
          "ipnReferenceNoteName": "C",
          "noteName": "rāst",
          "cents": 0,
          "fraction": "1/1",
          "decimalRatio": 1,
          "frequency": 130.665,
          "octave": 1
        }
      ],
      "compatibleMaqamat": [
        {
          "maqamIdName": "maqam_rast",
          "maqamDisplayName": "maqām rāst",
          "isTransposed": false,
          "isBaseForm": true
        }
      ],
      "compatibleMaqamatCount": 1
    }
  ],
  "totalSets": 1,
  "totalCompatibleMaqamat": 1,
  "incompatibleMaqamat": [],
  "incompatibleMaqamatCount": 0,
  "parameters": {
    "tuningSystem": {
      "id": "cairocongresstuningcommittee_1929",
      "idName": "cairocongresstuningcommittee-1929",
      "displayName": "Cairo Congress Tuning Committee (1929)"
    },
    "startingNote": {
      "idName": "yegah",
      "displayName": "yegāh"
    },
    "alKindiTuningSystem": {
      "id": "alkindi_874",
      "idName": "al-kindi-874",
      "displayName": "al-Kindī (874)"
    },
    "alKindiStartingNote": {
      "idName": "ushayran",
      "displayName": "ʿushayrān"
    },
    "centsTolerance": 5,
    "startSetFromC": false
  }
}

Classify maqāmāt by maqam-based pitch class sets ​

GET /maqamat/classification/maqam-pitch-class-sets

Groups maqāmāt according to maqam-based pitch class sets. Each set contains all pitch classes from a single maqām transposition (union of ascending and descending), and identifies which other maqāmāt can be performed using only those pitch classes.

Musicological Purpose: Answers the question: "Which maqāmāt can be performed using only the pitch classes of maqām X?" For example, maqām rāst on rāst includes pitch classes that can perform maqām bayyāt on dūgāh and maqām segāh on segāh.

Key Differences from 12-Pitch-Class-Sets:

  • No Chromatic Base: Does not merge with alkindi_874 or chromatic filler pitch classes
  • Variable Set Sizes: Sets can contain any number of pitch classes (7, 8, 10, etc.), not fixed at 12
  • Octave-Equivalent Matching: Pitch classes in different octaves treated as equivalent (C in octave 1 = C in octave 2)
  • Single Tuning System: Uses only the specified tuning system (simpler than 12-pitch-class-sets)
  • Subset Matching: Compatible maqāmāt must use subset of source maqam's pitch classes

Critical Design Principles:

  • Octave Equivalence: IPN references are compared octave-normalized (C at any octave = "C")
  • Union of Melodic Paths: Includes all pitch classes from both ascending AND descending sequences
  • Exact Matching: All pitch classes from a compatible maqām must exist in the source set (within tolerance)
  • Direct Values: All cent values come directly from tuning system without calculation
  • Base-form Priority: Base forms create canonical sets first, then transpositions

The Algorithm:

  1. For each maqām form (base form first, then transpositions):
    • Extracts all unique pitch classes from ascending + descending sequences
    • Groups by IPN reference (octave-equivalent)
    • Validates no duplicate IPN references with different cents values
    • Creates a maqam-based pitch class set
  2. For each set, finds compatible maqāmāt:
    • Checks if all pitch classes needed by candidate maqām exist in source set
    • Compares cents values within tolerance (octave-normalized)
    • Marks candidate as compatible if all pitch classes match
  3. Groups compatible maqāmāt together
  4. Names each group after one of its members (see Set names)

Set names: A set is named by the same rule as on /maqamat/classification/12-pitch-class-sets: after its lowest-id base form when it holds one, else after the lowest-id maqām of its commonest family, preferring a tonic with no qarār or jawāb prefix, then the lowest tonic. The set's pitch classes are those of the transposition that made it. The maqām the set is named after is a member, so its pitch classes are all in the set, but the set can hold more. The set ID is the chosen member's idName plus _set.

Compatibility:

  • Maqāmāt with duplicate IPN references (same IPN with different cents values when octave-normalized) are marked as incompatible
  • Compatible maqāmāt can be performed entirely using the pitch classes of the source maqām
  • Minimum Set Size: Only sets with 2 or more maqāmāt are returned (source + at least one compatible). One maqām on one tonic key counts once however many octaves it appears in, so a set holding only maqām rāst on rāst and on kurdān is not returned.
  • Every member is listed, octave equivalents included: maqām bayyāt on yegāh, on nawā and on saham/ramal tūtī are three entries of one set

Output Format:

  • Sets ordered by number of compatible maqāmāt (descending)
  • Each set includes: source maqām, all pitch classes (in ascending cents order), compatible maqāmāt, pitch class count
  • Pitch classes include: English name, note name, cents, frequency, fraction, etc.

Filtering Options:

  • Use setId to retrieve a specific set and its compatible maqāmāt
  • Use maqamId to find all sets containing a specific maqām

Query Parameters:

  • tuningSystem (required): Tuning system ID for all maqāmāt - Type: string
    • Example: cairocongresstuningcommittee_1929
  • startingNote (required): Starting note for the tuning system. - Type: string
    • Example: yegah
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5
  • includeIncompatible (optional): Include maqāmāt that cannot form valid maqam-based pitch class sets - Type: string - Valid values: true, false - Default: false
    • Example: true
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • includePitchClassData (optional): Include pitch class data in the response (default: false). When false: Omits pitch class data, returning only set metadata and compatible maqamat
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • setId (optional): Filter by specific set ID to retrieve that set and its compatible maqāmāt (e.g., 'maqam_rast_set'). - Type: string
    • Example: maqam_rast_set
  • maqamId (optional): Filter by maqām to find all sets containing it: a maqām idName (e.g., 'maqam_rast'), its numeric id, or one transposition's idName (e.g., 'maqam_rast_al_qarar_chahargah'; the older closed-up spelling 'maqam_rast_alqarar_chahargah' is also accepted). - Type: string
    • Example: maqam_rast

Example:

bash
curl "https://diarmaqar.net/api/maqamat/classification/maqam-pitch-class-sets?tuningSystem=cairocongresstuningcommittee_1929&startingNote=yegah&includeArabic=true"

Response: Classification results with maqam-based pitch class sets and compatible maqāmāt

Example response — default:

json
{
  "statistics": {
    "totalSets": 1,
    "totalCompatibleMaqamat": 3,
    "incompatibleMaqamatCount": 0,
    "totalProcessed": 3
  },
  "sets": [
    {
      "setIdName": "maqam_rast_set",
      "setDisplayName": "maqām rāst set",
      "compatibleMaqamatCount": 3,
      "sourceMaqam": {
        "id": "1",
        "idName": "maqam_rast",
        "displayName": "maqām rāst"
      },
      "pitchClassSet": [
        {
          "englishName": "C3",
          "noteName": "rāst",
          "cents": 0,
          "fraction": "1/1",
          "decimalRatio": 1,
          "frequency": 130.665,
          "octave": 1
        },
        {
          "englishName": "D3",
          "noteName": "dūgāh",
          "cents": 203.91,
          "fraction": "9/8",
          "decimalRatio": 1.125,
          "frequency": 146.998,
          "octave": 1
        },
        {
          "englishName": "E3",
          "noteName": "segāh",
          "cents": 407.82,
          "fraction": "81/64",
          "decimalRatio": 1.266,
          "frequency": 165.361,
          "octave": 1
        }
      ],
      "pitchClassCount": 7,
      "compatibleMaqamat": [
        {
          "maqamIdName": "maqam_rast",
          "maqamDisplayName": "maqām rāst",
          "isTransposed": false,
          "isBaseForm": true,
          "tonic": {
            "ipnReferenceNoteName": "C",
            "noteNameIdName": "rast",
            "noteNameDisplayName": "rāst"
          }
        },
        {
          "maqamIdName": "maqam_bayyat_dugah",
          "maqamDisplayName": "maqām bayyāt (dūgāh)",
          "isTransposed": true,
          "isBaseForm": false,
          "tonic": {
            "ipnReferenceNoteName": "D",
            "noteNameIdName": "dugah",
            "noteNameDisplayName": "dūgāh"
          }
        },
        {
          "maqamIdName": "maqam_segah_segah",
          "maqamDisplayName": "maqām segāh (segāh)",
          "isTransposed": true,
          "isBaseForm": false,
          "tonic": {
            "ipnReferenceNoteName": "E",
            "noteNameIdName": "segah",
            "noteNameDisplayName": "segāh"
          }
        }
      ]
    }
  ],
  "parameters": {
    "tuningSystem": {
      "id": "cairocongresstuningcommittee_1929",
      "idName": "cairocongresstuningcommittee-1929",
      "displayName": "Cairo Congress Tuning Committee (1929)"
    },
    "startingNote": {
      "idName": "yegah",
      "displayName": "yegāh"
    },
    "centsTolerance": 5
  }
}

Ajnās ​

Documented tri/tetra/penta-chords with historical source attribution.

List all ajnās ​

GET /ajnas

Return all ajnās (singular: jins) with metadata.

  • Includes URL-safe identifiers, display names, and structural information
  • Structural information includes note sequences needed for maqām construction and analysis
  • Optional bibliographic source references (sourceId and page) when includeSources=true

Query Parameters:

  • filterByTonic (optional): Filter by jins tonic/first note (URL-safe, case-insensitive, diacritics-insensitive) - Type: string
    • Example: rast
  • sortBy (optional): Sort order for results. including empty string) return HTTP 400.
  • Type: string - Valid values: alphabetical, tonic - Default: alphabetical
  • Example: alphabetical - Sort alphabetically by display name (default)
  • Example: tonic - Sort by tonic note priority across the full NoteName.ts octave-stratified order, alphabetical tiebreak
  • includeSources (optional): Include bibliographic source references (sourceId and page) for each jins - Type: string - Valid values: true, false - Default: false
    • Example: true
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/ajnas?includeSources=true&includeArabic=true"

Response: List of ajnās retrieved successfully

Example response:

json
{
  "count": 38,
  "data": [
    {
      "jins": {
        "id": "42",
        "idName": "jins_ajam_sultani",
        "displayName": "jins ʿajam sulṭānī",
        "version": "2026-07-20T09:57:37.540Z"
      },
      "tonic": {
        "idName": "ajam_ushayran",
        "displayName": "ʿajam ʿushayrān"
      },
      "stats": {
        "numberOfPitchClasses": 4,
        "availableInTuningSystems": 26
      },
      "availability": {
        "tuningSystems": [
          {
            "tuningSystem": {
              "id": "ronzevalle_1904",
              "idName": "ronzevalle_1904",
              "displayName": "Ronzevalle (1904) Modernist Arabic Tuning",
              "version": "2026-08-05T13:44:18.170Z"
            },
            "startingNotes": {
              "idNames": [
                "ushayran",
                "yegah"
              ],
              "displayNames": [
                "ʿushayrān",
                "yegāh"
              ]
            }
          },
          {
            "tuningSystem": {
              "id": "alkindi_874",
              "idName": "alkindi_874",
              "displayName": "al-Kindī (874) 12-Tone",
              "version": "2026-08-05T14:18:59.205Z"
            },
            "startingNotes": {
              "idNames": [
                "ushayran",
                "yegah",
                "rast"
              ],
              "displayNames": [
                "ʿushayrān",
                "yegāh",
                "rāst"
              ]
            }
          }
        ]
      },
      "links": {
        "detail": "https://diarmaqar.net/api/ajnas/jins_ajam_sultani"
      }
    }
  ]
}

Get detailed jins data ​

GET /ajnas/{idName}

Retrieve comprehensive data for a specific jins on its conventional or a transposed tonic, in a specific tuning system on a specific starting note name.

Returns:

  • Comprehensive pitch class data in the requested tuning system and starting note name
  • Optional includeIntervals data, transposition to different tonics, and tuning-system-specific modulations (including lower octave)

Parameter Discovery:

  • Use options=true to discover valid values for all parameters including dynamically calculated transposition options
  • Especially useful for finding valid tuning system starting notes and transposition tonics for a specific jins

Important:

  • When options=true, the endpoint returns parameter discovery metadata instead of jins data
  • This mode is mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, pitch class data type, includeIntervals)
  • If data-returning parameters are provided with options=true, the API returns a 400 Bad Request error with details about conflicting parameters

Requirements:

  • Tuning system is required for all requests; a starting note is required for data retrieval and optional in discovery mode (options=true), where omitting it returns the tuning system's valid starting notes
  • These are fundamental to all pitch class calculations

Path Parameters:

  • idName: URL-safe jins identifier: A jins's idName (jins_segah), its numeric id, or the idName of one of its transpositions (jins_segah_al_tik_hisar). A transposed idName works like adding transposeTo for its tonic; giving it together with a different transposeTo is a 400. The older closed-up spelling (jins_segah_altik_hisar) is also accepted. (string) (required)
    • Example: jins_rast - Jins Rāst (representative example - with zalzalian intervals)
    • Example: jins_kurd - Jins Kurd (representative example - without zalzalian intervals)
    • Example: jins_bayyat - Jins Bayyāt (representative example - with zalzalian intervals)

Query Parameters:

  • tuningSystem (required): Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899') - Type: string
    • Example: ibnsina_1037 - Ibn Sīnā (1037) - 7-Fret Oud 17-Tone (representative example)
    • Example: alfarabi_950g - al-Fārābī (950g) - First Oud Tuning 27-Tone (representative example)
  • startingNote (required): Tuning system starting note name (URL-safe, diacritics-insensitive).
    • Different starting notes represent different theoretical frameworks within the same tuning system
    • Use yegah for IbnSina/Meshshaqa, ushayran for al-Farabi/al-Kindi, rast for CairoCongress/al-Sabbagh
  • Type: string
  • Example: yegah - yegāh (for IbnSina, Meshshaqa)
  • Example: ushayran - ʿushayrān (for al-Farabi, al-Kindi)
  • options (optional): When true, returns available parameter options instead of jins data.
    • Tuning system is required for all requests; a starting note is required for data retrieval and optional in discovery mode (options=true), where omitting it returns the tuning system's valid starting notes
    • These are fundamental to all pitch class calculations and calculate valid starting note options and transposition tonics
    • Mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, pitch class data type, intervals)
    • Transposition options are dynamically calculated based on the specific jins, tuning system, and starting note combination
    • Only tonics where the jins can be validly transposed (preserving interval pattern) are included, not all possible pitch classes
    • If data-returning parameters are provided, returns 400 Bad Request error with details about conflicting parameters
  • Type: string - Valid values: true, false - Default: false
  • pitchClassDataType (required): Specifies which pitch class data type to return for each pitch class.
    • When set to all, returns the full set of pitch class fields (englishName, solfege, abjadName, fraction, cents, decimalRatio, stringLength, frequency, fretDivision, midiNoteDecimal, midiNotePlusCentsDeviation, centsDeviation, ipnReferenceNoteName) plus the always-included identifiers (pitchClassIndex, octave, scaleDegree, noteName, noteNameDisplay, and noteNameDisplayAr if includeArabic is enabled).
    • When set to a specific format, returns only that field plus the always-included identifiers.
    • Empty string and unrecognised values return HTTP 400 with a hint listing valid options.
    • In discovery mode (when options=true), this parameter remains optional. Passing any value other than cents in discovery mode is treated as a conflict (400).
  • Type: string - Valid values: all, abjadName, englishName, solfege, fraction, ... (14 total) - Default: all
  • Example: cents
  • transposeTo (optional): Transpose the jins to a new tonic by preserving the interval patterns (URL-safe, diacritics-insensitive).
    • To see all valid transposition options, request available parameter options instead of jins data
  • Type: string
  • includeIntervals (optional): Include interval data between jins degrees - Type: string - Valid values: true, false - Default: false
    • Example: true
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/ajnas/jins_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents&includeArabic=true"

Response: Jins data retrieved successfully.

  • When options is true, the response structure differs and returns available parameter options instead of jins data
  • In that case, transposition options contain only valid transposition tonics for this specific jins, tuning system, and starting note combination

Example response — basic:

json
{
  "jins": {
    "id": "5",
    "idName": "jins_kurd",
    "displayName": "jins kurd",
    "version": "2025-10-18T19:41:17.132Z",
    "isBaseForm": true
  },
  "tonic": {
    "idName": "rast",
    "displayName": "rāst"
  },
  "stats": {
    "numberOfTranspositions": 17,
    "numberOfPitchClasses": 4
  },
  "comments": {
    "english": null,
    "arabic": null
  },
  "sources": [],
  "parameters": {
    "pitchClassDataType": "all",
    "includeIntervals": false,
    "centsTolerance": 5
  },
  "context": {
    "tuningSystem": {
      "id": "ibnsina_1037",
      "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
      "version": "2025-10-18T19:41:17.132Z",
      "originalValueType": "fraction",
      "numberOfPitchClassesSingleOctave": 17,
      "numberOfPitchClassesAllOctaves": 68,
      "startingNoteName": "yegah",
      "referenceFrequency": 440
    }
  },
  "pitchData": [
    {
      "pitchClassIndex": 0,
      "octave": 1,
      "scaleDegree": "I",
      "noteName": "rast",
      "noteNameDisplay": "rāst",
      "englishName": "C3",
      "fraction": "1/1",
      "cents": 0,
      "decimalRatio": 1,
      "stringLength": 1000,
      "frequency": 440,
      "fretDivision": "0.000",
      "midiNoteDecimal": 48,
      "midiNotePlusCentsDeviation": "48 +0.0",
      "centsDeviation": 0,
      "ipnReferenceNoteName": "C"
    },
    {
      "pitchClassIndex": 1,
      "octave": 1,
      "scaleDegree": "II",
      "noteName": "dugah",
      "noteNameDisplay": "dūgāh",
      "englishName": "D3",
      "fraction": "204/182",
      "cents": 204,
      "decimalRatio": 1.12,
      "frequency": 492.8
    }
  ]
}

Check jins availability across tuning systems ​

GET /ajnas/{idName}/availability

Return tuning-system availability for a jins.

  • Shows which tuning systems on which starting note names can realize the specified jins
  • If transpositionNoteName is provided, filters results to show only tuning systems where the jins can be transposed to that specific note
  • Validity is computed against each tuning system's note name sets and the jins's pitch class intervals
  • Availability is checked in every octave the tuning system builds from each starting note, so ajnās that span several octaves are found

Path Parameters:

  • idName: URL-safe jins identifier: A jins's idName (jins_rast), its numeric id, or the idName of one of its transpositions (jins_rast_al_nawa). A transposed idName works like transpositionNoteName for its tonic; giving it together with a different transpositionNoteName is a 400. The older closed-up spelling is also accepted. (string) (required)
    • Example: jins_rast

Query Parameters:

  • transpositionNoteName (optional): Filter results to show only tuning systems where the jins can be transposed to this specific note (URL-safe, diacritics-insensitive). - Type: string
    • Example: nawa
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/ajnas/jins_rast/availability?includeArabic=true"

Response: Availability information retrieved successfully

Example response — withoutTransposition:

json
{
  "jins": {
    "id": "5",
    "idName": "jins_kurd",
    "displayName": "Jins Kurd",
    "version": "2025-10-18T19:41:17.132Z"
  },
  "availability": {
    "count": 29,
    "tuningSystems": [
      {
        "tuningSystemId": "ibnsina_1037",
        "tuningSystemDisplayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
        "tuningSystemStartingNoteNames": [
          "ʿushayrān",
          "yegāh"
        ],
        "tuningSystemStartingNoteNamesIds": [
          "ushayran",
          "yegah"
        ]
      },
      {
        "tuningSystemId": "alfarabi_950g",
        "tuningSystemDisplayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave)",
        "tuningSystemStartingNoteNames": [
          "ʿushayrān",
          "yegāh"
        ],
        "tuningSystemStartingNoteNamesIds": [
          "ushayran",
          "yegah"
        ]
      }
    ]
  }
}

List transpositions for a jins ​

GET /ajnas/{idName}/transpositions

Lists distinct transpositions (taswīr) for a jins within a specific tuning system and starting note. The base form is excluded. Octave renderings of the same modal degree (e.g. qarār dūgāh vs dūgāh vs muḥayyar) are not treated as distinct taswīr.

If there are no distinct taswīr for this tuning-system + starting-note combination, this endpoint returns 422 with an { error, hint } payload (it does not return a 200 with an empty list).

Path Parameters:

  • idName: URL-safe jins identifier: A jins's idName (jins_rast) or its numeric id. This route lists every transposition of the jins, so the idName of a single transposition (jins_rast_al_nawa) is rejected with a 400 that names the base idName to use. (string) (required)
    • Example: jins_bayyat

Query Parameters:

  • tuningSystem (required): Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899') - Type: string
    • Example: meshshaqa_1899
  • startingNote (required): Tuning system starting note name (URL-safe, diacritics-insensitive). - Type: string
    • Example: yegah
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/ajnas/jins_bayyat/transpositions?tuningSystem=meshshaqa_1899&startingNote=yegah&includeArabic=true"

Response: Transpositions retrieved successfully

Example response:

json
{
  "jins": {
    "id": "2",
    "idName": "jins_bayyat",
    "displayName": "jins bayyāt",
    "version": "2025-10-18T19:35:30.479Z"
  },
  "tuningSystem": {
    "id": "ibnsina_1037",
    "idName": "ibnsina_1037",
    "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
    "version": "2025-11-09T00:44:40.275Z",
    "numberOfPitchClassesSingleOctave": 17
  },
  "startingNote": {
    "idName": "yegah",
    "displayName": "yegāh"
  },
  "transpositions": {
    "total": 12,
    "options": {
      "idNames": [
        "qarar_yegah",
        "qarar_ushayran",
        "qarar_rast",
        "yegah",
        "ushayran",
        {
          "…": "truncated — 7 more items"
        }
      ],
      "displayNames": [
        "qarār yegāh",
        "qarār ʿushayrān",
        "qarār rāst",
        "yegāh",
        "ʿushayrān",
        {
          "…": "truncated — 7 more items"
        }
      ]
    },
    "detailed": [
      {
        "idName": "jins_bayyat_al_qarar_yegah",
        "displayName": "jins bayyāt al-qarār yegāh",
        "tonic": {
          "idName": "qarar_yegah",
          "displayName": "qarār yegāh"
        },
        "pitchClass": {
          "pitchClassIndex": 0,
          "octave": 0
        },
        "links": {
          "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=qarar_yegah"
        }
      },
      {
        "idName": "jins_bayyat_al_qarar_ushayran",
        "displayName": "jins bayyāt al-qarār ʿushayrān",
        "tonic": {
          "idName": "qarar_ushayran",
          "displayName": "qarār ʿushayrān"
        },
        "pitchClass": {
          "pitchClassIndex": 3,
          "octave": 0
        },
        "links": {
          "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=qarar_ushayran"
        }
      },
      {
        "idName": "jins_bayyat_al_qarar_rast",
        "displayName": "jins bayyāt al-qarār rāst",
        "tonic": {
          "idName": "qarar_rast",
          "displayName": "qarār rāst"
        },
        "pitchClass": {
          "pitchClassIndex": 7,
          "octave": 0
        },
        "links": {
          "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=qarar_rast"
        }
      },
      {
        "idName": "jins_bayyat_al_yegah",
        "displayName": "jins bayyāt al-yegāh",
        "tonic": {
          "idName": "yegah",
          "displayName": "yegāh"
        },
        "pitchClass": {
          "pitchClassIndex": 0,
          "octave": 1
        },
        "links": {
          "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=yegah"
        }
      },
      {
        "idName": "jins_bayyat_al_ushayran",
        "displayName": "jins bayyāt al-ʿushayrān",
        "tonic": {
          "idName": "ushayran",
          "displayName": "ʿushayrān"
        },
        "pitchClass": {
          "pitchClassIndex": 3,
          "octave": 1
        },
        "links": {
          "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=ushayran"
        }
      },
      {
        "…": "truncated — 7 more items"
      }
    ]
  },
  "links": {
    "self": "https://diarmaqar.net/api/ajnas/jins_bayyat/transpositions?tuningSystem=ibnsina_1037&startingNote=yegah",
    "availability": "https://diarmaqar.net/api/ajnas/jins_bayyat/availability",
    "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat"
  }
}

Compare jins data across multiple tuning systems and starting notes ​

GET /ajnas/{idName}/compare

Compare comprehensive jins data across multiple tuning systems and multiple starting notes in a single request. Given N tuning systems and M starting notes, the response contains the Cartesian product of N × M comparison cells in user-supplied order (outer loop = tuningSystems, inner loop = startingNotes).

Each successful cell includes the (unidirectional) pitch class sequence, optional interval data, and transposition details. When a requested starting note is not available in a given tuning system the cell carries an informational note field (not error) together with validStartingNotes. When a hard failure occurs (tuning system not found, jins not realizable in this configuration, or an unreachable transposeTo target) the cell carries an error field. The overall response is always HTTP 200 — per-cell outcomes do not affect the HTTP status.

The following invariant always holds:

successfulComparisons + unavailableStartingNotes + failedComparisons === totalComparisons

This endpoint is ideal for comparative musicological analysis of melodic structures across historical tuning systems and/or multiple modal transpositions.

Path Parameters:

  • idName: URL-safe jins identifier: A jins's idName (jins_segah), its numeric id, or the idName of one of its transpositions (jins_segah_al_tik_hisar). A transposed idName works like adding transposeTo for its tonic; giving it together with a different transposeTo is a 400. The older closed-up spelling (jins_segah_altik_hisar) is also accepted. (string) (required)
    • Example: jins_bayyat

Query Parameters:

  • tuningSystems (required): Comma-separated list of tuning system IDs. product of these tuning systems with the requested startingNotes (outer loop = tuningSystems, inner loop = startingNotes). Use all to include every tuning system in the archive (cannot be combined with explicit IDs).
  • Type: string
  • Example: alsabbagh_1954,ibnsina_1037
  • startingNotes (required): Comma-separated list of starting note names (URL-safe, diacritics-insensitive). response contains N × M cells for N tuning systems × M starting notes, in user-supplied order. If a starting note is not available in a given tuning system that cell carries an informational note field (with a validStartingNotes namespace) rather than pitch data.
  • Type: string
  • Example: rast,yegah,ushayran
  • pitchClassDataType (optional): Output format for pitch class data. Defaults to all when omitted. - Type: string - Valid values: all, englishName, solfege, fraction, cents, ... (14 total) - Default: all
    • Example: cents
  • includeIntervals (optional): Whether to include interval data between adjacent pitch classes on each cell. Defaults to "false" when omitted.. Defaults to "false" when omitted.
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • transposeTo (optional): Transpose every successful cell to the given tonic note (applies to every cell in the Cartesian product). Cartesian product). If the requested target is not reachable in a given cell the cell carries an error plus an availableTranspositions list.
  • Type: string
  • Example: nawa
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with Ar suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names and jins names get Arabic versions in *Ar fields
    • Tuning system display names get Arabic versions in displayNameAr if available
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/ajnas/jins_bayyat/compare?tuningSystems=alsabbagh_1954,ibnsina_1037&startingNotes=rast,yegah,ushayran&includeArabic=true"

Response: Comparison data retrieved successfully. Note that the response is always HTTP 200 regardless of per-cell outcomes; individual failures (missing starting note, tuning system not found, jins not realizable, unreachable transposeTo) are reported on the respective cell via note or error fields. The counters successfulComparisons + unavailableStartingNotes + failedComparisons always equal totalComparisons.

Example response — twoTuningSystems:

json
{
  "jins": {
    "id": "19",
    "idName": "jins_rast",
    "displayName": "jins rāst",
    "version": "2025-10-18T19:34:26.343Z"
  },
  "comparisons": {
    "count": 1,
    "totalComparisons": 1,
    "successfulComparisons": 1,
    "unavailableStartingNotes": 0,
    "failedComparisons": 0,
    "data": [
      {
        "tuningSystem": {
          "id": "alsabbagh_1954",
          "idName": "alsabbagh_1954",
          "displayName": "al-Ṣabbāgh (1954) Contemporary Arabic Tuning 24-Tone",
          "version": "2025-10-18T19:42:23.643Z"
        },
        "startingNote": {
          "idName": "rast",
          "displayName": "rāst"
        },
        "jins": {
          "id": "19",
          "idName": "jins_rast",
          "displayName": "jins rāst",
          "version": "2025-10-18T19:34:26.343Z"
        },
        "tonic": {
          "idName": "rast",
          "displayName": "rāst"
        },
        "stats": {
          "tuningSystem": {
            "numberOfPitchClassesSingleOctave": 24,
            "referenceFrequency": 130.665
          },
          "jins": {
            "numberOfPitchClasses": 4
          }
        },
        "availableTranspositions": [],
        "pitchData": [
          {
            "pitchClassIndex": 0,
            "octave": 1,
            "scaleDegree": "I",
            "noteName": "rast",
            "noteNameDisplay": "rāst",
            "cents": 0
          },
          {
            "pitchClassIndex": 4,
            "octave": 1,
            "scaleDegree": "II",
            "noteName": "dugah",
            "noteNameDisplay": "dūgāh",
            "cents": 203.91000173077484
          },
          {
            "pitchClassIndex": 7,
            "octave": 1,
            "scaleDegree": "III",
            "noteName": "segah",
            "noteNameDisplay": "segāh",
            "cents": 356.8630927494849
          },
          {
            "pitchClassIndex": 10,
            "octave": 1,
            "scaleDegree": "IV",
            "noteName": "chahargah",
            "noteNameDisplay": "chahārgāh",
            "cents": 498.0449991346125
          }
        ],
        "parameters": {
          "pitchClassDataType": "cents",
          "includeIntervals": true,
          "transposeTo": null
        },
        "links": {
          "detail": "https://diarmaqar.net/api/ajnas/jins_rast?tuningSystem=alsabbagh_1954&startingNote=r%C4%81st&pitchClassDataType=cents&includeIntervals=true",
          "availability": "https://diarmaqar.net/api/ajnas/jins_rast/availability"
        },
        "intervals": [
          {
            "cents": 203.91000173077484
          },
          {
            "cents": 152.95309101871007
          },
          {
            "cents": 141.1819063851276
          }
        ]
      }
    ]
  },
  "parameters": {
    "tuningSystems": {
      "idNames": [
        "alsabbagh_1954"
      ],
      "displayNames": [
        "alsabbagh_1954"
      ]
    },
    "startingNotes": {
      "idNames": [
        "rast"
      ],
      "displayNames": [
        "rast"
      ]
    },
    "pitchClassDataType": "cents",
    "includeIntervals": true,
    "transposeTo": null
  },
  "links": {
    "self": "https://diarmaqar.net/api/ajnas/jins_rast/compare?tuningSystems=alsabbagh_1954&startingNotes=rast&pitchClassDataType=cents",
    "detail": "https://diarmaqar.net/api/ajnas/jins_rast",
    "availability": "https://diarmaqar.net/api/ajnas/jins_rast/availability"
  }
}

Tuning Systems ​

Historical tuning systems spanning from al-Kindī (874 CE) to contemporary approaches.

List all tuning systems ​

GET /tuning-systems

Retrieve metadata for all available tuning systems.

  • Includes identifiers, display names, version information, primary value type, and pitch class counts per octave
  • Responses include available starting note names for each tuning system
  • Different starting notes represent different theoretical frameworks (e.g., ʿushayrān for oud tuning, yegāh for monochord measurements)
  • Optional bibliographic source references (sourceId and page) when includeSources=true

Query Parameters:

  • includeSources (optional): Include bibliographic source references (sourceId and page) for each tuning system - Type: string - Valid values: true, false - Default: false
    • Example: true
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/tuning-systems?includeSources=true&includeArabic=true"

Response: List of tuning systems

Example response — english:

json
{
  "count": 35,
  "data": [
    {
      "tuningSystem": {
        "id": "ibnsina_1037",
        "idName": "ibnsina_1037",
        "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
        "version": "2025-10-18T19:42:23.643Z",
        "year": "1037"
      },
      "startingNotes": {
        "idNames": [
          "ushayran",
          "yegah"
        ],
        "displayNames": [
          "ʿushayrān",
          "yegāh"
        ]
      },
      "stats": {
        "numberOfPitchClassesSingleOctave": 17
      },
      "sources": [
        {
          "sourceId": "alshawwa_1946",
          "page": "49"
        }
      ]
    },
    {
      "tuningSystem": {
        "id": "alfarabi_950g",
        "idName": "alfarabi_950g",
        "displayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave) 27-Tone",
        "version": "2025-10-18T19:42:23.643Z",
        "year": "950g"
      },
      "startingNotes": {
        "idNames": [
          "ushayran",
          "yegah"
        ],
        "displayNames": [
          "ʿushayrān",
          "yegāh"
        ]
      },
      "stats": {
        "numberOfPitchClassesSingleOctave": 27
      },
      "sources": [
        {
          "sourceId": "alshawwa_1946",
          "page": "50"
        }
      ]
    }
  ]
}

Get Tuning System Details ​

GET /tuning-systems/{id}/{startingNote}/pitch-classes

Get Tuning System Details - Returns all pitch classes for a specific tuning system and starting note.

This endpoint is essential for tuning system operations, providing comprehensive pitch class data across all octaves with full formatting options.

Path Parameters:

  • id: Tuning system identifier (string) (required)
    • Example: cairocongresstuningcommittee_1929
  • startingNote: Tuning system starting note name (URL-safe, diacritics-insensitive). Use yegah for IbnSina/Meshshaqa, ushayran for al-Farabi/al-Kindi, rast for CairoCongress/al-Sabbagh (string) (required)
    • Example: rast

Query Parameters:

  • pitchClassDataType (optional): Pitch class data format.
    • all returns all available fields including englishName, solfege, abjadName, fraction, cents, decimalRatio, stringLength, frequency, fretDivision, midiNoteDecimal, midiNotePlusCentsDeviation, centsDeviation, ipnReferenceNoteName
    • Use a specific value to return only that field plus minimal identifiers
  • Type: string - Valid values: all, englishName, solfege, fraction, cents, ... (14 total) - Default: all
  • Example: all
  • octave (optional): Filter by octave number. Use a specific octave number (0, 1, 2, 3) to filter to that octave only.
  • Type: string - Valid values: all, 0, 1, 2, 3 - Default: all
  • Example: all
  • includeSources (optional): Include bibliographic source references (sourceId and page) for the tuning system - Type: string - Valid values: true, false - Default: false
    • Example: true
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/tuning-systems/cairocongresstuningcommittee_1929/rast/pitch-classes?includeSources=true&includeArabic=true"

Response: Tuning system pitch classes retrieved successfully

Example response:

json
{
  "tuningSystem": {
    "id": "ibnsina_1037",
    "idName": "ibnsina_1037",
    "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
    "version": "2025-11-09T00:44:40.275Z",
    "year": "1037",
    "numberOfPitchClassesSingleOctave": 17
  },
  "startingNotes": {
    "idNames": [
      "ushayran",
      "yegah"
    ],
    "displayNames": [
      "ʿushayrān",
      "yegāh"
    ]
  },
  "selectedStartingNote": {
    "idName": "yegah",
    "displayName": "yegāh"
  },
  "stats": {
    "totalPitchClasses": 17,
    "numberOfPitchClassesSingleOctave": 17,
    "referenceFrequency": 97.999,
    "octaves": [
      0,
      1,
      2,
      3
    ]
  },
  "pitchClasses": [
    {
      "pitchClassIndex": 0,
      "octave": 0,
      "noteName": "qarar_yegah",
      "noteNameDisplay": "qarār yegāh",
      "cents": -1200
    },
    {
      "pitchClassIndex": 1,
      "octave": 0,
      "noteName": "qarar_qarar_hisar",
      "noteNameDisplay": "qarār qarār ḥiṣār",
      "cents": -1088.691430896177
    },
    {
      "pitchClassIndex": 2,
      "octave": 0,
      "noteName": "qarar_qarar_tik_hisar/shuri",
      "noteNameDisplay": "qarār qarār tīk ḥiṣār/shūrī",
      "cents": -1061.427339096077
    },
    {
      "pitchClassIndex": 3,
      "octave": 0,
      "noteName": "qarar_ushayran",
      "noteNameDisplay": "qarār ʿushayrān",
      "cents": -996.0899982692251
    },
    {
      "pitchClassIndex": 4,
      "octave": 0,
      "noteName": "qarar_ajam_ushayran",
      "noteNameDisplay": "qarār ʿajam ʿushayrān",
      "cents": -905.8650025961624
    },
    {
      "…": "truncated — 63 more items"
    }
  ],
  "context": {
    "pitchClassDataType": "cents",
    "octave": "all"
  },
  "links": {
    "self": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037/yegah/pitch-classes",
    "tuningSystem": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037"
  },
  "sources": [
    {
      "sourceId": "farmer_1937",
      "page": "249"
    }
  ]
}

List maqāmāt available in a tuning system ​

GET /tuning-systems/{id}/{startingNote}/maqamat

Return all maqāmāt that can be realized in a given tuning system beginning on a specific starting note name.

  • Feasibility is determined by comparing maqām note names to every pitch class the tuning system builds from that starting note, in all its octaves (the same pitch space transpositions and modulations are calculated in)
  • characteristics.hasSuyur is true when at least one sayr can be played on the maqām's base form in this pitch space (the suyūr GET /maqamat/{idName}?includeSuyur=true returns)

Path Parameters:

  • id: Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899') (string) (required)
    • Example: alfarabi_950g
  • startingNote: Tuning system starting note name (URL-safe, diacritics-insensitive). Use yegah for IbnSina/Meshshaqa, ushayran for al-Farabi/al-Kindi, rast for CairoCongress/al-Sabbagh (string) (required)
    • Example: ushayran

Query Parameters:

  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • includeMaqamDegrees (optional): When true, each maqām in data includes a maqamDegrees object with ascending and descending arrays of PAO note name idNames (URL-safe identifiers for scale degrees).. of PAO note name idNames (URL-safe identifiers for scale degrees).
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • includeDegreeDetails (optional): When true (and when includeMaqamDegrees=true), the endpoint returns maqamDegrees.ascending / maqamDegrees.descending as arrays of objects { noteName, englishName, solfege, ipnReferenceNoteName, centsDeviation, midiNotePlusCentsDeviation } instead of note-name strings. The same transformation applies to transpositions[].maqamDegrees. maqamDegrees.descending as arrays of objects { noteName, englishName, solfege, ipnReferenceNoteName, centsDeviation, midiNotePlusCentsDeviation } instead of note-name strings. The same transformation applies to transpositions[].maqamDegrees. The last three fields are the same as in GET /maqamat/{id}: the 12-EDO key the degree is spelled against (ipnReferenceNoteName, e.g. "Bb"), the degree's deviation from it in cents (centsDeviation), and the MIDI note number followed by the deviation (midiNotePlusCentsDeviation, e.g. "58 -9.8"). Each direction is spelled on its own, so an ascending and a descending degree may share a key.
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • includeTranspositions (optional): When true, each maqām in data includes a transpositions array with the other transpositions (excluding the base tonic). (excluding the base tonic). Each transposition has its own idName and displayName (maqam_rast_al_chahargah, "maqām rāst al-chahārgāh"; plus displayNameAr with inArabic=true), its tonic, and maqamDegrees with ascending/descending note name idNames for that transposed position. The idName works as a path segment: /maqamat/maqam_rast_al_chahargah.
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • includeOctaveRenderings (optional): When true, each maqām in data also has an octaveRenderings array: the base form an octave or more away, on the same modal degree (maqam_yegah_al_nawa, maqām yegāh on nawā). octave or more away, on the same modal degree (maqam_yegah_al_nawa, maqām yegāh on nawā). These are not taṣwīr, so they are never in transpositions. Entries have the same shape as transpositions. Together with the base form and transpositions, this lists every maqām form that maqām detail can refer to (in ajnas, the structural jins slots, modulations and lowerOctaveModulations). Every listed form carries formType (base, transposition or octaveRendering).
  • Type: string - Valid values: true, false - Default: false
  • sortBy (optional): Sort order for results. and /ajnas, which default to alphabetical) because the endpoint is intrinsically about a concrete pitch layout. Invalid values return HTTP 400.
  • Type: string - Valid values: alphabetical, tonic - Default: tonic
  • Example: tonic - Sort by tonic note priority across the full NoteName.ts octave-stratified order, alphabetical tiebreak
  • Example: alphabetical - Sort alphabetically by display name
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/tuning-systems/alfarabi_950g/ushayran/maqamat?includeArabic=true"

Response: Maqāmāt list retrieved successfully

Example response:

json
{
  "tuningSystem": {
    "id": "ibnsina_1037",
    "idName": "ibnsina_1037",
    "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
    "version": "2026-08-16T22:20:52.549Z",
    "year": "1037",
    "numberOfPitchClassesSingleOctave": 17
  },
  "startingNotes": {
    "idNames": [
      "ushayran",
      "yegah",
      "rast"
    ],
    "displayNames": [
      "ʿushayrān",
      "yegāh",
      "rāst"
    ]
  },
  "selectedStartingNote": {
    "idName": "yegah",
    "displayName": "yegāh"
  },
  "stats": {
    "totalMaqamatForStartingNote": 69,
    "totalMaqamatInLibrary": 145,
    "uniqueTonicCount": 8,
    "uniqueFamilyCount": 26,
    "referenceFrequency": 98
  },
  "data": [
    {
      "maqam": {
        "id": "34",
        "idName": "maqam_dilkeshidah",
        "displayName": "maqām dilkeshīdah",
        "version": "2025-10-18T19:41:17.132Z",
        "isBaseForm": true,
        "formType": "base"
      },
      "family": {
        "idName": "buselik_alhilu",
        "displayName": "būselīk (al-Ḥilū)"
      },
      "tonic": {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      "stats": {
        "numberOfPitchClasses": 7
      },
      "characteristics": {
        "isOctaveRepeating": true,
        "hasAsymmetricDescending": true,
        "hasSuyur": true
      },
      "links": {
        "detail": "https://diarmaqar.net/api/maqamat/maqam_dilkeshidah"
      },
      "transpositions": [
        {
          "idName": "maqam_dilkeshidah_al_qarar_rast",
          "displayName": "maqām dilkeshīdah al-qarār rāst",
          "tonic": {
            "idName": "qarar_rast",
            "displayName": "qarār rāst"
          },
          "isBaseForm": false,
          "formType": "transposition",
          "maqamDegrees": {
            "ascending": [
              "qarar_rast",
              "qarar_dugah",
              "qarar_kurdi",
              "qarar_chahargah",
              "yegah",
              "qarar_tik_hisar_shuri",
              "kawasht"
            ],
            "descending": [
              "ajam_ushayran",
              "qarar_tik_hisar_shuri",
              "yegah",
              "qarar_chahargah",
              "qarar_kurdi",
              "qarar_dugah",
              "qarar_rast"
            ]
          }
        }
      ],
      "octaveRenderings": [
        {
          "idName": "maqam_dilkeshidah_al_qarar_yegah",
          "displayName": "maqām dilkeshīdah al-qarār yegāh",
          "tonic": {
            "idName": "qarar_yegah",
            "displayName": "qarār yegāh"
          },
          "isBaseForm": false,
          "formType": "octaveRendering",
          "maqamDegrees": {
            "ascending": [
              "qarar_yegah",
              "qarar_ushayran",
              "qarar_ajam_ushayran",
              "qarar_rast",
              "qarar_dugah",
              "qarar_segah",
              "qarar_hijaz"
            ],
            "descending": [
              "qarar_chahargah",
              "qarar_segah",
              "qarar_dugah",
              "qarar_rast",
              "qarar_ajam_ushayran",
              "qarar_ushayran",
              "qarar_yegah"
            ]
          }
        }
      ]
    },
    {
      "maqam": {
        "id": "30",
        "idName": "maqam_farahfazza",
        "displayName": "maqām faraḥfazzā",
        "version": "2026-07-25T15:22:12.206Z",
        "isBaseForm": true,
        "formType": "base"
      },
      "family": {
        "idName": "buselik_alhilu",
        "displayName": "būselīk (al-Ḥilū)"
      },
      "tonic": {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      "stats": {
        "numberOfPitchClasses": 7
      },
      "characteristics": {
        "isOctaveRepeating": true,
        "hasAsymmetricDescending": true,
        "hasSuyur": true
      },
      "links": {
        "detail": "https://diarmaqar.net/api/maqamat/maqam_farahfazza"
      },
      "transpositions": [
        {
          "idName": "maqam_farahfazza_al_qarar_ushayran",
          "displayName": "maqām faraḥfazzā al-qarār ʿushayrān",
          "tonic": {
            "idName": "qarar_ushayran",
            "displayName": "qarār ʿushayrān"
          },
          "isBaseForm": false,
          "formType": "transposition",
          "maqamDegrees": {
            "ascending": [
              "qarar_ushayran",
              "qarar_kawasht",
              "qarar_rast",
              "qarar_dugah",
              "qarar_buselik_ushshaq",
              "qarar_chahargah",
              "yegah"
            ],
            "descending": [
              "qarar_hisar",
              "qarar_chahargah",
              "qarar_buselik_ushshaq",
              "qarar_dugah",
              "qarar_rast",
              "qarar_kawasht",
              "qarar_ushayran"
            ]
          }
        }
      ],
      "octaveRenderings": [
        {
          "idName": "maqam_farahfazza_al_qarar_yegah",
          "displayName": "maqām faraḥfazzā al-qarār yegāh",
          "tonic": {
            "idName": "qarar_yegah",
            "displayName": "qarār yegāh"
          },
          "isBaseForm": false,
          "formType": "octaveRendering",
          "maqamDegrees": {
            "ascending": [
              "qarar_yegah",
              "qarar_ushayran",
              "qarar_ajam_ushayran",
              "qarar_rast",
              "qarar_dugah",
              "qarar_kurdi",
              "qarar_chahargah"
            ],
            "descending": [
              "qarar_hijaz",
              "qarar_kurdi",
              "qarar_dugah",
              "qarar_rast",
              "qarar_ajam_ushayran",
              "qarar_ushayran",
              "qarar_yegah"
            ]
          }
        }
      ]
    }
  ],
  "links": {
    "self": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037/yegah/maqamat",
    "tuningSystem": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037",
    "collection": "https://diarmaqar.net/api/maqamat"
  }
}

List ajnās available in a tuning system ​

GET /tuning-systems/{id}/{startingNote}/ajnas

Return all ajnās that can be realized in a given tuning system beginning on a specific starting note name.

  • Feasibility is determined by comparing jins note names to every pitch class the tuning system builds from that starting note, in all its octaves (the same pitch space transpositions and modulations are calculated in)
  • A jins is a single ascending set of note names, so unlike a maqām it has no descending counterpart, no sayr and no family classification. jinsDegrees is therefore one array rather than an ascending/descending pair
  • This is the ajnās counterpart of /tuning-systems/{id}/{startingNote}/maqamat and returns the same response shape

Path Parameters:

  • id: Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899') (string) (required)
    • Example: ibnsina_1037
  • startingNote: Tuning system starting note name (URL-safe, diacritics-insensitive). Use yegah for IbnSina/Meshshaqa, ushayran for al-Farabi/al-Kindi, rast for CairoCongress/al-Sabbagh (string) (required)
    • Example: yegah

Query Parameters:

  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr)
    • Jins names and note names get Arabic versions in *Ar fields
    • Tuning system display names get Arabic versions in displayNameAr if available
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • includeJinsDegrees (optional): When true, each jins in data includes a jinsDegrees array of PAO note name idNames (URL-safe identifiers for the jins degrees), in ascending order from the tonic.. (URL-safe identifiers for the jins degrees), in ascending order from the tonic.
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • includeDegreeDetails (optional): When true (and when includeJinsDegrees=true), the endpoint returns jinsDegrees as an array of objects { noteName, englishName, solfege } instead of note-name strings. objects { noteName, englishName, solfege } instead of note-name strings. The same transformation applies to transpositions[].jinsDegrees.
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • includeTranspositions (optional): When true, each jins in data includes a transpositions array with the other transpositions (taṣwīr) available in this tuning system, excluding the base tonic. (taṣwīr) available in this tuning system, excluding the base tonic. Each entry has its own idName and displayName (jins_rast_al_nawa, "jins rāst al-nawā"; plus displayNameAr with inArabic=true), its tonic, and jinsDegrees for that transposed position. The idName works as a path segment: /ajnas/jins_rast_al_nawa.
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • includeOctaveRenderings (optional): When true, each jins in data also has an octaveRenderings array: the base form an octave or more away, on the same modal degree (jins_yegah_al_nawa, jins yegāh on nawā). octave or more away, on the same modal degree (jins_yegah_al_nawa, jins yegāh on nawā). These are not taṣwīr, so they are never in transpositions. Entries have the same shape as transpositions. Together with the base form and transpositions, this lists every jins form that maqām detail can refer to (in ajnas, the structural jins slots, modulations and lowerOctaveModulations). Every listed form carries formType (base, transposition or octaveRendering).
  • Type: string - Valid values: true, false - Default: false
  • sortBy (optional): Sort order for results. defaults to alphabetical) because the endpoint is intrinsically about a concrete pitch layout. Invalid values return HTTP 400.
  • Type: string - Valid values: alphabetical, tonic - Default: tonic
  • Example: tonic - Sort by tonic note priority across the full NoteName.ts octave-stratified order, alphabetical tiebreak
  • Example: alphabetical - Sort alphabetically by display name
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/tuning-systems/ibnsina_1037/yegah/ajnas?includeArabic=true"

Response: Ajnās list retrieved successfully

Example response:

json
{
  "tuningSystem": {
    "id": "ibnsina_1037",
    "idName": "ibnsina_1037",
    "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
    "version": "2026-08-16T22:20:52.549Z",
    "year": "1037",
    "numberOfPitchClassesSingleOctave": 17
  },
  "startingNotes": {
    "idNames": [
      "ushayran",
      "yegah",
      "rast"
    ],
    "displayNames": [
      "ʿushayrān",
      "yegāh",
      "rāst"
    ]
  },
  "selectedStartingNote": {
    "idName": "yegah",
    "displayName": "yegāh"
  },
  "stats": {
    "totalAjnasForStartingNote": 39,
    "totalAjnasInLibrary": 44,
    "uniqueTonicCount": 10,
    "referenceFrequency": 98
  },
  "data": [
    {
      "jins": {
        "id": "39",
        "idName": "jins_qaf",
        "displayName": "jins qāf",
        "version": "2026-07-20T09:57:37.540Z",
        "isBaseForm": true,
        "formType": "base"
      },
      "tonic": {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      "stats": {
        "numberOfPitchClasses": 4
      },
      "links": {
        "detail": "https://diarmaqar.net/api/ajnas/jins_qaf"
      },
      "transpositions": [
        {
          "idName": "jins_qaf_al_qarar_rast",
          "displayName": "jins qāf al-qarār rāst",
          "tonic": {
            "idName": "qarar_rast",
            "displayName": "qarār rāst"
          },
          "isBaseForm": false,
          "formType": "transposition",
          "jinsDegrees": [
            "qarar_rast",
            "qarar_zirguleh",
            "qarar_kurdi",
            "qarar_hijaz"
          ]
        }
      ],
      "octaveRenderings": [
        {
          "idName": "jins_qaf_al_qarar_yegah",
          "displayName": "jins qāf al-qarār yegāh",
          "tonic": {
            "idName": "qarar_yegah",
            "displayName": "qarār yegāh"
          },
          "isBaseForm": false,
          "formType": "octaveRendering",
          "jinsDegrees": [
            "qarar_yegah",
            "qarar_qarar_hisar",
            "qarar_ajam_ushayran",
            "qarar_zirguleh"
          ]
        }
      ]
    },
    {
      "jins": {
        "id": "48",
        "idName": "jins_shad_araban",
        "displayName": "jins shad ʿarabān",
        "version": "2026-07-20T18:09:15.658Z",
        "isBaseForm": true,
        "formType": "base"
      },
      "tonic": {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      "stats": {
        "numberOfPitchClasses": 4
      },
      "links": {
        "detail": "https://diarmaqar.net/api/ajnas/jins_shad_araban"
      },
      "transpositions": [
        {
          "idName": "jins_shad_araban_al_qarar_ajam_ushayran",
          "displayName": "jins shad ʿarabān al-qarār ʿajam ʿushayrān",
          "tonic": {
            "idName": "qarar_ajam_ushayran",
            "displayName": "qarār ʿajam ʿushayrān"
          },
          "isBaseForm": false,
          "formType": "transposition",
          "jinsDegrees": [
            "qarar_ajam_ushayran",
            "qarar_kawasht",
            "qarar_dugah",
            "qarar_kurdi"
          ]
        }
      ],
      "octaveRenderings": [
        {
          "idName": "jins_shad_araban_al_qarar_yegah",
          "displayName": "jins shad ʿarabān al-qarār yegāh",
          "tonic": {
            "idName": "qarar_yegah",
            "displayName": "qarār yegāh"
          },
          "isBaseForm": false,
          "formType": "octaveRendering",
          "jinsDegrees": [
            "qarar_yegah",
            "qarar_qarar_hisar",
            "qarar_kawasht",
            "qarar_rast"
          ]
        }
      ]
    }
  ],
  "links": {
    "self": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037/yegah/ajnas",
    "tuningSystem": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037",
    "collection": "https://diarmaqar.net/api/ajnas"
  }
}

Modulations ​

Find modulation routes between maqāmāt ​

GET /modulation-routes

Calculate possible modulation routes between maqāmāt, similar to a navigation/maps application.

Uses al-Shawwā's 1946 modulation rules to find shortest paths between a source and target maqām, with optional waypoints and return-to-start functionality.

Key Features:

  • Finds shortest paths (fewest modulation steps) using BFS algorithm
  • Supports waypoints for multi-stop journeys
  • Optional return-to-start for round-trip routes (reflecting traditional maqām performance practice)
  • limitToShortestHops=true returns only the shortest-length routes; default (false) pads the result with progressively longer routes up to maxRoutes / maxHops
  • allowOctaveJumps=true lets BFS traverse register-shift (8va/8vb) edges between register-equivalent siblings; default (false) keeps routes strictly within al-Shawwā's scale-degree modulation rules
  • allowDownwardModulation=true lets BFS traverse direct downward-modulation edges (*OctaveBelow categories, e.g. sixthDegreeAscOctaveBelow / VI-8vb). These are single-hop modulations to a different maqām whose tonic sits one octave below the ascending rule's target — common in Arabic practice (e.g. saba:dūgāh → ajam ushayrān:ajam ushayrān as one move). Default (false) ignores those edges
  • Results cached per tuning system + starting note combination for performance
  • maxHops is required and capped at 20 to prevent combinatorial explosion

Graph Structure:

  • Nodes: Each (maqamId, tonic) pair is a unique node
  • Edges: Modulation possibilities based on al-Shawwā's rules (scale degrees I, III, IV, V, VI)

Performance Notes:

  • maxHops is required to prevent combinatorial explosion
  • First request for a tuning system + starting note builds the graph (may take longer)
  • Subsequent requests use cached graph data

Query Parameters:

  • tuningSystem (required): Tuning system identifier (e.g., 'alfarabi_950g', 'ibnsina_1037') - Type: string
    • Example: alfarabi_950g
  • startingNote (required): Tuning system starting note name (URL-safe, diacritics-insensitive). This is MANDATORY as it affects which maqāmāt are available and their modulation possibilities.. This is MANDATORY as it affects which maqāmāt are available and their modulation possibilities.
  • Type: string
  • Example: ushayran
  • fromMaqam (required): Source maqam base ID (the starting point of the journey). Use the base maqam identifier (e.g., "maqam_nahawand"), not the transposition display name. Combine with fromTonic to specify a particular transposition.. Use the base maqam identifier (e.g., "maqam_nahawand"), not the transposition display name. Combine with fromTonic to specify a particular transposition.
  • Type: string
  • Example: maqam_rast
  • fromTonic (optional): Optional specific tonic for the source maqam (URL-safe). If not specified, uses the base form. - Type: string
    • Example: rast
  • toMaqam (required): Target maqam base ID (the destination of the journey). Use the base maqam identifier (e.g., "maqam_nahawand"), not the transposition display name. Combine with toTonic to specify a particular transposition.. Use the base maqam identifier (e.g., "maqam_nahawand"), not the transposition display name. Combine with toTonic to specify a particular transposition.
  • Type: string
  • Example: maqam_segah
  • toTonic (optional): Optional specific tonic for the target maqam (URL-safe). If not specified, uses the base form. - Type: string
    • Example: segah
  • maxHops (required): Maximum number of modulation steps allowed (required safeguard). Prevents combinatorial explosion in route calculation. Most musical modulation sequences are 2-4 hops. Maximum allowed value is 20.. Prevents combinatorial explosion in route calculation. Most musical modulation sequences are 2-4 hops. Maximum allowed value is 20.
  • Type: integer
  • Example: 5
  • waypoints (optional): Optional comma-separated waypoints to pass through. Format: maqamId:tonicId or just maqamId (uses canonical tonic). Example: "maqam_bayyat:dugah,maqam_saba". Format: maqamId:tonicId or just maqamId (uses canonical tonic). Example: "maqam_bayyat:dugah,maqam_saba"
  • Type: string
  • Example: maqam_bayyat:dugah
  • returnToStartingMaqam (optional): Whether to calculate the return path back to the source (starting) maqam. Reflects traditional maqām performance practice where music returns to the starting mode. When true, response includes both outbound and return routes.. Reflects traditional maqām performance practice where music returns to the starting mode. When true, response includes both outbound and return routes.
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • maxRoutes (optional): Maximum number of routes to return - Type: integer - Default: 10
    • Example: 10
  • limitToShortestHops (optional): When true, only routes at the minimum hop count are returned — all routes in the response share the same hops value. returned — all routes in the response share the same hops value. When false (default), the response is filled out with progressively longer simple paths (still capped by maxHops and maxRoutes, ordered shortest-first).
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • allowOctaveJumps (optional): When true, BFS may traverse register-shift (8va / 8vb) edges between register-equivalent siblings of the same maqām (e.g. edges between register-equivalent siblings of the same maqām (e.g. ḥijāz:muḥayyar → ḥijāz:dūgāh). These edges appear anywhere in a route — at the start, in the middle, or at the end — and let the algorithm reach register variants that aren't directly connected by scale-degree modulation. When false (default), those edges are ignored and every hop in every returned route must be a genuine al-Shawwā modulation (degrees I / III / IV / V / VI). Note: allowOctaveJumps controls PURE register shifts (same maqām, different octave). allowDownwardModulation controls DOWNWARD MODULATIONS (different maqām at a lower-octave tonic). They are independent flags.
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • allowDownwardModulation (optional): When true, BFS may traverse direct downward-modulation edges (*OctaveBelow categories, e.g. sixthDegreeAscOctaveBelow / VI-8vb). edges (*OctaveBelow categories, e.g. sixthDegreeAscOctaveBelow / VI-8vb). These represent a single-hop modulation to a different maqām whose tonic sits one octave below the corresponding ascending rule's target — common in Arabic practice (e.g. saba:dūgāh → ajam ushayrān:ajam ushayrān as one move rather than as VI↑ + 8vb). When false (default), those edges are ignored and such a move can only be reached via the equivalent two-hop ascending-modulation + register-shift combination.
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • includeArabic (optional): Return bilingual responses with Arabic script when true. Adds Arabic versions with "Ar" suffix (e.g., maqamDisplayNameAr, tonicDisplayAr). Adds Arabic versions with "Ar" suffix (e.g., maqamDisplayNameAr, tonicDisplayAr)
  • Type: string - Valid values: true, false - Default: false
  • Example: true
  • centsTolerance (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: number - Default: 5
    • Example: 5

Example:

bash
curl "https://diarmaqar.net/api/modulation-routes?tuningSystem=alfarabi_950g&startingNote=ushayran&fromMaqam=maqam_rast&toMaqam=maqam_segah&maxHops=5&includeArabic=true"

Response: Modulation routes calculated successfully

Example response — routeFound:

json
{
  "totalPossibleRoutes": {
    "outboundRoutesCount": 1,
    "data": [
      {
        "routeNumber": 1,
        "outboundRoute": {
          "hops": 2,
          "steps": [
            {
              "from": {
                "maqamId": "1",
                "maqamIdName": "maqam_rast",
                "maqamDisplayName": "maqām rāst",
                "tonicId": "rast",
                "tonicDisplay": "rāst",
                "isTransposition": false
              },
              "to": {
                "maqamId": "2",
                "maqamIdName": "maqam_bayyat",
                "maqamDisplayName": "maqām bayyāt",
                "tonicId": "dugah",
                "tonicDisplay": "dūgāh",
                "isTransposition": false
              },
              "modulationDegree": "III",
              "modulationCategory": "thirdDegree"
            },
            {
              "from": {
                "maqamId": "2",
                "maqamIdName": "maqam_bayyat",
                "maqamDisplayName": "maqām bayyāt",
                "tonicId": "dugah",
                "tonicDisplay": "dūgāh",
                "isTransposition": false
              },
              "to": {
                "maqamId": "5",
                "maqamIdName": "maqam_hijaz",
                "maqamDisplayName": "maqām ḥijāz",
                "tonicId": "nawa",
                "tonicDisplay": "nawā",
                "isTransposition": false
              },
              "modulationDegree": "IV",
              "modulationCategory": "fourthDegree"
            }
          ]
        }
      }
    ]
  },
  "context": {
    "tuningSystem": {
      "id": "alfarabi_950g",
      "displayName": "al-Fārābī (950) غ"
    },
    "startingNote": {
      "idName": "ushayran",
      "displayName": "ʿushayrān"
    },
    "sourceNode": {
      "maqamId": "maqam_rast",
      "maqamDisplayName": "Maqam Rast",
      "tonicId": "rast",
      "tonicDisplay": "rāst",
      "isTransposition": false
    },
    "targetNode": {
      "maqamId": "maqam_hijaz",
      "maqamDisplayName": "Maqam Hijaz",
      "tonicId": "nawa",
      "tonicDisplay": "nawā",
      "isTransposition": false
    },
    "searchConstraints": {
      "maxHops": 5,
      "maxRoutes": 10,
      "returnToStartingMaqam": false,
      "limitToShortestHops": false,
      "allowOctaveJumps": false,
      "allowDownwardModulation": false
    }
  }
}

Pitch Classes ​

List all note names ​

GET /pitch-classes/note-names

Returns all note names used in the app, bilingually, sortable by note name order or alphabetically.

Note names are sourced from all octave arrays in NoteName.ts (octaveZeroNoteNames, octaveOneNoteNames, octaveTwoNoteNames, octaveThreeNoteNames, octaveFourNoteNames). Each note name includes:

  • Canonical order (index within its octave array)
  • Octave number (0-4)
  • English IPN equivalent

Note names are unique per octave, so the same note name string in different octaves represents different pitch classes.

Note: Availability data is not included in this endpoint (it's expensive to calculate). Use the availability endpoint (/api/pitch-classes/note-names/{noteName}/availability) to get availability information for a specific note name.

Query Parameters:

  • sortBy (optional): Sort order for results - Type: string - Valid values: order, alphabetical - Default: order
    • Example: order - Sort by canonical note name order (from NoteName.ts arrays)
    • Example: alphabetical - Sort alphabetically by display name
  • filterByTuningSystem (optional): Filter by tuning system ID to show only note names that exist in that system (URL-safe, case-insensitive, diacritics-insensitive). - Type: string
    • Example: meshshaqa_1899
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/pitch-classes/note-names?includeArabic=true"

Response: List of note names retrieved successfully

Example response:

json
{
  "count": 183,
  "data": [
    {
      "noteName": {
        "idName": "qarar_yegah",
        "displayName": "qarār yegāh"
      },
      "englishName": "G1",
      "order": 0,
      "octave": 0,
      "links": {
        "detail": "https://diarmaqar.net/api/pitch-classes/note-names/qarar_yegah",
        "availability": "https://diarmaqar.net/api/pitch-classes/note-names/qarar_yegah/availability"
      }
    },
    {
      "noteName": {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      "englishName": "G2",
      "order": 0,
      "octave": 1,
      "links": {
        "detail": "https://diarmaqar.net/api/pitch-classes/note-names/yegah",
        "availability": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/availability"
      }
    },
    {
      "noteName": {
        "idName": "nawa",
        "displayName": "nawā"
      },
      "englishName": "G3",
      "order": 0,
      "octave": 2,
      "links": {
        "detail": "https://diarmaqar.net/api/pitch-classes/note-names/nawa",
        "availability": "https://diarmaqar.net/api/pitch-classes/note-names/nawa/availability"
      }
    },
    {
      "noteName": {
        "idName": "saham/ramal_tuti",
        "displayName": "saham/ramal tūtī"
      },
      "englishName": "G4",
      "order": 0,
      "octave": 3,
      "links": {
        "detail": "https://diarmaqar.net/api/pitch-classes/note-names/saham/ramal_tuti",
        "availability": "https://diarmaqar.net/api/pitch-classes/note-names/saham/ramal_tuti/availability"
      }
    },
    {
      "noteName": {
        "idName": "qarar_qarar_nim_hisar",
        "displayName": "qarār qarār nīm ḥiṣār"
      },
      "englishName": "Ab--1",
      "order": 1,
      "octave": 0,
      "links": {
        "detail": "https://diarmaqar.net/api/pitch-classes/note-names/qarar_qarar_nim_hisar",
        "availability": "https://diarmaqar.net/api/pitch-classes/note-names/qarar_qarar_nim_hisar/availability"
      }
    },
    {
      "…": "truncated — 178 more items"
    }
  ]
}

Get pitch class details by note name ​

GET /pitch-classes/note-names/{noteName}

Get pitch class details for a note name, across all tuning systems or a specific one.

When querying by note name, the note name itself identifies the octave (note names are unique per octave). The octave parameter is optional and can be used for validation.

Supports:

  • Single tuning system with specific starting note
  • Single tuning system with startingNote="all" (returns array for all starting notes)
  • All tuning systems (returns array for all tuning systems and starting notes)

Path Parameters:

  • noteName: URL-safe note name (e.g., "rast", "dugah", "nawa") (string) (required)
    • Example: rast

Query Parameters:

  • tuningSystem (optional): Tuning system ID. - Type: string
    • Example: cairocongresstuningcommittee_1929
  • startingNote (optional): Starting note for the tuning system.
    • Use "all" to include all available starting notes for that tuning system (returns array of results, one per starting note) Note: Since note names are unique per octave, the note name itself identifies the octave. No octave parameter is needed. Use yegah for IbnSina/Meshshaqa, ushayran for al-Farabi/al-Kindi, rast for CairoCongress/al-Sabbagh
  • Type: string
  • Example: rast
  • pitchClassDataType (optional): Pitch class data format (defaults to all when omitted, matching the handler) - Type: string - Valid values: all, abjadName, englishName, solfege, fraction, ... (14 total) - Default: all
    • Example: cents
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/pitch-classes/note-names/rast?includeArabic=true"

Response: Pitch class data retrieved successfully

Example response:

json
{
  "context": {
    "tuningSystem": {
      "id": "ibnsina_1037",
      "idName": "ibnsina_1037",
      "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
      "version": "2025-11-09T00:44:40.275Z"
    },
    "startingNote": {
      "idName": "yegah",
      "displayName": "yegāh"
    },
    "noteName": {
      "idName": "yegah",
      "displayName": "yegāh"
    },
    "referenceFrequency": 97.999,
    "pitchClassDataType": "cents"
  },
  "pitchClass": {
    "pitchClassIndex": 0,
    "octave": 1,
    "noteName": "yegah",
    "noteNameDisplay": "yegāh",
    "cents": 0
  },
  "links": {
    "self": "https://diarmaqar.net/api/pitch-classes/note-names/yegah?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents",
    "availability": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/availability",
    "compare": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/compare"
  }
}

Check note name availability across tuning systems ​

GET /pitch-classes/note-names/{noteName}/availability

Check which tuning systems support a specific note name and what pitch class index it has in each tuning system.

Returns for each tuning system:

  • All starting notes where the note name exists
  • The pitch class index for each starting note
  • The octave where the note name was found

Path Parameters:

  • noteName: URL-safe note name (e.g., "rast", "dugah", "nawa") (string) (required)
    • Example: rast

Query Parameters:

  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/pitch-classes/note-names/rast/availability?includeArabic=true"

Response: Availability data retrieved successfully

Example response:

json
{
  "noteName": {
    "idName": "yegah",
    "displayName": "yegāh"
  },
  "availability": {
    "count": 35,
    "data": [
      {
        "tuningSystem": {
          "id": "ronzevalle_1904",
          "idName": "ronzevalle_1904",
          "displayName": "Ronzevalle (1904) Modernist Arabic Tuning",
          "version": "2025-11-26T10:19:38.569Z"
        },
        "startingNotes": [
          {
            "startingNote": {
              "idName": "ushayran",
              "displayName": "ʿushayrān"
            },
            "pitchClassIndex": 20,
            "octave": 0
          },
          {
            "startingNote": {
              "idName": "yegah",
              "displayName": "yegāh"
            },
            "pitchClassIndex": 0,
            "octave": 1
          }
        ]
      },
      {
        "tuningSystem": {
          "id": "alkindi_874",
          "idName": "alkindi_874",
          "displayName": "al-Kindī (874) 12-Tone",
          "version": "2025-11-17T13:16:34.754Z"
        },
        "startingNotes": [
          {
            "startingNote": {
              "idName": "ushayran",
              "displayName": "ʿushayrān"
            },
            "pitchClassIndex": 10,
            "octave": 0
          },
          {
            "startingNote": {
              "idName": "yegah",
              "displayName": "yegāh"
            },
            "pitchClassIndex": 0,
            "octave": 1
          },
          {
            "startingNote": {
              "idName": "rast",
              "displayName": "rāst"
            },
            "pitchClassIndex": 7,
            "octave": 0
          }
        ]
      },
      {
        "tuningSystem": {
          "id": "angloeuropean_1700",
          "idName": "angloeuropean_1700",
          "displayName": "Anglo-European (1700) 12-EDO",
          "version": "2025-11-18T11:53:58.428Z"
        },
        "startingNotes": [
          {
            "startingNote": {
              "idName": "ushayran",
              "displayName": "ʿushayrān"
            },
            "pitchClassIndex": 10,
            "octave": 0
          },
          {
            "startingNote": {
              "idName": "yegah",
              "displayName": "yegāh"
            },
            "pitchClassIndex": 0,
            "octave": 1
          }
        ]
      },
      {
        "tuningSystem": {
          "id": "aldik_1926a",
          "idName": "aldik_1926a",
          "displayName": "al-Dīk (1926a) al-Sullam al-Fārsī or al-'Arabī (!!!)",
          "version": "2025-10-18T19:42:23.643Z"
        },
        "startingNotes": [
          {
            "startingNote": {
              "idName": "yegah",
              "displayName": "yegāh"
            },
            "pitchClassIndex": 0,
            "octave": 1
          }
        ]
      },
      {
        "tuningSystem": {
          "id": "aldik_1926b",
          "idName": "aldik_1926b",
          "displayName": "al-Dīk (1926b) Old Arabic Scale",
          "version": "2025-10-18T19:42:23.643Z"
        },
        "startingNotes": [
          {
            "startingNote": {
              "idName": "yegah",
              "displayName": "yegāh"
            },
            "pitchClassIndex": 0,
            "octave": 1
          }
        ]
      },
      {
        "…": "truncated — 30 more items"
      }
    ]
  },
  "links": {
    "self": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/availability",
    "detail": "https://diarmaqar.net/api/pitch-classes/note-names/yegah",
    "compare": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/compare"
  }
}

Compare pitch class by note name across tuning systems ​

GET /pitch-classes/note-names/{noteName}/compare

Compare a pitch class (by note name) across different tuning systems.

Returns comprehensive data for each tuning system including:

  • Pitch class data in the requested format
  • Context information (tuning system, starting note, reference frequency)

Path Parameters:

  • noteName: URL-safe note name (e.g., "rast", "dugah", "nawa") (string) (required)
    • Example: rast

Query Parameters:

  • tuningSystems (required): Comma-separated tuning system IDs, or all for every tuning system (cannot be combined with explicit IDs). - Type: string
    • Example: meshshaqa_1899,cairocongresstuningcommittee_1929
  • startingNote (required): Starting note (applies to all tuning systems), or "all" to include all available starting notes for each tuning system. - Type: string
    • Example: yegah
  • pitchClassDataType (optional): Pitch class data format (defaults to all when omitted, matching the handler) - Type: string - Valid values: all, abjadName, englishName, solfege, fraction, ... (14 total) - Default: all
    • Example: cents
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/pitch-classes/note-names/rast/compare?tuningSystems=meshshaqa_1899,cairocongresstuningcommittee_1929&startingNote=yegah&includeArabic=true"

Response: Comparison data retrieved successfully

Example response:

json
{
  "context": {
    "noteName": {
      "idName": "yegah",
      "displayName": "yegāh"
    }
  },
  "comparisons": [
    {
      "tuningSystem": {
        "id": "ibnsina_1037",
        "idName": "ibnsina_1037",
        "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
        "version": "2025-11-09T00:44:40.275Z"
      },
      "startingNote": {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      "pitchClass": {
        "pitchClassIndex": 0,
        "octave": 1,
        "noteName": "yegah",
        "noteNameDisplay": "yegāh",
        "cents": 0
      },
      "context": {
        "referenceFrequency": 97.999,
        "pitchClassDataType": "cents"
      }
    },
    {
      "tuningSystem": {
        "id": "alfarabi_950g",
        "idName": "alfarabi_950g",
        "displayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave) 27-Tone",
        "version": "2025-10-18T19:42:23.643Z"
      },
      "startingNote": {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      "pitchClass": {
        "pitchClassIndex": 0,
        "octave": 1,
        "noteName": "yegah",
        "noteNameDisplay": "yegāh",
        "cents": 0
      },
      "context": {
        "referenceFrequency": 97.999,
        "pitchClassDataType": "cents"
      }
    }
  ],
  "meta": {
    "totalComparisons": 2,
    "successfulComparisons": 2,
    "failedComparisons": 0
  },
  "links": {
    "self": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/compare?tuningSystems=ibnsina_1037%2Calfarabi_950g&pitchClassDataType=cents&startingNote=yegah",
    "detail": "https://diarmaqar.net/api/pitch-classes/note-names/yegah",
    "availability": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/availability"
  }
}

Intervals ​

Calculate intervals by note names ​

GET /intervals

Get interval calculations for 2 or more pitch classes by listing their note names.

Calculates intervals between consecutive note names: [0→1, 1→2, 2→3, ...]

Supports:

  • Single tuning system with specific starting note
  • Single tuning system with startingNote="all" (returns array for all starting notes)
  • All tuning systems (returns array for all tuning systems and starting notes)

Note: When querying by note names, the pitchClassIndex field is excluded from interval responses as it is not meaningful in this context.

Query Parameters:

  • noteNames (required): Comma-separated note names (e.g., "rast,dugah,segah"). Note names can come from any octave. - Type: string
    • Example: rast,dugah,segah
  • tuningSystem (optional): Tuning system ID. - Type: string
    • Example: alsabbagh_1954
  • startingNote (optional): Starting note.
    • Use "all" to include all available starting notes for that tuning system (returns array of results, one per starting note) Note: Since note names are unique per octave, each note name already identifies its octave. No octave parameter is needed. Use yegah for IbnSina/Meshshaqa, ushayran for al-Farabi/al-Kindi, rast for CairoCongress/al-Sabbagh
  • Type: string
  • Example: rast
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/intervals?noteNames=rast,dugah,segah&includeArabic=true"

Response: Interval calculations retrieved successfully

Example response:

json
{
  "context": {
    "noteNames": [
      {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      {
        "idName": "dugah",
        "displayName": "dūgāh"
      },
      {
        "idName": "segah",
        "displayName": "segāh"
      }
    ]
  },
  "intervals": [
    {
      "tuningSystemContext": {
        "tuningSystem": {
          "id": "ibnsina_1037",
          "idName": "ibnsina_1037",
          "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
          "version": "2025-11-09T00:44:40.275Z"
        },
        "startingNote": {
          "idName": "yegah",
          "displayName": "yegāh"
        },
        "referenceFrequency": 97.999
      },
      "fromNote": {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      "toNote": {
        "idName": "dugah",
        "displayName": "dūgāh"
      },
      "intervalData": {
        "fraction": "3/2",
        "cents": 701.9550008653874,
        "decimalRatio": 1.5,
        "stringLength": -333.33333333333337,
        "fretDivision": 333.333,
        "originalValue": "3/2",
        "originalValueType": "fraction"
      }
    },
    {
      "tuningSystemContext": {
        "tuningSystem": {
          "id": "ibnsina_1037",
          "idName": "ibnsina_1037",
          "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
          "version": "2025-11-09T00:44:40.275Z"
        },
        "startingNote": {
          "idName": "yegah",
          "displayName": "yegāh"
        },
        "referenceFrequency": 97.999
      },
      "fromNote": {
        "idName": "dugah",
        "displayName": "dūgāh"
      },
      "toNote": {
        "idName": "segah",
        "displayName": "segāh"
      },
      "intervalData": {
        "fraction": "13/12",
        "cents": 138.57266090392318,
        "decimalRatio": 1.0833333333333333,
        "stringLength": -51.28205128205127,
        "fretDivision": 51.28199999999998,
        "originalValue": "13/12",
        "originalValueType": "fraction"
      }
    }
  ],
  "links": {
    "self": "https://diarmaqar.net/api/intervals?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents&noteNames=yegah%2Cdugah%2Csegah",
    "compare": "https://diarmaqar.net/api/intervals/compare?noteNames=yegah,dugah,segah"
  }
}

Compare intervals across tuning systems ​

GET /intervals/compare

Compare interval calculations for 2+ pitch classes across different tuning systems by listing their note names.

Calculates intervals between consecutive note names: [0→1, 1→2, 2→3, ...]

Note: When querying by note names, the pitchClassIndex field is excluded from interval responses as it is not meaningful in this context.

Query Parameters:

  • noteNames (required): Comma-separated note names. Note names can come from any octave. - Type: string
    • Example: rast,dugah,segah
  • tuningSystems (required): Comma-separated tuning system IDs, or all for every tuning system (cannot be combined with explicit IDs). - Type: string
    • Example: alfarabi_950g,cairocongresstuningcommittee_1929
  • startingNote (required): Starting note (applies to all tuning systems), or "all" to include all available starting notes for each tuning system. - Type: string
    • Example: ushayran
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/intervals/compare?noteNames=rast,dugah,segah&tuningSystems=alfarabi_950g,cairocongresstuningcommittee_1929&startingNote=ushayran&includeArabic=true"

Response: Comparison data retrieved successfully

Example response:

json
{
  "context": {
    "noteNames": [
      {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      {
        "idName": "dugah",
        "displayName": "dūgāh"
      },
      {
        "idName": "segah",
        "displayName": "segāh"
      }
    ]
  },
  "comparisons": [
    {
      "tuningSystem": {
        "id": "ibnsina_1037",
        "idName": "ibnsina_1037",
        "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
        "version": "2025-11-09T00:44:40.275Z"
      },
      "startingNote": {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      "intervals": [
        {
          "from": {
            "idName": "yegah",
            "displayName": "yegāh"
          },
          "to": {
            "idName": "dugah",
            "displayName": "dūgāh"
          },
          "interval": {
            "fraction": "3/2",
            "cents": 701.9550008653874,
            "decimalRatio": 1.5,
            "stringLength": -333.33333333333337,
            "fretDivision": 333.333,
            "originalValue": "3/2",
            "originalValueType": "fraction"
          }
        },
        {
          "from": {
            "idName": "dugah",
            "displayName": "dūgāh"
          },
          "to": {
            "idName": "segah",
            "displayName": "segāh"
          },
          "interval": {
            "fraction": "13/12",
            "cents": 138.57266090392318,
            "decimalRatio": 1.0833333333333333,
            "stringLength": -51.28205128205127,
            "fretDivision": 51.28199999999998,
            "originalValue": "13/12",
            "originalValueType": "fraction"
          }
        }
      ],
      "context": {
        "referenceFrequency": 97.999
      }
    },
    {
      "tuningSystem": {
        "id": "alfarabi_950g",
        "idName": "alfarabi_950g",
        "displayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave) 27-Tone",
        "version": "2025-10-18T19:42:23.643Z"
      },
      "startingNote": {
        "idName": "yegah",
        "displayName": "yegāh"
      },
      "intervals": [
        {
          "from": {
            "idName": "yegah",
            "displayName": "yegāh"
          },
          "to": {
            "idName": "dugah",
            "displayName": "dūgāh"
          },
          "interval": {
            "fraction": "3/2",
            "cents": 701.9550008653874,
            "decimalRatio": 1.5,
            "stringLength": -333.33333333333337,
            "fretDivision": 333.333,
            "originalValue": "3/2",
            "originalValueType": "fraction"
          }
        },
        {
          "from": {
            "idName": "dugah",
            "displayName": "dūgāh"
          },
          "to": {
            "idName": "segah",
            "displayName": "segāh"
          },
          "interval": {
            "fraction": "12/11",
            "cents": 150.63705850063081,
            "decimalRatio": 1.0909090909090908,
            "stringLength": -55.55555555555554,
            "fretDivision": 55.55599999999998,
            "originalValue": "12/11",
            "originalValueType": "fraction"
          }
        }
      ],
      "context": {
        "referenceFrequency": 97.999
      }
    }
  ],
  "meta": {
    "totalComparisons": 2,
    "successfulComparisons": 2,
    "failedComparisons": 0
  },
  "links": {
    "self": "https://diarmaqar.net/api/intervals/compare?tuningSystems=ibnsina_1037%2Calfarabi_950g&startingNote=yegah&pitchClassDataType=cents&noteNames=yegah%2Cdugah%2Csegah",
    "intervals": "https://diarmaqar.net/api/intervals?noteNames=yegah,dugah,segah"
  }
}

Calculate interval between two pitch classes ​

GET /intervals/calculate

Calculate the interval between two pitch classes in a specific tuning system.

Supports flexible pitch class identification:

  • By note name (e.g., "rast", "dugah")
  • By value in any format: fraction (e.g., "3/2"), cents (e.g., "701.955"), decimalRatio (e.g., "1.5"), stringLength, or fretDivision

Returns the interval in the requested unit format, plus all other unit formats for reference.

Query Parameters:

  • from (required): First pitch class identifier (note name or value) - Type: string
    • Example: rast
  • to (required): Second pitch class identifier (note name or value) - Type: string
    • Example: dugah
  • tuningSystem (required): Tuning system ID - Type: string
    • Example: ibnsina_1037
  • startingNote (required): Starting note for the tuning system - Type: string
    • Example: yegah
  • unit (required): Output unit format for the interval - Type: string - Valid values: fraction, cents, centsFromZero, decimalRatio, stringLength, fretDivision
    • Example: cents
  • fromType (optional): Type of 'from' value if it's a value (not a note name). Required if 'from' is a value and cannot be auto-detected.. Required if 'from' is a value and cannot be auto-detected.
  • Type: string - Valid values: fraction, cents, decimalRatio, stringLength, fretDivision
  • Example: fraction
  • toType (optional): Type of 'to' value if it's a value (not a note name). Required if 'to' is a value and cannot be auto-detected.. Required if 'to' is a value and cannot be auto-detected.
  • Type: string - Valid values: fraction, cents, decimalRatio, stringLength, fretDivision
  • Example: fraction
  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/intervals/calculate?from=rast&to=dugah&tuningSystem=ibnsina_1037&startingNote=yegah&unit=cents&includeArabic=true"

Response: Interval calculated successfully

Example response — noteNames:

json
{
  "context": {
    "tuningSystem": {
      "id": "ibnsina_1037",
      "idName": "ibnsina_1037",
      "displayName": "Ibn Sīnā (1037)"
    },
    "startingNote": {
      "idName": "yegah",
      "displayName": "yegāh"
    },
    "referenceFrequency": 97.999
  },
  "from": {
    "pitchClass": {
      "pitchClassIndex": 0,
      "octave": 0,
      "noteName": "yegah",
      "noteNameDisplay": "yegāh",
      "englishName": "D",
      "solfege": "re",
      "abjadName": "د",
      "fraction": "1/1",
      "cents": 0,
      "decimalRatio": 1,
      "stringLength": 1000,
      "fretDivision": 0
    },
    "identifier": {
      "idName": "yegah",
      "displayName": "yegāh"
    }
  },
  "to": {
    "pitchClass": {
      "pitchClassIndex": 1,
      "octave": 0,
      "noteName": "dugah",
      "noteNameDisplay": "dūgāh",
      "englishName": "E",
      "solfege": "mi",
      "abjadName": "ه",
      "fraction": "9/8",
      "cents": 203.91,
      "decimalRatio": 1.125,
      "stringLength": 888.889,
      "fretDivision": 102
    },
    "identifier": {
      "idName": "dugah",
      "displayName": "dūgāh"
    }
  },
  "interval": {
    "value": 203.91,
    "unit": "cents",
    "allUnits": {
      "fraction": "9/8",
      "cents": 203.91,
      "decimalRatio": 1.125,
      "stringLength": 111.111,
      "fretDivision": 102
    }
  },
  "links": {
    "self": "https://diarmaqar.net/api/intervals/calculate?from=yegah&to=dugah&tuningSystem=ibnsina_1037&startingNote=yegah&unit=cents",
    "tuningSystem": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037",
    "intervals": "https://diarmaqar.net/api/intervals?noteNames=yegah,dugah&tuningSystem=ibnsina_1037&startingNote=yegah"
  }
}

Sources ​

List all bibliographic sources ​

GET /sources

Return all bibliographic sources (books, articles, theses) with comprehensive metadata.

  • Includes titles, contributors, publication information, and version timestamps
  • Sources document the historical and scholarly foundation for the archive's musical data
  • All sources include common fields (edition, publication date, URL, etc.)
  • Type-specific fields are included based on sourceType:
    • Books: publisher, place, ISBN, original publication date
    • Articles: journal, volume, issue, page range, DOI
    • Theses: degree type, university, department, database information

Query Parameters:

  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/sources?includeArabic=true"

Response: List of sources retrieved successfully

Example response — comprehensive:

json
{
  "count": 2,
  "data": [
    {
      "id": "alkhulai_1904_2011",
      "displayName": "al-khulai-(1904/2011)",
      "citation": "al-Khulaʿī 1904/2011",
      "citationAr": "الخلعي 1904/2011",
      "sourceType": "Book",
      "title": "Kitāb al-Mūsiqā al-Sharqī",
      "titleAr": "كتاب الموسيقى الشرقي",
      "contributors": [
        {
          "type": "Author",
          "firstName": "Muḥammad Kāmil",
          "lastName": "al-Khulaʿī",
          "firstNameAr": "محمد كامل",
          "lastNameAr": "الخلعي"
        }
      ],
      "edition": "",
      "editionAr": "",
      "publicationDate": "2011",
      "publicationDateAr": "٢٠١١",
      "url": "https://www.hindawi.org/books/46319638/",
      "dateAccessed": "21-05-2025",
      "version": "2025-10-18T19:50:31.664Z",
      "originalPublicationDate": "1904",
      "originalPublicationDateAr": "١٩٠٤",
      "publisher": "Hindawi Foundation for Education and Culture",
      "publisherAr": "مؤسسة هنداوي للتعليم والثقافة",
      "place": "Cairo",
      "placeAr": "القاهرة",
      "ISBN": "9789776416543"
    },
    {
      "id": "farmer_1937",
      "displayName": "farmer-(1937)",
      "citation": "Farmer 1937",
      "citationAr": "فارمر 1937",
      "sourceType": "Article",
      "title": "The Lute Scale of Avicenna",
      "titleAr": "سلم العود لإبن سينا",
      "contributors": [
        {
          "type": "Author",
          "firstName": "Henry George",
          "lastName": "Farmer",
          "firstNameAr": "هنري جورج",
          "lastNameAr": "فارمر"
        }
      ],
      "edition": "",
      "editionAr": "",
      "publicationDate": "1937",
      "publicationDateAr": "١٩٣٧",
      "url": "",
      "dateAccessed": "",
      "version": "2025-10-18T19:50:31.664Z",
      "journal": "The Journal of the Royal Asiatic Society of Great Britain and Ireland",
      "journalAr": "مجلة الجمعية الملكية الآسيوية في بريطانيا العظمى وأيرلندا",
      "volume": "2",
      "volumeAr": "٢",
      "issue": "",
      "issueAr": "",
      "pageRange": "245–257",
      "pageRangeAr": "٢٤٥-٢٥٧",
      "DOI": ""
    },
    {
      "id": "allami_2022",
      "displayName": "allami-(2022)",
      "citation": "Allami 2022",
      "citationAr": "اللامي 2022",
      "sourceType": "Thesis",
      "title": "Échos-monde: Towards a hybrid repertoire of contemporary and experimental acoustic, electroacoustic and electronic Arabic music",
      "titleAr": "‎عالم الأصداء: نحو رصيدٍ هجينٍ للموسيقى العربية المعاصرة والتجريبية، صوتياً وكهروصوتياً وإلكترونياً",
      "contributors": [
        {
          "type": "Author",
          "firstName": "Khyam",
          "lastName": "Allami",
          "firstNameAr": "خيّام",
          "lastNameAr": "اللامي"
        }
      ],
      "edition": "",
      "editionAr": "",
      "publicationDate": "2022",
      "publicationDateAr": "",
      "url": "https://www.open-access.bcu.ac.uk/14036/",
      "dateAccessed": "16-10-2025",
      "version": "2025-10-23T22:32:56.276Z",
      "degreeType": "PhD Dissertation",
      "degreeTypeAr": "أطروحة دكتوراه",
      "university": "Birmingham City University",
      "universityAr": "جامعة برمنغهام سيتي",
      "department": "Royal Birmingham Conservatoire",
      "departmentAr": "معهد برمنغهام الملكي",
      "databaseIdentifier": "",
      "databaseName": ""
    }
  ],
  "meta": {
    "total": 17
  }
}

Get a single bibliographic source ​

GET /sources/{id}

Return detailed information for a single bibliographic source by ID.

  • Returns comprehensive bibliographic metadata for the specified source
  • Includes all common fields (title, contributors, publication date, etc.)
  • Includes type-specific fields based on sourceType:
    • Books: publisher, place, ISBN, original publication date
    • Articles: journal, volume, issue, page range, DOI
    • Theses: degree type, university, department, database information
  • Supports bilingual responses (English/Arabic) via includeArabic parameter

Path Parameters:

  • id: The unique identifier for the bibliographic source.

Examples:

  • alkhulai_1904_2011 - Book source ID (URL-safe, diacritics removed)
  • farmer_1937 - Article source ID
  • allami_2022 - Thesis source ID

Note: Source IDs use only the publication date (not original publication date) and are URL-safe with diacritics removed for compatibility.

Use the /api/sources endpoint to retrieve all available source IDs. (string) (required)

  • Example: farmer_1937

Query Parameters:

  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., titleAr, firstNameAr, lastNameAr)
    • Contributors get Arabic name versions in firstNameAr and lastNameAr fields
    • Type-specific fields get Arabic versions (e.g., publisherAr, journalAr, universityAr)
    • Display name gets Arabic version in displayNameAr field
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/sources/farmer_1937?includeArabic=true"

Response: Source retrieved successfully

Example response — book:

json
{
  "source": {
    "id": "alkhulai_1904_2011",
    "displayName": "al-khulai-(1904/2011)",
    "citation": "al-Khulaʿī 1904/2011",
    "sourceType": "Book",
    "title": "Kitāb al-Mūsiqā al-Sharqī",
    "contributors": [
      {
        "type": "Author",
        "firstName": "Muḥammad Kāmil",
        "lastName": "al-Khulaʿī"
      }
    ],
    "edition": "",
    "publicationDate": "2011",
    "url": "https://www.hindawi.org/books/46319638/",
    "dateAccessed": "21-05-2025",
    "version": "2025-10-18T19:50:31.664Z",
    "originalPublicationDate": "1904",
    "publisher": "Hindawi Foundation for Education and Culture",
    "place": "Cairo",
    "ISBN": "9789776416543"
  }
}

List tuning systems by source ​

GET /sources/{id}/tuning-systems

Returns all tuning systems that reference the specified source.

A tuning system is included if any of its sourcePageReferences match the source ID. This endpoint provides an easy way to see which tuning systems have been derived from a specific source.

Path Parameters:

  • id: The unique identifier for the bibliographic source.

Use the /api/sources endpoint to retrieve all available source IDs. (string) (required)

  • Example: farmer_1937

Query Parameters:

  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/sources/farmer_1937/tuning-systems?includeArabic=true"

Response: Tuning systems retrieved successfully

Example response:

json
{
  "context": {
    "source": {
      "id": "alsabbagh_1954",
      "idName": "alsabbagh_1954",
      "displayName": "al-Anghām al-Sharqīya: al-Qism al-Thānī min kitāb al-Dalīl al-Mūsīqī al-ʿĀm fi Aṭrab al-Anghām"
    }
  },
  "count": 1,
  "data": [
    {
      "tuningSystem": {
        "id": "alsabbagh_1954",
        "idName": "alsabbagh_1954",
        "displayName": "al-Ṣabbāgh (1954) Contemporary Arabic Tuning 24-Tone",
        "version": "2026-08-05T14:14:27.676Z",
        "year": "1954"
      },
      "sourceReferences": [
        {
          "page": "47"
        }
      ],
      "startingNotes": [
        "rast"
      ],
      "links": {
        "detail": "https://diarmaqar.net/api/tuning-systems/alsabbagh_1954",
        "source": "https://diarmaqar.net/api/sources/alsabbagh_1954"
      }
    }
  ]
}

List maqamat by source ​

GET /sources/{id}/maqamat

Returns all maqamat that reference the specified source.

A maqam is included if any of its sourcePageReferences match the source ID. This endpoint provides an easy way to see which maqamat have been documented in a specific source.

Path Parameters:

  • id: The unique identifier for the bibliographic source.

Use the /api/sources endpoint to retrieve all available source IDs. (string) (required)

  • Example: alshawwa_1946

Query Parameters:

  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/sources/alshawwa_1946/maqamat?includeArabic=true"

Response: Maqamat retrieved successfully

Example response:

json
{
  "context": {
    "source": {
      "id": "alshawwa_1946",
      "idName": "alshawwa_1946",
      "displayName": "al-Qawaʿid al-Fannīya fī al-Mūsiqa al-Sharqīya wa al-Gharbīya"
    }
  },
  "count": 36,
  "data": [
    {
      "maqam": {
        "id": "1",
        "idName": "maqam_rast",
        "displayName": "maqām rāst",
        "version": "2025-12-10T17:03:34.565Z"
      },
      "sourceReferences": [
        {
          "page": "42"
        }
      ],
      "links": {
        "detail": "https://diarmaqar.net/api/maqamat/maqam_rast",
        "source": "https://diarmaqar.net/api/sources/alshawwa_1946"
      }
    },
    {
      "maqam": {
        "id": "6",
        "idName": "maqam_nawa_athar",
        "displayName": "maqām nawā athar",
        "version": "2025-12-10T18:28:28.107Z"
      },
      "sourceReferences": [
        {
          "page": "52"
        }
      ],
      "links": {
        "detail": "https://diarmaqar.net/api/maqamat/maqam_nawa_athar",
        "source": "https://diarmaqar.net/api/sources/alshawwa_1946"
      }
    },
    {
      "maqam": {
        "id": "10",
        "idName": "maqam_nahawand",
        "displayName": "maqām nahāwand",
        "version": "2025-10-18T19:41:17.132Z"
      },
      "sourceReferences": [
        {
          "page": "49"
        }
      ],
      "links": {
        "detail": "https://diarmaqar.net/api/maqamat/maqam_nahawand",
        "source": "https://diarmaqar.net/api/sources/alshawwa_1946"
      }
    },
    {
      "maqam": {
        "id": "11",
        "idName": "maqam_nahawand_kabir",
        "displayName": "maqām nahāwand kabīr",
        "version": "2025-10-18T19:41:17.132Z"
      },
      "sourceReferences": [
        {
          "page": "50"
        }
      ],
      "links": {
        "detail": "https://diarmaqar.net/api/maqamat/maqam_nahawand_kabir",
        "source": "https://diarmaqar.net/api/sources/alshawwa_1946"
      }
    },
    {
      "maqam": {
        "id": "17",
        "idName": "maqam_ajam_ushayran",
        "displayName": "maqām ʿajam ʿushayrān",
        "version": "2025-10-18T19:41:17.132Z"
      },
      "sourceReferences": [
        {
          "page": "30"
        }
      ],
      "links": {
        "detail": "https://diarmaqar.net/api/maqamat/maqam_ajam_ushayran",
        "source": "https://diarmaqar.net/api/sources/alshawwa_1946"
      }
    },
    {
      "…": "truncated — 31 more items"
    }
  ]
}

List ajnas by source ​

GET /sources/{id}/ajnas

Returns all ajnas that reference the specified source.

A jins is included if any of its SourcePageReferences match the source ID. This endpoint provides an easy way to see which ajnas have been documented in a specific source.

Path Parameters:

  • id: The unique identifier for the bibliographic source.

Use the /api/sources endpoint to retrieve all available source IDs. (string) (required)

  • Example: alshawwa_1946

Query Parameters:

  • includeArabic (optional): Return bilingual responses with Arabic script when true.
    • All English/transliteration fields remain unchanged
    • Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr)
    • Note names, maqām names, and jins names get Arabic versions in *Ar fields
    • Comments get Arabic versions in commentsAr if available
    • Tuning system display names get Arabic versions in displayNameAr if available
    • Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)
  • Type: string - Valid values: true, false - Default: false
  • Example: true

Example:

bash
curl "https://diarmaqar.net/api/sources/alshawwa_1946/ajnas?includeArabic=true"

Response: Ajnas retrieved successfully

Example response:

json
{
  "context": {
    "source": {
      "id": "alshawwa_1946",
      "idName": "alshawwa_1946",
      "displayName": "al-Qawaʿid al-Fannīya fī al-Mūsiqa al-Sharqīya wa al-Gharbīya"
    }
  },
  "count": 2,
  "data": [
    {
      "jins": {
        "id": "21",
        "idName": "jins_buselik_alshawwa",
        "displayName": "jins būselīk (al-Shawwā)",
        "version": "2025-10-18T19:34:26.343Z"
      },
      "sourceReferences": [
        {
          "page": "70"
        }
      ],
      "links": {
        "detail": "https://diarmaqar.net/api/ajnas/jins_buselik_alshawwa",
        "source": "https://diarmaqar.net/api/sources/alshawwa_1946"
      }
    },
    {
      "jins": {
        "id": "24",
        "idName": "jins_awj_ara",
        "displayName": "jins awj ʾārāʾ",
        "version": "2025-10-18T19:34:26.343Z"
      },
      "sourceReferences": [
        {
          "page": "38"
        }
      ],
      "links": {
        "detail": "https://diarmaqar.net/api/ajnas/jins_awj_ara",
        "source": "https://diarmaqar.net/api/sources/alshawwa_1946"
      }
    }
  ]
}

Statistics ​

Get archive statistics ​

GET /statistics

Return the archive's totals and, for every tuning system on every starting note, how many ajnās and maqāmāt it can build, how many transpositions (taṣwīr) and octave renderings they have, and how many modulations their forms allow.

Each maqām or jins has three kinds of form in a tuning system:

  • base form: the maqām on its own notes, e.g. maqām rāst on rāst
  • transposition (taṣwīr): moved onto another tonic, e.g. maqām rāst al-nawā
  • octave rendering: the base form or a taṣwīr one or more octaves away, e.g. maqām rāst on qarār rāst. Not a taṣwīr, so never counted in transpositions.

Modulations follow al-Shawwā's 1946 guidelines. Each form's options are counted degree by degree, as GET /maqamat/{idName} lists them, then summed over the forms: a target on the sixth degree that qualifies both ascending and descending counts 2. They are kept apart by the kind of form they start from (fromBaseForms, fromTranspositions, fromOctaveRenderings); base forms plus transpositions is the headline figure the statistics page shows.

The numbers are computed before a deploy whenever the data they count has changed, not per request. They carry a dataFingerprint of that data and the time they were computed (generatedAt).

Example:

bash
curl "https://diarmaqar.net/api/statistics"

Response: Archive statistics retrieved successfully

Example response — oneRow:

json
{
  "dataFingerprint": "4f1c…",
  "generatedAt": "2026-11-10T19:30:00.000Z",
  "archive": {
    "tuningSystems": 28,
    "tuningSystemStartingNotes": 48,
    "maqamat": 145,
    "ajnas": 44,
    "suyur": 193,
    "sources": 19,
    "patterns": 7
  },
  "count": 48,
  "data": [
    {
      "tuningSystem": {
        "id": "ronzevalle_1904",
        "idName": "ronzevalle_1904",
        "displayName": "Ronzevalle (1904) Modernist Arabic Tuning",
        "year": "1904"
      },
      "startingNote": {
        "idName": "ushayran",
        "displayName": "ʿushayrān"
      },
      "ajnas": {
        "possible": 42,
        "total": 44,
        "transpositions": 3440,
        "octaveRenderings": 118
      },
      "maqamat": {
        "possible": 105,
        "total": 145,
        "transpositions": 7383,
        "octaveRenderings": 212,
        "suyur": 129
      },
      "modulations": {
        "fromBaseForms": {
          "maqamat": 50523,
          "ajnas": 20286
        },
        "fromTranspositions": {
          "maqamat": 1776759,
          "ajnas": 815983
        },
        "fromOctaveRenderings": {
          "maqamat": 91504,
          "ajnas": 40647
        }
      },
      "links": {
        "maqamat": "https://diarmaqar.net/api/tuning-systems/ronzevalle_1904/ushayran/maqamat",
        "ajnas": "https://diarmaqar.net/api/tuning-systems/ronzevalle_1904/ushayran/ajnas"
      }
    }
  ],
  "links": {
    "self": "https://diarmaqar.net/api/statistics"
  }
}

Digital Arabic Maqām Archive Documentation