# Discourse API
> A live window into Discourse's own official community forum (meta.discourse.org), the flagship instance of the most widely used modern forum platform, as an API. Pull the latest topics with their reply, view and like counts; the top topics of a day, week, month or year; the category list with topic counts; or a user's profile (trust level, join date). The traditional threaded-forum experience delivered as clean JSON for social, news-aggregation and community-dashboard apps. Live data, no key. Distinct from link-aggregators and microblogs — this is forum software.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/discourse-api/..."
```

## Pricing
- **Free** (Free) — 500 calls/Mo, 5 req/s
- **Starter** ($8/Mo) — 13,000 calls/Mo, 15 req/s
- **Pro** ($20/Mo) — 62,000 calls/Mo, 30 req/s
- **Business** ($48/Mo) — 310,000 calls/Mo, 50 req/s

## Endpoints

### Topics

#### `GET /v1/latest` — Latest topics

**Parameters:**
- `limit` (query, optional, string) — Max topics (1-100) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/discourse-api/v1/latest?limit=30"
```

**Response:**
```json
{
    "data": {
        "feed": "latest",
        "count": 30,
        "topics": [
            {
                "id": 1,
                "url": "https://meta.discourse.org/t/new-to-discourse-start-here/1",
                "slug": "new-to-discourse-start-here",
                "tags": [],
                "likes": 431,
                "posts": 1,
                "title": "New to Discourse? Start here!",
                "views": 115837,
                "closed": true,
                "pinned": true,
                "replies": 0,
                "created_at": "2013-02-01T04:52:28.073Z",
                "category_id": 67,
                "last_posted_at": "2013-02-01T04:52:28.397Z"
            },
            {
                "id": 404728,
                "url": "https://meta.discourse.org/t/introducing-the-unified-new-view-for-the-topic-list/404728",
                "slug": "introducing-the-unified-new-view-for-the-topic-list",
                "tags": [],
                "likes": 0,
                "posts": 1,
                "title": "Introducing the unified new view for the topic list",
                "views": 1,
                "closed": false,
                "pinned": false,
                "replies": 0,
                "created_at": "2026-06-09T02:56:43.294Z",
                "category_id": 67,
                "last_posted_at": "2026-06-09T02:56:43.294Z"
            },
            {
                "id": 402812,
                "url": "https://meta.discourse.org/t/introdu
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search the forum for topics

**Parameters:**
- `q` (query, required, string) — Search query (min 2 chars) Example: `plugin`
- `limit` (query, optional, string) — Max topics (1-50) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/discourse-api/v1/search?q=plugin&limit=20"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "query": "plugin",
        "topics": [
            {
                "id": 54462,
                "url": "https://meta.discourse.org/t/the-plugin-instance-find-all-method-incorrectly-treats-every-file-with-the-plugin-rb-name-as-a-discourse-plugin/54462",
                "slug": "the-plugin-instance-find-all-method-incorrectly-treats-every-file-with-the-plugin-rb-name-as-a-discourse-plugin",
                "tags": [],
                "likes": null,
                "posts": 6,
                "title": "The Plugin::Instance.find_all method incorrectly treats every file with the «plugin.rb» name as a Discourse plugin",
                "views": null,
                "closed": true,
                "pinned": false,
                "replies": 5,
                "created_at": "2016-12-19T00:21:09.289Z",
                "category_id": 1,
                "last_posted_at": "2017-05-16T21:29:12.681Z"
            },
            {
                "id": 266794,
                "url": "https://meta.discourse.org/t/activitypub-plugin/266794",
                "slug": "activitypub-plugin",
                "tags": [
                    {
                        "id": 803,
                        "name": "activitypub",
                        "slug": "activitypub"
                    },
                    {
                        "id": 731,
                        "name": "experimental",
                        "slug": "experimental"
             
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/top` — Top topics by period

