[codex] Clarify recitation and chapter-reciter IDs in v4 docs

[basit3407]

What changed

• clarified in openAPI/content/v4.json that ayah-by-ayah recitation_id values come from /resources/recitations
• clarified that chapter-reciter reciter_id values come from /resources/chapter_reciters
• updated the affected generated v4 docs so each consumer endpoint points to the correct source ID family
• made the verse audio query param wording explicit that chapter-reciter IDs are not supported there
• aligned the audio/reciters/{reciter_id}/timestamp and /lookup docs with the same chapter-reciter ID guidance

Why

External consumers could reasonably assume the two ID families were interchangeable. That led to valid chapter-reciter IDs being passed into ayah-recitation endpoints and returning Recitation not found.

Impact

• public v4 docs now make the distinction explicit on both the producer endpoints and the consumer endpoints
• this is a docs-only change; no API behavior, routes, or schemas changed

Validation

• yarn build in C:\Code\qf-api-docs
• git diff --check

[cloudflare-workers-and-pages]

Deploying qf-api-docs with    Cloudflare Pages

Latest commit:	4a38dfc
Status:	✅  Deploy successful!
Preview URL:	https://5186f925.qf-api-docs.pages.dev
Branch Preview URL:	https://codex-clarify-recitation-and.qf-api-docs.pages.dev

View logs

[Copilot]

Pull request overview

This PR clarifies the distinction between ayah-by-ayah recitation_id and chapter-reciter reciter_id throughout the v4 OpenAPI spec and generated docs, so API consumers use the correct ID family for each endpoint (reducing “Recitation not found” confusion).

Changes:

• Updated v4 OpenAPI descriptions to explicitly state which endpoints accept ayah-by-ayah recitation IDs vs chapter-reciter IDs (including verse audio query params and /audio/reciters/... endpoints).
• Regenerated/updated the affected MDX API docs so the same guidance appears consistently in the published documentation.
• Added explicit “not interchangeable / not supported” wording where consumers are likely to mix the ID families.

Reviewed changes

Copilot reviewed 16 out of 57 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
openAPI/content/v4.json	Source-of-truth OpenAPI text updated to clarify ID-family usage across endpoints/params.
docs/content_apis_versioned/recitations.api.mdx	Recitations “producer” doc now explicitly defines ayah-by-ayah recitation IDs and where they’re valid.
docs/content_apis_versioned/audio-reciter-timestamp.api.mdx	Docs for /audio/reciters/{reciter_id}/timestamp updated with chapter-reciter ID guidance (but has encoding artifacts to fix).
docs/content_apis_versioned/audio-reciter-lookup.api.mdx	Docs for /audio/reciters/{reciter_id}/lookup updated with chapter-reciter ID guidance (but has encoding artifacts to fix).
docs/content_apis_versioned/4.0.0/audio-reciter-timestamp.api.mdx	Versioned copy of timestamp doc updated (but has encoding artifacts to fix).
docs/content_apis_versioned/4.0.0/audio-reciter-lookup.api.mdx	Versioned copy of lookup doc updated (but has encoding artifacts to fix).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.