OpenAPI v1.json lists /auth for all endpoints, but users/posts/rooms/tags/comments use /quran-reflect #71
Description
Summary
The global OpenAPI spec at openAPI/user-related-apis/v1.json defines only these top-level servers:
"servers": [
{ "url": "https://apis-prelive.quran.foundation/auth" },
{ "url": "https://apis.quran.foundation/auth" }
]No individual path/operation overrides the servers, so every endpoint in the spec appears to be under /auth. However, the per-endpoint MDX docs (and live testing) show that multiple endpoint categories actually use /quran-reflect as the base path.
Affected Endpoints
The per-endpoint MDX files correctly document quran-reflect as the server for these categories, but the aggregated v1.json incorrectly places them under /auth:
| Category | Server (per MDX docs) | Server (v1.json) | Example MDX |
|---|---|---|---|
Users (UsersController) |
/quran-reflect |
/auth |
users-controller-profile.api.mdx |
Posts (PostsController) |
/quran-reflect |
/auth |
posts-controller-feed.api.mdx |
Rooms (RoomsController) |
/quran-reflect |
/auth |
rooms-controller-create-new-group.api.mdx |
Tags (TagsController) |
/quran-reflect |
/auth |
tags-controller-find.api.mdx |
Comments (CommentsController) |
/quran-reflect |
/auth |
comments-controller-create.api.mdx |
The following categories correctly use /auth in both v1.json and MDX docs:
- Bookmarks, Notes, Collections, Reading Sessions, Preferences, Streaks, Goals, Activity Days
Reproduction
# v1.json says /auth for everything:
curl -s https://api-docs.quran.foundation/openAPI/user-related-apis/v1.json | jq '.servers'
# But per-endpoint MDX says /quran-reflect for users:
# (reading the YAML frontmatter in users-controller-profile.api.mdx)Live Verification
# Confirmed working (quran-reflect):
curl -s https://apis-prelive.quran.foundation/quran-reflect/v1/users/profile \
-H "x-auth-token: <token>" -H "x-client-id: <client_id>"
# → 200 OK
# Would fail with /auth:
curl -s https://apis-prelive.quran.foundation/auth/v1/users/profile \
-H "x-auth-token: <token>" -H "x-client-id: <client_id>"
# → 404 or routing errorSuggested Fix
Add per-path servers overrides in v1.json for the affected endpoint categories, or split the spec into two server groups:
/quran-reflect/v1: users, posts, rooms, tags, comments/auth/v1: bookmarks, notes, collections, reading_sessions, preferences, streaks, goals, activity_days
Impact
API consumers using the OpenAPI spec programmatically (code generation, AI tool calling via llms.txt → v1.json) will construct incorrect base URLs for ~40% of endpoints.
Context
Discovered while integrating the User API for quran-mcp. The llms.txt at api-docs.quran.foundation/llms.txt references v1.json, making this the primary machine-readable entry point for AI integrations.