**Parameters:**
- `period` (query, optional, string) — daily, weekly (default), monthly, quarterly, yearly or all Example: `weekly`
- `limit` (query, optional, string) — Max topics (1-100) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/discourse-api/v1/top?period=weekly&limit=30"
```

**Response:**
```json
{
    "data": {
        "feed": "top",
        "count": 30,
        "period": "weekly",
        "topics": [
            {
                "id": 404427,
                "url": "https://meta.discourse.org/t/is-anyone-experiencing-an-odd-spam-user-attack-any-way-to-block/404427",
                "slug": "is-anyone-experiencing-an-odd-spam-user-attack-any-way-to-block",
                "tags": [],
                "likes": 38,
                "posts": 15,
                "title": "Is anyone experiencing an odd spam user attack? Any way to block?",
                "views": 287,
                "closed": false,
                "pinned": false,
                "replies": 14,
                "created_at": "2026-06-03T13:59:07.092Z",
                "category_id": 6,
                "last_posted_at": "2026-06-07T16:36:28.163Z"
            },
            {
                "id": 403635,
                "url": "https://meta.discourse.org/t/introducing-a-new-post-type-composer-actions-dropdown/403635",
                "slug": "introducing-a-new-post-type-composer-actions-dropdown",
                "tags": [],
                "likes": 21,
                "posts": 3,
                "title": "Introducing a new \"Post Type\" Composer actions dropdown",
                "views": 209,
                "closed": false,
                "pinned": false,
                "replies": 2,
                "created_at": "2026-06-01T20:07:07.770Z",
                "category_id": 67,
                "last_pos
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/topic` — One topic with its posts

**Parameters:**
- `id` (query, required, string) — Numeric topic id (from /v1/latest or /v1/top) Example: `1`
- `limit` (query, optional, string) — Max posts (1-50) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/discourse-api/v1/topic?id=1&limit=20"
```

**Response:**
```json
{
    "data": {
        "id": 1,
        "url": "https://meta.discourse.org/t/new-to-discourse-start-here/1",
        "slug": "new-to-discourse-start-here",
        "tags": [],
        "count": 1,
        "likes": 432,
        "posts": [
            {
                "name": null,
                "text": "We’re so glad you’re here! This is our official community, where you can connect, ask questions, and share ideas about Discourse, a powerful platform for support, teamwork, and everything community. You’ll find topics here on features, bugs, hosting, development, and general support. Want to run your own Discourse site? There are a couple of great ways to get started: Official hosting & migration services Fully managed by the team that builds Discourse – ideal for those who want peace of mind and expert support. Use the free, open source code A fast and streamlined option if you prefer to self",
                "likes": 432,
                "username": "Discourse",
                "created_at": "2013-02-01T04:52:28.397Z",
                "post_number": 1
            }
        ],
        "title": "New to Discourse? Start here!",
        "views": 116026,
        "created_at": "2013-02-01T04:52:28.073Z",
        "category_id": 67,
        "posts_count": 1,
        "last_posted_at": "2013-02-01T04:52:28.397Z"
    },
    "meta": {
        "timestamp": "2026-06-13T14:11:26.046Z",
        "request_id": "18c2fced-a723-462d-9655-23332490f716"
    },
    "status": "ok",
    "m
…(truncated, see openapi.json for full schema)
```

### Forum

#### `GET /v1/categories` — All categories with topic counts

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/discourse-api/v1/categories"
```

**Response:**
```json
{
    "data": {
        "count": 11,
        "categories": [
            {
                "id": 6,
                "name": "Support",
                "slug": "support",
                "color": "ce96c9",
                "post_count": 132315,
                "description": "Ask the community for help with anything related to Discourse.To help others help you, share as much detail as you can about the issue and what is occurring, including what you have tried so far from searching, reading the documentation or asking our AI bot.",
                "topic_count": 20304
            },
            {
                "id": 7,
                "name": "Development",
                "slug": "dev",
                "color": "292929",
                "post_count": 25995,
                "description": "The category for all things Discourse Development. Building a customization for yourself or the community? Then this is the category for you! Learn more…",
                "topic_count": 4363
            },
            {
                "id": 14,
                "name": "Marketplace",
                "slug": "marketplace",
                "color": "8c6220",
                "post_count": 6759,
                "description": "A hub for all Discourse-related commerce: jobs, gigs, plugins, themes, hosting, and more.",
                "topic_count": 1326
            },
            {
                "id": 65,
                "name": "Community Building",
                "slug": "community-build
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/user` — A user profile

**Parameters:**
- `username` (query, required, string) — Discourse username Example: `codinghorror`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/discourse-api/v1/user?username=codinghorror"
```

**Response:**
```json
{
    "data": {
        "user": {
            "name": "Jeff Atwood",
            "admin": true,
            "title": "co-founder",
            "avatar": "https://meta.discourse.org/user_avatar/meta.discourse.org/codinghorror/120/110067_2.png",
            "username": "codinghorror",
            "moderator": false,
            "created_at": "2013-02-05T04:44:25.476Z",
            "profile_url": "https://meta.discourse.org/u/codinghorror",
            "trust_level": 2,
            "last_seen_at": "2026-06-08T06:59:49.649Z"
        }
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:23.769Z",
        "request_id": "cfc89d91-b82f-4c7b-b3ff-4ba2b816e9ec"
    },
    "status": "ok",
    "message": "User retrieved successfully",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/discourse-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "source": "meta.discourse.org public JSON (live)",
        "periods": [
            "daily",
            "weekly",
            "monthly",
            "quarterly",
            "yearly",
            "all"
        ],
        "service": "discourse-api",
        "instance": "meta.discourse.org",
        "endpoints": {
            "GET /v1/top": "Top topics by period (period=daily|weekly|monthly|quarterly|yearly|all, limit).",
            "GET /v1/meta": "This document.",
            "GET /v1/user": "User profile (username=, e.g. codinghorror).",
            "GET /v1/latest": "Latest topics (limit).",
            "GET /v1/categories": "All categories with topic counts."
        },
        "categories": 11,
        "description": "Live feed of Discourse's official community forum (meta.discourse.org), flagship of the most-used modern forum platform: latest topics with reply/view/like counts, top topics by period, the category list, and user profiles (trust level, join date). Live, no key. Distinct from link-aggregators and microblogs — this is forum software."
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:24.034Z",
        "request_id": "7c9b8d67-af96-45e5-a2b4-7cda1575fd94"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```

### Members

#### `GET /v1/directory` — The community leaderboard

**Parameters:**
- `period` (query, optional, string) — daily, weekly, monthly, quarterly, yearly or all (default) Example: `all`
- `order` (query, optional, string) — likes_received (default), likes_given, topic_count, post_count, days_visited or posts_read Example: `likes_received`
- `limit` (query, optional, string) — Max users (1-50) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/discourse-api/v1/directory?period=all&order=likes_received&limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 25,
        "order": "likes_received",
        "users": [
            {
                "name": "Sam Saffron",
                "posts": 14908,
                "avatar": "https://meta.discourse.org/user_avatar/meta.discourse.org/sam/120/102149_2.png",
                "topics": 300,
                "username": "sam",
                "likes_given": 24967,
                "profile_url": "https://meta.discourse.org/u/sam",
                "days_visited": 4879,
                "likes_received": 49545
            },
            {
                "name": "Jeff Atwood",
                "posts": 19071,
                "avatar": "https://meta.discourse.org/user_avatar/meta.discourse.org/codinghorror/120/110067_2.png",
                "topics": 226,
                "username": "codinghorror",
                "likes_given": 56014,
                "profile_url": "https://meta.discourse.org/u/codinghorror",
                "days_visited": 3357,
                "likes_received": 44037
            },
            {
                "name": "Jay Pfaffman",
                "posts": 15253,
                "avatar": "https://meta.discourse.org/user_avatar/meta.discourse.org/pfaffman/120/120154_2.png",
                "topics": 595,
                "username": "pfaffman",
                "likes_given": 27741,
                "profile_url": "https://meta.discourse.org/u/pfaffman",
                "days_visited": 3876,
                "likes_received": 27709
          
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/user-summary` — A member's activity stats

**Parameters:**
- `username` (query, required, string) — Discourse username Example: `codinghorror`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/discourse-api/v1/user-summary?username=codinghorror"
```

**Response:**
```json
{
    "data": {
        "posts": 19071,
        "topics": 226,
        "username": "codinghorror",
        "posts_read": 292881,
        "likes_given": 56014,
        "profile_url": "https://meta.discourse.org/u/codinghorror",
        "days_visited": 3357,
        "solved_count": 401,
        "likes_received": 72761,
        "topics_entered": 85503,
        "time_read_seconds": 16808964
    },
    "meta": {
        "timestamp": "2026-06-13T14:11:30.110Z",
        "request_id": "682d4488-0cf6-4e65-bfbe-5d2ecb6b4868"
    },
    "status": "ok",
    "message": "User summary retrieved successfully",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/discourse-api
OpenAPI spec: https://www.oanor.com/api/discourse-api/openapi.json