Hi everyone I’ve been building a custom frontend using Discourse as a headless backend (Next.js-based architecture), and I’d like to share some practical gaps I’ve encountered in the current API design from a real-world integration perspective. This is not a critique of Discourse itself (it’s powerful and flexible), but rather feedback to improve DX for modern frontend + API-driven architectures.. 1. Pagination & Topic Posts Structure Current issue: Pagination is not always consistent across endpoints Topic posts ( /t/{id}.json ) mixes: original post replies internal metadata This makes it harder to build clean infinite scroll / normalized state (Redux/Zustand/React Query) Suggestion: Provide clearer separation or optional query flags like: ?include_first_post=true|false ?posts_only=replies Cursor-based pagination support (instead of page-based only) 2. Replies vs Topic Structure Right now: Replies are embedded inside topic response No clear separation between: “topic metadata” “post stream” This causes: extra parsing logic in frontend duplication when normalizing state Suggestion: Offer dedicated endpoints like: /t/{id}/posts /t/{id}/replies or support filtering inside /t/{id}.json 3. Lack of Field-Level Documentation in API Response For example in topic response: created_at bumped_at last_posted_at updated_at These are not always clearly differentiated. Problem: Developers often misinterpret: bumped_at vs updated_at what triggers “topic activity” Suggestion: Add inline schema documentation or OpenAPI-style metadata: meaning of each field lifecycle explanation 4. Statistics & Caching Inconsistencies Issues: posts_count , reply_count , participants_count sometimes lag behind real-time data heavy reliance on cached counters Impact: inaccurate UI (especially for dashboards / analytics pages) requires extra API calls to validate state Suggestion: Add “real-time vs cached” indicator or endpoint variant Or provide webhook/event-driven updates for counts 5. Sitemap + SEO + Framework Integration Gaps When integrating with modern frameworks (Next.js, Nuxt, etc.): Problems: No unified API for: updated topics for sitemap generation category-level last change tracking full post indexation support Developers end up doing: multiple API calls per category manual diffing for updated_at pagination crawling to detect updates Suggestion: Add dedicated endpoints: /categories/updated /topics/changes?since=timestamp /sitemap.json (API-driven sitemap feed) 6. User Metrics & Aggregations Missing Common needed data: total likes received per user total likes given reaction breakdown per post/user engagement stats per category Current issue: requires multiple endpoints + aggregation on frontend Suggestion: Add aggregated endpoints like: /users/{id}/stats /topics/{id}/stats 7. User Avatars Flexibility Current limitation: avatars are tightly coupled with Discourse upload system Request: allow external avatar URLs (S3 / CDN / external auth providers) support: external_avatar_url This would help with: SSO systems headless identity providers 8. API Keys: Admin vs User Keys Clarification needed in docs: Difference between: admin API key user API key (created via /admin/api/keys or user API endpoints) Questions: lifecycle & expiration rules revocation rules per user vs global security scope limitations per type This is critical when building production-grade integrations. Final Thoughts Discourse API is already powerful, but it feels optimized for “server-rendered forum usage” more than “headless / frontend-driven architecture”. Modern frameworks (Next.js, Remix, etc.) benefit a lot from: fewer round trips clearer data boundaries predictable caching rules better aggregation endpoints Would love feedback from maintainers or others building headless Discourse setups. Thanks