Forem API V1

Update a recommended articles list Update an existing recommended articles list by ID. Requires Admin credentials.

Update a survey Update an existing survey, including its polls and options. Requires Administrator privileges.

Invite a User Invite a new user to join the platform by email. ### Super Admin Action: - Requires Super Admin privileges. - Triggers a system invitation flow and sends an invitation email containing a sign-up link. - Handy for invite-only platforms or private enterprise instances.

Create a concept (Admin) Create a new Concept. ### Parameters: - **name**: Human readable label for the concept. - **description**: Detailed semantic definition used to generate the anchor embedding. - **similarity_threshold**: Target similarity threshold for categorizing articles under this concept. - **parent_id**: ID of parent concept, if establishing a hierarchy.

Trigger concept lookback backfill (Admin) Trigger a background backfill worker to scan historical articles published in the last `N` days and evaluate them against this concept.

Create a request redirect (Admin) Create a new request redirect route. Requires Administrator privileges. ### Body Parameter Guidelines: - **original_url**: The source path (e.g. `/old-page`) to intercept. - **destination_url**: The target destination (e.g. `https://myforem.com/new-page`) to redirect users to. - **request_domain**: The domain scope (e.g. `dev.to`) where this redirect rule applies.

Merge user into another (Admin) Merge a duplicate user account into a target main account. ### Account Merging Behavior: - Transfers all comments, articles, reactions, and follows to the target user (`merge_user_id`). - Deletes/destroys the source user account in the background once its content has been transferred, so it may still exist briefly after this request returns. - High risk! Action is permanent and irreversible. - Requires Super Admin credentials.

Bulk link identities (Admin) Bulk link OAuth identities across multiple users. Requires Super Admin credentials.

Link an identity to a user (Admin) Manually link an OAuth provider identity to a user. Requires Super Admin credentials. ### Identity Binding: - **provider**: The login provider name (e.g. `github`, `twitter`). - **uid**: The provider's unique user identifier. - **username**: The user's username on the provider's service.

Add a note to a user (Admin) Add a new moderation/audit note to a user. ### Audit Logging Guidelines: - **content**: Plaintext description of behavior, infraction, or actions taken. - **reason**: Categorized classification (e.g. `spam`, `abuse`, `harassment`, `administrative`). - Requires Super Admin credentials.

Create a badge achievement Award a badge to a user. Requires administrator privileges. ### Integration Tips: - **user_id**: The numeric ID of the user receiving the badge. - **badge_id**: The numeric ID of the badge being awarded. - **rewarding_context_message_markdown**: Optional personalized message shown in the notification or profile feed to explain why the user was awarded the badge. - **metadata**: Optional key/value data stored with the achievement for context. - If the badge cannot be awarded more than once and the user already holds it, the request is rejected with `409 Conflict`, and the conflicting `achievement_id` is included in the response. A `422` is returned for other request errors.

Create a badge Create a new badge. Requires administrator privileges. ### Body Parameter Guidelines: - **title**: Unique name for the badge. - **description**: Text explanation of the achievement. - **remote_badge_image_url**: Public URL to an image asset (PNG, GIF, or SVG) representing the badge icon. - **allow_multiple_awards**: Set to `true` if a user can earn the same badge multiple times (e.g. weekly challenges).

Create a billboard Create a new billboard. ### Parameter Options & Tips: - **body_markdown**: The HTML/Markdown advertisement copy. - **placement_area**: Target region in layouts (e.g. `post_comments` below comments, `sidebar` in sidebars, `home_feed` between posts). - **display_to**: Cohort target rules (e.g. `all` for everyone, `logged_in`, `guests`, or customized segments). - **target_geolocations**: Comma-separated ISO codes for country/region targeting. - **approved** & **published**: Set to `true` to activate billboard rotation instantly.

Follow users or organizations in bulk on behalf of the authenticated user. ### Bulk Update Behavior: - Accepts arrays of `user_ids` and `organization_ids` in the request body. - Performs follow actions for all provided identifiers. - Highly efficient for onboarding flows or importing social connections.

pages Create a new custom page. Requires administrative privileges. ### Body Parameter Guidelines: - **title**: Heading displayed at the top of the page. - **slug**: URL path identifier. Must be unique and URL-safe. - **body_markdown**: Content written in Markdown format. - **body_json**: Optional JSON payload for API-consumed/structured data pages. - **is_top_level_path**: Set to `true` to serve the page directly at the root (e.g. `/{slug}`) instead of under the default namespace `/page/{slug}`. Use with caution to avoid namespace collisions with core Forem paths. - **template**: Layout styling options (`contained` or custom layouts).

create reaction Create a reaction on a target resource (Article, Comment, or User) on behalf of the authenticated user. ### Usage Details: - Unlike the toggle endpoint, this endpoint is idempotent: multiple requests to react with the same category to the same target will return the existing reaction without deleting it.

toggle reaction Toggle a reaction on a target resource (Article, Comment, or User) on behalf of the authenticated user. ### Toggle Logic: - **First Request**: Creates a new reaction of the specified category on the reactable target. - **Second Request (with same parameters)**: Deletes the existing reaction. - Particularly useful for simple, interactive UI buttons like "Like", "Unicorn", or "Save" where clicking toggles the active state.

