canonical: https://jentic.com/apis/discourse.org/discourse # Discourse API Documentation Discourse is the open-source forum software behind tens of thousands of communities, support sites, and product hubs. The hosted discourse.org API exposes 93 operations covering topics, posts, categories, users, groups, badges, tags, search, private messages, the discourse-post-event plugin, and admin features such as backups and site settings. It is the same surface used internally by the Discourse mobile app and core integrations. ## For AI agents Create topics, post replies, manage users and groups, and run admin operations on a Discourse forum. Useful for community-management, support, and event-coordination agents. ## Scope Does not handle real-time WebSocket events or transactional email delivery - use for hosted Discourse forum REST operations only. ## Capabilities - Create and reply to forum topics with Markdown via /posts.json and /t/{id}.json - Search topics, posts, and users via /search/query.json with category, tag, and user filters - Manage groups, group memberships, and category access through /groups and /admin/groups - Schedule and list community events via the /discourse-post-event/events.json endpoints - Administer categories, badges, tags, and site backups through admin-prefixed endpoints - Manage user accounts and notifications through /users endpoints ## Use cases ### Customer Community and Support Forum Automation Product teams running a Discourse community can automate the lifecycle of support topics - creating posts from inbound support tickets, tagging them, and notifying owners through group mentions. The /posts.json and /t/{id}.json endpoints handle topic creation and replies, while /search/query.json finds duplicate threads. This keeps the public knowledge base growing without manual triage. Example prompt: POST /posts.json to create a new support topic with title, raw Markdown body, and category ID, then attach product-area tags via /t/{id}.json. ### Community Events with Discourse Post Event Plugin Communities using the discourse-post-event plugin can list, create, and export community events directly via the /discourse-post-event/events.json and /discourse-post-event/events.ics endpoints. Calendars can be embedded into external sites or pulled into personal calendars, giving members a single source of truth for meetups, AMAs, and office hours. Example prompt: GET /discourse-post-event/events.json filtered to upcoming events for the 'meetups' category and render the response as a calendar widget. ### Group Sync from External Identity Systems Hosted Discourse customers can keep group membership in sync with HR systems, CRMs, or partner directories. PUT /groups/{id}/members and DELETE /groups/{id}/members add and remove users while /groups/{id}.json fetches state. This is commonly used to grant access to private categories based on subscription tier or role in another system. Example prompt: Add user 'jane.doe' to the 'paid-customers' group via PUT /groups/{id}/members and confirm membership with GET /groups/{id}/members. ### Forum Backups and Admin Automation Hosted and self-hosted Discourse operators can automate routine admin work - triggering nightly backups via /admin/backups.json, downloading the latest backup file, and rotating retention. Category, badge, and group management can also be scripted from CI for reproducible community governance, especially when promoting changes from staging to production. Example prompt: POST /admin/backups.json to trigger a fresh backup and poll until the file is available, then download via the returned filename. ### AI Agent Community Assistant AI agents can act as Discourse community helpers - answering recurring questions, posting daily summaries, and tagging stale topics - by calling the Discourse API through Jentic. The API-Key and API-Username headers stay in your Jentic One instance and never appear in the agent's context, while Jentic search lets the agent find the right topic or post operation by intent. Example prompt: Search Jentic for 'reply to a Discourse topic', load the POST /posts.json operation, and execute it to post a daily community digest summary into the announcements category. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /posts.json | Create a new topic or reply to an existing topic | | GET | /categories.json | List forum categories | | GET | /discourse-post-event/events.json | List community events | | GET | /discourse-post-event/events.ics | Export community events as iCal | | PUT | /groups/{id}/members | Add members to a group | | POST | /admin/backups.json | Trigger a forum backup | | POST | /admin/badges.json | Create a new badge | ## Key resources - **Topics & Posts** — Create, fetch, update, and delete forum topics and individual posts - **Categories** — Manage forum categories, sub-categories, and category settings - **Users** — Look up users, manage user fields, and handle account actions - **Groups** — Create groups, manage memberships, and configure group permissions - **Badges** — Define and grant achievement badges - **Search** — Query topics, posts, and users by keyword and filter - **Discourse Post Event** — List, create, and export community events as JSON or iCal - **Admin** — Backups, site settings, badge admin, and moderation actions ## Why Jentic - **Setup:** Wiring a hosted Discourse forum by hand means carrying its API key and username in paired request headers and threading them through every REST call yourself. Through Jentic you install once, import the Discourse API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** Discourse admin keys grant broad forum access, so scope your agent to the operations it needs, such as creating a post or listing community events. You choose the operations it may call, so admin operations like creating backups or badges are not included unless you add them. - **Credential handling:** Your Discourse API key and username are stored once, encrypted, by your own Jentic One instance and injected as the paired request headers at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a forum topic' or 'list community events', and Jentic returns the matching Discourse operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Discourse (self-hosted)** — Self-hosted Discourse on a custom or local domain - **Mattermost** — Self-hosted real-time team messaging - **Zendesk** — Customer support ticketing platform ## FAQ ### What authentication does the Discourse API use? Discourse uses two headers: API-Key (an admin or user-scoped key) and API-Username (the username the request acts on behalf of). Through Jentic, both values are held in your Jentic One instance and injected at execution; agents never see the raw key. ### Can I list community events with the Discourse API? Yes, when the discourse-post-event plugin is enabled. /discourse-post-event/events.json returns events as JSON and /discourse-post-event/events.ics returns the same set as an iCalendar feed for embedding in personal or external calendars. ### What are the rate limits for the Discourse API? Discourse enforces per-action rate limits configured by site settings such as max_requests_per_minute, max_post_creates_per_minute, and per-IP limits. Hosted plans publish defaults per tier. Inspect site settings or contact your Discourse hosting provider for the exact values applied to your forum. ### How do I create a topic on Discourse through Jentic? Search Jentic for 'create a topic on Discourse', load the POST /posts.json operation, and execute it with title, raw Markdown content, category ID, and any tags. Jentic returns the new topic's ID and slug for follow-up operations. ### Can I export forum data with the Discourse API? Yes, /admin/backups.json triggers a full forum backup, and /admin/backups/{filename} downloads a specific backup. Combined with category, topic, and user listing endpoints, you can also build incremental exports without invoking the full backup process. ### Can I limit what my agent is allowed to do with the Discourse API? Yes. Because your Jentic One instance is self-hosted, you decide which Discourse operations the agent can call and which stored API key and username it uses. You can allow only the operations it needs, such as creating a post via POST /posts.json or listing events via /discourse-post-event/events.json, while leaving broad admin operations like triggering backups through /admin/backups.json or creating badges via /admin/badges.json out of scope. Since a Discourse admin key grants wide forum access, this lets you narrow the agent to exactly the actions you approve.