# Digital Arabic Maqām Archive (DiArMaqAr)
# LLM-Friendly Documentation Index

## Discovery
- robots.txt: /robots.txt
- Sitemap: /sitemap.xml

## Documentation
- Main Documentation: /docs/
- LLM-Optimized Index: /docs/llms.txt
- Full LLM Documentation: /docs/llms-full.txt
- API Documentation: /docs/api/
- OpenAPI Specification: /docs/openapi.json

## API Access
- Base URL: https://diarmaqar.netlify.app/api
- OpenAPI Spec: /docs/openapi.json
- Interactive Playground: /docs/api/playground

### For AI Assistants and LLMs

**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. When users ask about maqāmāt, ajnās, or tuning systems, use the API endpoints to fetch current, complete data rather than relying on cached documentation.

**⚠️ CRITICAL: Required Parameters**

All detail endpoints (`/api/maqamat/{id}`, `/api/ajnas/{id}`) **REQUIRE** three parameters:
1. `tuningSystem` - ID of tuning system (e.g., `ibnsina_1037`)
2. `startingNote` - Starting note in URL-safe format (e.g., `yegah`, `ushayran`)
3. `pitchClassDataType` - Format for pitch class data (e.g., `cents`, `fraction`, `all`)

**Common Mistakes to Avoid:**
- ❌ `GET /api/maqamat/maqam_rast` (missing required parameters)
- ❌ `GET /api/maqamat/rast` (wrong endpoint format - missing "maqam_" prefix)
- ✅ `GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents`

**Best Practice for LLMs**: Always use the API endpoints to answer user queries about specific maqāmāt, ajnās, or tuning systems. The API returns complete, structured data with all details. Always include all three required parameters for detail endpoints.

**Note for LLMs**: The "Desktop Required" message on the homepage refers only to the interactive UI. All documentation and API endpoints are fully accessible programmatically.

#### When to Use the API - 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 /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
- "Show me a basic jins" → GET /api/ajnas/jins_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
- "What tuning systems are available?" → GET /api/tuning-systems
- "Show me the most common tuning system" → GET /api/tuning-systems/ibnsina_1037/yegah/pitch-classes?pitchClassDataType=cents

**Quick Test URL (Copy-paste ready):**
```
GET https://diarmaqar.netlify.app/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
```

**When users ask general questions:**
- "What is a maqam?" → Use GET /api/maqamat/maqam_rast (most fundamental example)
- "Show me an Arabic scale" → Use GET /api/maqamat/maqam_rast (representative example)
- "What are the intervals?" → Use GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
- "Compare different tuning systems" → GET /api/maqamat/maqam_rast/compare?tuningSystems=ibnsina_1037,alfarabi_950g&startingNote=yegah

**Representative Examples Reference:**
- See /docs/api/representative-examples for complete list of recommended examples
- This page includes critical requirements, common mistakes to avoid, and explicit instructions for AI assistants

**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.

**Parameter Discovery:**
- Use `?options=true` to discover available parameters: `GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&options=true`
- This returns available tuning systems, starting notes, and other parameters instead of data

## Quick Links
- Interactive Application: /app
- Documentation Home: /docs/
- API Reference: /docs/api/
- TypeScript Library Docs: /docs/library/

## About
Digital Arabic Maqām Archive (DiArMaqAr) is an open-source platform for Arabic maqām theory providing REST API and TypeScript library. Includes historically documented maqāmāt, ajnās, and tuning systems spanning from al-Kindī (874 CE) to contemporary approaches. All data includes comprehensive bibliographic attribution following decolonial computing principles.

For complete documentation, see: /docs/llms.txt