Create or update a recommended articles list Create a new recommended articles list or update an existing one. Requires Administrator privileges. ### Body Parameter Guidelines: - **name**: Curated list title or label (e.g. "Editor's Choice"). - **placement_area**: Target UI layout region (e.g. `main_feed`, `sidebar_top`, `onboarding`). - **expires_at**: ISO 8601 timestamp after which the list recommendation automatically expires. - **user_id**: Owner/curator numeric user ID. - **article_ids**: Staged array of numeric article IDs to include in the recommendation sequence.

Create a survey Create a new survey with optional nested polls and poll options. Requires Administrator privileges.

request a presigned URL to upload raw session transcript to S3 Generate an S3 presigned PUT URL and object key for uploading raw session transcripts directly to S3.

Update user email (Admin) Update a user's primary registration email address. Requires Super Admin credentials.

Update user notification settings (Admin) Update a user's email notification preferences (e.g., unsubscribing them from the system newsletter or the periodic digest). Any subset of the listed properties may be supplied; at least one is required. Requires Super Admin credentials.

Update user moderation status (Admin) Manually update a user's moderation status. ### Status Details: - **status**: Allowed target states (e.g. `active`, `suspended`, `banned`). - **note**: Required reason text recorded in the user's moderation log audit history. - Requires Super Admin privileges.

Update a billboard by ID Update an existing billboard's configurations. ### Integration Guidance: - Allows changing placement area, geolocations, target segments, or text copy. - Updating an active billboard takes effect instantly in the layout delivery cache.

Unpublish a billboard Remove a billboard from active rotation by unpublishing it. ### Usage: - Instantly disables display across all pages while keeping the configuration stored in the database for later reactivations or historical reporting.

Update an organization by id This endpoint allows the client to update an existing organization.

update details for a page Update an existing page's details by ID. Requires administrative privileges.

Remove users from a manually managed audience segment Remove users in bulk from the specified manual audience segment. ### Bulk Update Behavior: - Accepts a JSON array of `user_ids` in the request body. - Returns successes (users successfully removed) and failures (users who were not members of the segment).

Search for articles This endpoint allows the client to search for articles. ### Search Guidance: - **q**: The search query term. Matches against article titles, tags, and body content. - **top**: Restricts search results to articles published within the last `N` days. - **page** & **per_page**: Standard pagination support. Use this to display results sequentially on a search results page.

Search for users Search for a user by email address. ### Permissions & Context: - Requires administrative privileges (`api-key` of an administrator). - Used to verify account existence or map email addresses to platform usernames.

Add spam role for a User Flag a user as spammer. ### Spam Role Details: - Requires `admin` or `moderator` privileges. - Stops the user from creating new posts or comments, acting as a shadowban or block on activity. - Existing content remains but is hidden from search/feeds.

Suspend a User Suspend a user's account. ### Suspension Details: - The user associated with the API key must have an `admin` or `moderator` role. - Assigns the `suspended` role to the user, preventing them from posting new content (articles or comments) while suspended. - Existing content is not deleted. - Suspended users are not notified in the UI; if you want them to know, you must notify them explicitly.

Add trusted role for a User Assign the trusted role to a user. ### Trusted Role Details: - Requires `admin` or `moderator` privileges. - Trusted users gain privileges like casting flag votes on inappropriate content or participating in priority review queues. - Triggers a system notification and an email to the user.

Remove limited for a User Remove the limited role, restoring the user to general privileges. Requires `admin` or `moderator` role.

Remove spam role from a User Unflag a user as spammer, restoring general permissions. Requires `admin` or `moderator` role.

Remove trusted role from a User Revoke the trusted role, returning the user to general status. Requires `admin` or `moderator` role.

Unpublish an article This endpoint allows the client to unpublish an article. The user associated with the API key must have any 'admin' or 'moderator' role. The article will be unpublished and will no longer be visible to the public. It will remain in the database and will set back to draft status on the author's posts dashboard. Any notifications associated with the article will be deleted. Any comments on the article will remain.

Unpublish a User's Articles and Comments This endpoint allows the client to unpublish all of the articles and comments created by a user. ### Administrative Action: - Requires the authenticated user to be an Administrator. - This is a destructive administrative action that immediately unpublishes all posts/comments from public feeds. - Ideal for handling spam accounts or cleanup operations.

Update an article by id This endpoint allows the client to update an existing article by its unique numerical `id`. ### Authorization Constraints: - The API key provided must belong to the author of the article. - Supports updating individual fields such as `title`, `body_markdown`, `published`, `tags`, `ai_disclosure_level`, etc. - Setting `published: false` on an already published article will revert it to draft status.

Update an event Update an existing event. Requires administrator privileges.

upload an image Upload an image and get back a URL hosted by this Forem. ### Using the URL: - Embed it in an article's `body_markdown`, e.g. ``. - Set it as an article's cover image by passing it as `main_image` when creating or updating an article. ### Limits: - One image per request, sent as `multipart/form-data` in the `image` field. - Allowed types: jpg, jpeg, jpe, gif, png, ico, bmp, dng, webp. Max 25MB. - Rate limited per user to a configurable number of uploads per configurable window (by default 10 per hour). Exceeding it returns `429` with a `Retry-After` header. Forem admins can change both values, or set the limit to 0 to disable this endpoint.

Articles with a video Retrieve a list of articles that contain uploaded videos. ### Videos Overview: - Bypasses authentication (can be accessed publicly). - Returns articles that are published and include a video asset. - Articles are ordered by descending popularity (views, watch time, and reactions). - By default, returns 24 video articles per page.