Forem API V1

A User This endpoint allows the client to retrieve a single user, either by id or by the user's username. ### Path Parameter Options: - **id**: Can be either the user's unique numerical ID (e.g. `123`) OR the user's string username (e.g. `ben`). - Note that the returned user object schema (`ExtendedUser`) includes extended profile statistics and social link details.

User's all articles This endpoint allows the client to retrieve a list of all articles on behalf of an authenticated user. "Articles" are all the posts that users create on DEV that typically show up in the feed. They can be a blog post, a discussion question, a help thread etc. but is referred to as article within the code. It will return both published and unpublished articles with pagination. Unpublished articles will be at the top of the list in reverse chronological creation order. Published articles will follow in reverse chronological publication order. By default a page will contain 30 articles.

User's articles This endpoint allows the client to retrieve a list of published articles on behalf of an authenticated user. "Articles" are all the posts that users create on DEV that typically show up in the feed. They can be a blog post, a discussion question, a help thread etc. but is referred to as article within the code. Published articles will be in reverse chronological publication order. It will return published articles with pagination. By default a page will contain 30 articles.

The authenticated user Returned only for delegated Bearer tokens, on any Bearer-capable endpoint, when the configured JWKS endpoint cannot be reached or returns an unusable key set and no cached keys remain. Invalid tokens are 401, never 503.

User's published articles This endpoint allows the client to retrieve a list of published articles on behalf of an authenticated user. "Articles" are all the posts that users create on DEV that typically show up in the feed. They can be a blog post, a discussion question, a help thread etc. but is referred to as article within the code. Published articles will be in reverse chronological publication order. It will return published articles with pagination. By default a page will contain 30 articles.

User's unpublished articles This endpoint allows the client to retrieve a list of unpublished articles on behalf of an authenticated user. "Articles" are all the posts that users create on DEV that typically show up in the feed. They can be a blog post, a discussion question, a help thread etc. but is referred to as article within the code. Unpublished articles will be in reverse chronological creation order. It will return unpublished articles with pagination. By default a page will contain 30 articles.

Users in a manually managed audience segment Retrieve a paginated list of users enrolled in the specified manual audience segment. ### Pagination Guidance: - Supports standard `page` and `per_page` controls, returning 30 users per page by default.

Retrieve all concepts (Admin) Retrieve all concepts in the system including system and draft concepts. Admin credentials required.

Retrieve concept detail (Admin) Retrieve full details of a specific concept by ID. Admin credentials required.

Retrieve all request redirects (Admin) Retrieve a list of all request redirects configured on the platform. ### Redirects Overview: - Redirects map incoming HTTP request paths or domains to specific target destination URLs (301 or 302 redirects). - Primarily used for managing vanity URLs, legacy path support, or domain migrations. - Requires Administrator privileges.

Retrieve a request redirect's details (Admin) Retrieve details of a single request redirect route by ID. Requires Admin credentials.

List all users (Admin) Retrieve a list of all users registered on the platform. ### Permissions & Filters: - Requires Super Admin privileges. - Allows filtering by exact `email` or `username`. - Returns paginated list of extended user objects containing email addresses, registration dates, roles, and administrative statuses.

Get user detail (Admin) Retrieve details of a single user by numerical ID. ### Super Admin Action: - Requires Super Admin privileges. - Includes administrative settings, audit notes, email newsletter preferences, and OAuth login identity states.

List identities for a user (Admin) Retrieve all linked OAuth identities (e.g., GitHub, Twitter, Apple) for a user. Requires Super Admin credentials.

List notes for a user (Admin) Retrieve all moderator/administrator audit log notes appended to a user. Requires Super Admin credentials.

Retrieve dashboard analytics bundle Retrieve a complete bundled metrics package (totals, history, top posts) for rendering dashboard landing pages.

Retrieve follower engagement analytics Retrieve stats detailing new follower growth and engagement over time.

Retrieve heatmap activity Retrieve user activity heatmap metrics (commits, posts, reactions) grouped by weekdays and hours.

Retrieve historical analytics data graphed over a time range. ### Time Range Formats: - **start**: Start date (e.g. `2024-01-01`). Required. - **end**: End date (e.g. `2024-01-31`). Defaults to current date if omitted.

Retrieve analytics for the past day Retrieve real-time hourly analytics statistics for the last 24 hours. Used for live graphs.

Retrieve referrer analytics Retrieve traffic referring domains and URL source tracking metrics for articles.

Retrieve top contributors analytics Retrieve top organization contributors ordered by article engagement scores.

Retrieve analytics totals Retrieve aggregated lifetime stats (views, reactions, comments) for articles. ### Scope Control: - Specify `article_id` to query a single post's metrics. - Specify `organization_id` to retrieve metrics across all articles owned by the target organization.

Perform a semantic fuzzy search on articles Allows authenticated clients to search articles using Forem's hybrid lexical (Algolia/database) and semantic embeddings search pipeline, with optional Jev shortlist re-ranking.

