canonical: https://jentic.com/apis/discourse.local/discourse-local # Discourse API Documentation Discourse is an open-source forum platform used by communities, support sites, and product companies. This local-host variant of the Discourse API exposes 89 operations covering categories, topics, posts, users, groups, badges, tags, search, private messages, and admin features such as backups and site settings. It is the same surface used by self-hosted Discourse instances running under custom or local domains. ## For AI agents Create topics, post replies, manage users, groups, and tags on a self-hosted Discourse forum. Useful for community automation, support-bot, and admin agents. ## Scope Does not handle real-time WebSocket events or transactional email delivery - use for self-hosted Discourse forum REST operations only. ## Capabilities - Create and update topics, posts, and private messages via /posts.json and /t/{id}.json - Manage user accounts, groups, and group memberships through /users and /groups endpoints - Run search queries across topics, posts, and users via /search/query.json - Administer categories, badges, tags, and site backups through admin-prefixed endpoints - List notifications, read mailing-list summaries, and manage user preferences for community engagement - Trigger and download forum backups via /admin/backups.json ## Use cases ### Community Support Forums for Product Companies Product teams running a Discourse community can automate the lifecycle of support topics by creating posts from inbound support tickets, tagging them by product area, and notifying owners through group mentions. The /posts.json and /t/{id}.json endpoints handle topic creation and replies, while category-scoped searches surface duplicate threads. This keeps the public knowledge base growing without manual triage overhead. 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. ### Admin Operations and Site Backups 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 across staging and production environments. Example prompt: POST /admin/backups.json to trigger a fresh backup, then poll until the file is available and download it via the returned filename. ### Group Management and Onboarding Community managers and SSO integrations can keep group membership in sync with HR, customer, or partner directories. PUT /groups/{id}/members and DELETE /groups/{id}/members add and remove users, while /groups/{id}.json fetches the current state. This is commonly used to grant access to private categories based on a user's role in another system. Example prompt: Add user 'jane.doe' to the 'paid-customers' group via PUT /groups/{id}/members and confirm membership via GET /groups/{id}/members. ### 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 | /c/{slug}/{id}.json | Get a category's topics by slug and ID | | POST | /admin/groups.json | Create a new group | | 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 - **Admin** — Backups, site settings, badge admin, and moderation actions ## Why Jentic - **Setup:** Wiring a self-hosted Discourse forum by hand means carrying its API key and username in paired request headers and pointing at your own forum host 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 categories. 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 'add a member to a group', 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 (Hosted)** — Hosted Discourse forum operating on the same API surface - **Mattermost** — Self-hosted real-time team messaging - **Zendesk** — Customer support ticketing platform ## FAQ ### What authentication does the Discourse Local 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 create a topic with the Discourse API? Yes, POST /posts.json with title, raw Markdown body, and a category ID creates a new topic. Omitting title and providing topic_id instead posts a reply to the existing topic. Tags can be supplied at creation or applied via /t/{id}.json afterwards. ### What are the rate limits for the Discourse API? Self-hosted Discourse instances configure their own rate limits via site settings (max_requests_per_minute and per-action limits). Hosted Discourse plans publish per-tier defaults. Check site settings on your forum or contact your Discourse hosting provider for exact values. ### How do I run a forum search through Jentic? Search Jentic for 'search Discourse forum', load the schema for /search/query.json, and execute it with your query string and any filters such as category or tag. Jentic returns matching topics, posts, and users in a single response. ### Can I trigger a backup of a Discourse forum? Yes, POST /admin/backups.json starts a backup job on the server. Poll the backups list endpoint to confirm the file is ready, then download it via /admin/backups/{filename}. This requires an admin API-Key with backup permissions. ### Can I limit what my agent is allowed to do with the Discourse API? Yes. Because your Jentic One instance is self-hosted, your own rules decide which Discourse operations and credentials the agent may use. A Discourse admin key grants broad forum access, so you can scope the agent to only the operations it needs, such as creating a post via POST /posts.json or listing categories via GET /categories.json. Broad admin operations like triggering backups through /admin/backups.json or creating badges are not available to the agent unless you explicitly add them.