# Improving Discourse API documentation for building fully custom frontend community

**URL:** https://meta.discourse.org/t/improving-discourse-api-documentation-for-building-fully-custom-frontend-community/401236
**Category:** Development
**Tags:** rest-api
**Created:** [April 22, 2026, 11:48am UTC](https://meta.discourse.org/t/improving-discourse-api-documentation-for-building-fully-custom-frontend-community/401236 "2026-04-22T11:48:13Z")
**Posts on this page:** 2
**Page:** 1

<div class="post-metadata">

### Author: ![Mohamed\_Ahmed2](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/mohamed_ahmed2/32/485262_2.png) [@Mohamed\_Ahmed2](https://meta.discourse.org/u/Mohamed_Ahmed2)
#### Post date: [April 22, 2026, 11:48am UTC](https://meta.discourse.org/t/improving-discourse-api-documentation-for-building-fully-custom-frontend-community/401236/1 "2026-04-22T11:48:13Z")

</div>

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:

- This makes it harder to build clean infinite scroll / normalized state (Redux/Zustand/React Query)

Suggestion:

- Provide clearer separation or optional query flags like:

* * *

## 2. Replies vs Topic Structure

Right now:

- Replies are embedded inside topic response

- No clear separation between:

This causes:

- extra parsing logic in frontend

- duplication when normalizing state

Suggestion:

- Offer dedicated endpoints like:

* * *

## 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:

Suggestion:

- Add inline schema documentation or OpenAPI-style metadata:

* * *

## 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:

Developers end up doing:

- multiple API calls per category

- manual diffing for `updated_at`

- pagination crawling to detect updates

Suggestion:

- Add dedicated endpoints:

* * *

## 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:

* * *

## 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:

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 🙏

---

<div class="post-metadata">

### Author: ![darkpixlz](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/darkpixlz/32/549896_2.png) [@darkpixlz](https://meta.discourse.org/u/darkpixlz)
#### Post date: [April 22, 2026, 1:15pm UTC](https://meta.discourse.org/t/improving-discourse-api-documentation-for-building-fully-custom-frontend-community/401236/2 "2026-04-22T13:15:05Z")

</div>

Something else I noticed that annoys me is some endpoints are “protected” using formencoding instead of JSON maybe to deter people from messing with the API? The best example of this is the link click track API, which I guess makes sense as protection but anybody can still misuse it if they _really_ want so at the end of the day it’s just more difficult for developers to do stuff with.