Retrieve all badge achievements Retrieve a list of all badge achievements (awarded badges) in the system. Requires administrator privileges.

Retrieve a badge achievement's details Retrieve details of a specific badge award/achievement by ID.

Retrieve all badges Retrieve a list of all badges available on the platform. ### Badges Overview: - Badges recognize achievements (e.g., "Top Writer", "Beloved Community Member", or anniversary milestones). - Publicly visible on user profiles.

Retrieve a badge's details Retrieve details of a single badge by unique numeric ID.

Billboards Retrieve a list of all billboards configured in the system. ### Billboards Overview: - Billboards are custom promotional ads, notification banners, or call-to-actions shown on the Forem website. - Requires administrative privileges. - Returned objects include layout code, scheduling parameters, geo-targeting configurations, and custom target audience segment associations.

A billboard (by id) Retrieve full configurations of a single billboard by ID. Requires admin credentials.

Retrieve all accessible concepts in the system. ### Concepts Overview: - Concepts are semantic tags generated automatically by analyzing article text using ML embeddings (`gemini-embedding-2`), rather than explicit user tags. - Primarily used for advanced semantic categorization, automated feeds, and interest mapping.

Retrieve details of a concept Retrieve details, settings, and popularity metrics of a single concept by ID. ### Integration Tip: - Includes the semantic description, similarity thresholds, parent concept mappings, and scores.

Retrieve articles mapped to a concept Retrieve articles classified under this concept. ### Parameter Guidelines: - **sort**: Set to `score` to sort articles by article popularity score descending. If omitted or set to any other value, sorting defaults to cosine similarity (closest first) secondary sorted by article score.

Perform a semantic fuzzy search on concepts Allows authenticated clients to search concepts using Forem's semantic embeddings database.

Check app health Basic application liveness check. ### Usage Guidance: - Verifies that the Rails application process is running and responding to requests. - Does not check database or cache connectivity. - Typically used by load balancers, container orchestrators (like Kubernetes), or uptime checkers to verify container health.

Check cache connection Cache connection health check. ### Usage Guidance: - Verifies that the application can successfully ping the Redis cache instance. - Used to monitor cache and background worker queue connection health.

Check database connection Database connection health check. ### Usage Guidance: - Verifies that the application can successfully query the primary PostgreSQL database. - Used to monitor database pool status and connection health.

Retrieve instance configuration details Retrieve configuration details for the current Forem instance. ### Instance Metadata: - Bypasses authentication. - Returns public Forem version, branding parameters, community guidelines references, and supported features configurations.

show details for all pages Retrieve details for all Page objects in the system. ### Pages Overview: - Pages are custom static or dynamic views hosted on the Forem instance. - Publicly visible unless restricted. - Helpful for building custom menus, rendering site policies, or embedding custom forms.

show details for a page Retrieve details for a single Page object specified by ID.

Retrieve all recommended articles lists Retrieve a list of all recommended articles lists configured in the system. ### Overview: - Recommended Articles Lists are curated selections of articles pinned or recommended in layout regions (e.g. `main_feed` or `sidebar`). - Supports search by list name and standard query pagination. - Requires Administrator privileges.

Retrieve details of a recommended articles list Retrieve full details and nested article lists for a specific recommended articles list by ID. Requires Admin credentials.

Retrieve all discoverable subforems Retrieve a list of all discoverable subforems/communities. ### Subforems Overview: - Subforems represent distinct sub-communities or specialized sections hosted within the Forem instance. - Bypasses authentication (can be accessed publicly). - Returns list of names, slugs, color schemes, and target interests.

Add limited role for a User Limit a user's account permissions. ### Limited Details: - Requires `admin` or `moderator` privileges. - Assigns the `limited` role, which rate-limits notifications generated by their actions (such as publishing new posts or comments). - Does not restrict content creation or delete content.

Update a concept (Admin) Update concept properties. Admin credentials required.

Update a request redirect (Admin) Update details (paths or domain scope) of an existing redirect route by ID. Requires Admin credentials.

Update user profile (Admin) Update a user's public profile fields (name, location, bio summary, website) on their behalf. Requires Super Admin credentials.

Update a badge Update badge details (title, description, credits awarded, etc.) by unique ID. Requires administrator privileges.

Update a concept's metadata Update concept metadata such as description, similarity threshold, and custom score. ### Parameter Guidelines: - **similarity_threshold**: Cosine distance threshold (range 0.0 to 1.0) determining how closely an article's embedding must align with the concept's anchor embedding to be classified under it.

Update a feedback message's status (Admin) Update the status of a user feedback message or report. ### Feedback Messages Overview: - Feedback messages are submitted by users via support forms or content abuse reporting modals. - Requires Administrator privileges. - Used to track moderation/resolution workflows (e.g. marking a spam report as `Resolved`, `Spam`, or `Ignored`).