# Digital Arabic Maqām Archive > Documentation Open-source multilingual platform integrating historically documented Arabic maqām theory within a unified computational framework ## For AI Assistants: API Access **API access**: All endpoints are public, unauthenticated, and return plain JSON. No browser, cookies, or authentication required. Standard HTTP GET requests work from any client (curl, fetch, etc.). **Recommended for AI Assistants**: Use the REST API to fetch real-time, accurate data for users. Always prefer API calls over documentation summaries for real-time data accuracy. **Error handling for AI assistants**: The API returns rich 400/404 bodies with `hint` and `validOptions` fields, but many AI HTTP tools cannot read 4xx response bodies. If a request fails with an opaque 400, do not guess — call `GET https://diarmaqar.net/api/maqamat/{idName}/availability` (or the equivalent `/availability` endpoint for ajnās) to get valid `tuningSystem` + `startingNote` combinations, then retry. **Entity ID format**: Tuning system and source `idName`/`id` values follow the `creator_year` convention, lowercase (e.g. `ibnsina_1037`, `forster_2010`). Maqām and jins IDs are prefixed accordingly (e.g. `maqam_rast`, `jins_rast`). Do not guess-case or hyphenate these — list them via `GET https://diarmaqar.net/api/tuning-systems`, `GET https://diarmaqar.net/api/maqamat`, or `GET https://diarmaqar.net/api/ajnas` if unsure. **Base URL**: https://diarmaqar.net/api **OpenAPI Specification**: https://diarmaqar.net/docs/openapi.json **Representative Examples**: https://diarmaqar.net/docs/api/representative-examples ### Example Requests for Novice Users For users who don't know specific maqam names, use these representative examples: **Most Common Examples (Recommended for beginners):** - "Tell me about a fundamental Arabic maqam" → GET https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents - "Show me a basic jins" → GET https://diarmaqar.net/api/ajnas/jins_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents - "What tuning systems are available?" → GET https://diarmaqar.net/api/tuning-systems - "What maqām families exist?" → GET https://diarmaqar.net/api/maqamat/families?tuningSystem=ibnsina_1037&startingNote=yegah - "Show me the most common tuning system" → GET https://diarmaqar.net/api/tuning-systems/ibnsina_1037/yegah/pitch-classes?pitchClassDataType=cents **Quick Test URL (Copy-paste ready):** ``` GET https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents ``` **When users ask general questions:** - "What is a maqam?" → Use GET https://diarmaqar.net/api/maqamat/maqam_rast (most fundamental example) - "Show me an Arabic scale" → Use GET https://diarmaqar.net/api/maqamat/maqam_rast (representative example) - "What are the intervals?" → Use GET https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents - "Compare different tuning systems" → GET https://diarmaqar.net/api/maqamat/maqam_rast/compare?tuningSystems=ibnsina_1037,alfarabi_950g&startingNotes=yegah&pitchClassDataType=cents **Representative Examples Reference:** - See /docs/api/representative-examples for complete list of recommended examples All endpoints return JSON with complete data including pitch classes, intervals, bibliographic sources, and more. Use the OpenAPI specification at /docs/openapi.json for complete endpoint documentation and parameter details. --- ## Cold-start discovery workflow If you don't have a specific maqām / jins / tuning system to go on, follow this chain: 1. `GET https://diarmaqar.net/api/maqamat` → pick an `idName` from `data[]` 2. `GET https://diarmaqar.net/api/maqamat/{idName}/availability` → pick a compatible `tuningSystem` + `startingNote` 3. `GET https://diarmaqar.net/api/maqamat/{idName}?tuningSystem=…&startingNote=…&pitchClassDataType=cents` Parallel chains for ajnās, tuning systems, pitch classes, intervals, and sources follow the same pattern: **list → availability → detail**. Note: build every request as an absolute `https://diarmaqar.net/api/…` URL. Some HTTP clients cannot resolve a relative path on their own. Tip: `options=true` on a detail endpoint needs only `tuningSystem` — it returns the valid starting notes (idNames), and once `startingNote` is added, the valid `transposeTo` tonics. Tip: compare one value across EVERY tuning system in a single call with `tuningSystems=all` on any /compare endpoint (combine with `startingNote=all` for all framings), e.g. `GET https://diarmaqar.net/api/pitch-classes/note-names/segah/compare?tuningSystems=all&startingNote=all&pitchClassDataType=cents`. `all` cannot be combined with explicit IDs. If you omit required parameters, the API returns a 400 response whose body contains a `hint` field pointing at the next URL to call. **Important for AI assistants**: many AI HTTP tools cannot read the body of a 4xx response — you may only see "HTTP 400" with no explanation. Never guess parameters after an opaque 400. Instead, go back to step 2: the availability endpoint returns every valid `tuningSystem` + `startingNote` combination for an entity, so requests built from it succeed on the first try. --- ## Discovery - robots.txt: /robots.txt - Sitemap: /sitemap.xml ## Documentation Links - [Full LLM Documentation](/docs/llms-full.txt) - Complete documentation content - [Root LLM Index](/llms.txt) - Root-level LLM-friendly index - [Main Documentation](/docs/) - Human-readable documentation - [API Documentation](/docs/api/) - Complete API reference - [Representative Examples](/docs/api/representative-examples) - Ready-to-use API examples --- ## Table of Contents ### Getting Started - [Getting Started](/docs/guide.md): Introduction to the Digital Arabic Maqām Archive (DiArMaqAr) - [Quick Start Guide](/docs/guide/quick-start.md): Get up and running with DiArMaqAr quickly ### Core Concepts - [Theoretical Framework](/docs/guide/theoretical-framework.md): Understanding the conceptual hierarchy and foundations of Arabic maqām theory in DiArMaqAr - [Tanāghīm (Tuning Systems)](/docs/guide/tuning-systems.md): Understanding tanāghīm (tuning systems) and their role in Arabic maqām theory - [Ajnās](/docs/guide/ajnas.md): Understanding ajnās as the building blocks of maqāmāt - [Maqāmāt](/docs/guide/maqamat.md): Understanding maqāmāt as complete modal frameworks - [Suyūr](/docs/guide/suyur.md): Understanding suyūr as traditional melodic development pathways ### Advanced Features - [Taṣwīr (Transposition)](/docs/guide/taswir.md): Understanding tuning-system-sensitive transposition capabilities - [Intiqāl (Modulation)](/docs/guide/intiqal.md): Understanding Al-Shawwā's modulation algorithm and modulation networks - [Audio Synthesis](/docs/guide/audio-synthesis.md): Real-time audio synthesis capabilities for auditioning maqāmāt and tuning systems - [MIDI Integration](/docs/guide/midi-integration.md): MIDI input/output capabilities including MPE support for precise non-12-EDO playback - [Data Export](/docs/guide/data-export.md): Comprehensive data export capabilities for research and composition ### Research and Methodology - [Research Applications](/docs/guide/research-applications.md): Research use cases and academic applications of DiArMaqAr - [Cultural Framework](/docs/guide/cultural-framework.md): Decolonial computing principles and culture-specific methodology - [Bibliographic Sources](/docs/guide/bibliographic-sources.md): Comprehensive source attribution and scholarly verification - [PAO Note Names](/docs/guide/note-names.md): The full list of Persian-Arab-Ottoman note names used in DiArMaqAr, with their sources ### API Getting Started - [API Documentation](/docs/api.md): Programmatic access to Arabic maqāmāt, ajnās, and tuning systems data - [Representative Examples](/docs/api/representative-examples.md): Recommended tuning systems, maqāmāt, and ajnās for proper API usage ### Static Documentation - [API Endpoints Reference](/docs/api/endpoints-reference.md): Complete API endpoint documentation #### Endpoints Reference - [API Endpoints Reference](/api/endpoints-reference.md): Complete API endpoint documentation #### Maqāmāt #### Ajnās #### Tuning Systems #### Pitch Classes #### Intervals #### Sources #### Statistics ### Other - [Digital Arabic Maqām Archive (DiArMaqAr)](/docs/README DiArMaqAr Tuning System JSON Data Export.md) - [Documentation Generation Scripts](/docs/scripts/README.md)