Forem API V1

Add users to a manually managed audience segment Add users in bulk to the specified manual audience segment. ### Bulk Update Behavior: - Accepts a JSON array of `user_ids` in the request body. - Returns a list of successes and failures. Successful additions include users already present in the segment.

upload a new agent session Upload a new agent session. ### S3 Upload Workflow: 1. Call the S3 presign endpoint to obtain a direct upload URL for the raw session transcript file. 2. Upload the raw transcript to S3. 3. Send a POST request to this endpoint with the S3 key (`s3_key`) and the pre-parsed, curated JSON payload (`curated_data`).

Publish article This endpoint allows the client to create a new article. "Articles" are all the posts that users create on DEV/Forem that typically show up in the feed. They can be a blog post, a discussion question, a help thread etc. but are referred to as articles within the code. ### Body Parameter Tips: - **title**: A compelling and descriptive title for the article. - **body_markdown**: The main text of the article in Markdown format. You can use standard Markdown as well as Forem-specific Liquid tags (e.g., `{% embed ... %}`). You can also include YAML front matter at the very beginning of the markdown to specify metadata such as tags, series, and cover image. - **published**: Set to `true` to immediately publish the article and make it visible in feeds. Set to `false` (default) to save it as a draft. - **tags**: An array of up to 4 tag strings, e.g. `['ruby', 'rails']`. Tags help categorize your post and improve discoverability. - **series**: Group articles together by specifying a series name. If the series does not exist, it will be created. - **main_image**: Absolute URL of the cover image for the article. Use `POST /api/images` to upload an image, or `POST /api/images/generate` to generate one, and get back a URL to use here or in `body_markdown`. - **canonical_url**: If this post was originally published elsewhere, specify the canonical URL to maintain SEO integrity. - **description**: A short summary of the article used for previews and SEO meta description. - **ai_disclosure_level**: AI tooling usage disclosure (`not_disclosed`, `no_ai`, `some_ai`, `fully_autonomous`).

Create an event Create a new event. Requires administrator privileges.

Create an Organization This endpoint allows the client to create an organization with the provided parameters. It requires a token from a user with `admin` privileges.

Create a manually managed audience segment Create a new manually managed audience segment. ### Usage Guidance: - Used by administrators to define a new target cohort group. - Users can be added or removed in bulk later via segment member endpoints.

Delete an event. Requires administrator privileges.

Delete a manually managed audience segment Delete an audience segment specified by ID. ### Constraints: - Audience segments cannot be deleted if they are currently assigned to any active or pending Billboards.

Delete a concept (Admin) Permanently delete a concept by ID. Admin credentials required.

Delete a request redirect (Admin) Delete a request redirect route, disabling the routing intercept immediately. Requires Admin credentials.

Unlink an identity from a user (Admin) Unlink a specific OAuth login provider identity from a user by identity ID. Requires Super Admin credentials.

Delete a badge achievement Revoke a badge award by deleting the badge achievement. Requires administrator privileges.

Delete a badge configuration from the system by ID. Requires administrator privileges.

Delete an Organization by id This endpoint allows the client to delete a single organization, specified by id

remove a page Delete a custom page from the system by ID. Requires administrative privileges.

Delete a survey Delete an existing survey. Requires Administrator privileges.

generate an image with AI Generate an image from a text prompt and get back a URL hosted by this Forem. The image follows this Forem's cover image style and, unless `aspect_ratio` is given, is sized for its cover images. Use the URL in `body_markdown` or as an article's `main_image`, just like an uploaded image. ### Limits: - `prompt` is required and may be up to 1000 characters. - Rate limited per user to a configurable number of generations per configurable window (by default 3 per day). Every attempt counts, including failed ones. 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. - Returns `503` if AI image generation is not configured on this Forem.

show details for an agent session Retrieve details for a single agent session by unique slug or ID. ### Integration Tip: - Returns the complete session structure including parsed message logs, token counts, slices, and tool execution metadata.

request a presigned S3 GET URL to download the raw session transcript Retrieve a temporary presigned GET URL to download the original raw transcript file from S3.

list the authenticated user's agent sessions Retrieve a list of the authenticated user's agent sessions. ### Agent Sessions Overview: - Agent sessions represent coding conversation transcripts uploaded from CLI tools (like Claude Code). - Used by the developer portal to render interactive walkthroughs or session summaries. - Requires authentication.

Published article by id This endpoint allows the client to retrieve a single published article given its unique numerical `id`. ### Integration Tip: - Returns the complete serialized article object including its HTML/markdown representation, tags, and author profile details. - To retrieve an article using its URL path structure instead of its numeric ID, use the `/api/articles/{username}/{slug}` endpoint.

Published article by path This endpoint allows the client to retrieve a single published article given its `username` and `slug` (the URL-friendly path identifier). ### Usage Tip: - Handy for resolving absolute Forem/DEV article URLs (e.g., `https://dev.to/username/slug`) into their corresponding API data models.

Published articles This endpoint allows the client to retrieve a list of articles. "Articles" are all the posts that users create on DEV/Forem that typically show up in the feed. They can be a blog post, a discussion question, a help thread etc. but are referred to as articles within the code. By default it will return featured, published articles ordered by descending popularity. It supports pagination, each page will contain `30` articles by default. ### Query Parameter Usage Tips: - **Filtering by Tags**: - Use `tag` to filter articles containing a single exact tag (e.g. `tag=discuss`). - Use `tags` to retrieve articles containing *any* of the comma-separated list of tags (e.g. `tags=javascript,css`). - Use `tags_exclude` to filter out articles containing any of the comma-separated list of tags (e.g. `tags_exclude=node,java`). - **Filtering by User / Organization**: - Use `username` to retrieve articles belonging to a specific User or Organization. Articles are returned in reverse chronological publication order. - **State Options**: - Use `state=fresh` to fetch fresh articles. - Use `state=rising` to fetch rising/trending articles. - Combine `state=all` with `username` to fetch up to `1000` articles (both published and unpublished) from that user/organization in a single page. - **Top / Popularity**: - Use `top=N` to return the most popular articles published in the last `N` days (e.g. `top=7` for top articles of the week, `top=30` for top of the month). This parameter can be combined with `tag` to find top articles in a specific niche. - **Collections**: - Use `collection_id` to retrieve articles belonging to a specific collection/series, sorted chronologically.

Comment by id This endpoint allows the client to retrieve a specific comment and all of its nested descendant replies. ### Integration Tip: - Handy for linking directly to a deep comment thread or loading individual comment replies on demand.

Comments This endpoint allows the client to retrieve all comments belonging to an article or podcast episode as threaded conversations. ### Threaded Structure & Pagination Tips: - **Threaded Format**: Comments are returned as a tree structure (nested arrays of replies). Each top-level comment contains its nested child comments recursively. - **Query Constraints**: You must provide either `a_id` (Article ID) OR `p_id` (Podcast Episode ID) to fetch comments. Specifying both is not supported. - **Pagination**: When paginating, the `page` parameter filters the *top-level* comments only. All replies to those top-level comments are returned nested inline, regardless of page index. - If the `page` parameter is omitted, the response returns the full comment tree in a single payload.

Retrieve an event Retrieve a single event by ID.

Retrieve events Retrieve a list of events on the platform. ### Query Parameters: - **type_of**: Filter events by their type (`live_stream`, `takeover`, `other`, `challenge`).

Followed Tags Retrieve the list of tags followed by the authenticated user. ### Integration & Personalization Guidance: - Requires authentication. - Returns tags in ascending/popularity order based on user interactions. - Useful for customizing the home feed interface, constructing personalized sidebar navigation, or displaying a user's customized topic preferences in a dashboard.

Followers This endpoint allows the client to retrieve a list of the followers they have. ### Integration & Pagination Guidance: - "Followers" are other users registered on the platform who follow the authenticated user. - Supports pagination, defaulting to 80 followers per page. - The `sort` query parameter determines the sorting order based on when the follow relationship was established.

Published articles sorted by published date This endpoint allows the client to retrieve a list of articles ordered strictly by descending publication date. ### Usage Tips: - Bypasses all Forem/DEV feed personalization and popularity algorithms. - Ideal for building RSS feeds, chronological timelines, or "latest posts" widgets. - Supports standard `page` and `per_page` query parameters.

OpenAPI description Retrieve the machine-readable OpenAPI contract for this Forem instance. Automated clients should use this document instead of inferring endpoint schemas from responses or errors.

Organization's Articles Retrieve a list of articles published by the organization. ### Path Parameter Options: - **organization_id_or_username**: Supports either the organization's unique numerical ID OR its string username (slug). - Returns articles in reverse chronological publication order. - Ideal for populating an organization's custom blog feed or publication listing.

Organization's users Retrieve a list of public user profiles associated with the organization. ### Path Parameter Options: - **organization_id_or_username**: Supports either the organization's unique numerical ID OR its string username (slug). - Ideal for displaying team member directory lists on organization/brand pages.

An organization (by username) Retrieve public profile information for a single organization by its username. ### Integration Tip: - Bypasses authentication. - Returns details like Tech Stack, Tagline, Story, website URLs, and joined date.

An organization (by id) This endpoint allows the client to retrieve a single organization by their id

Organizations This endpoint allows the client to retrieve a list of Dev organizations. It supports pagination, each page will contain 10 tags by default.

Podcast Episodes Retrieve a list of podcast episodes published on the platform. ### Integration Guidance: - Bypasses authentication (can be accessed publicly). - Only returns active episodes belonging to published/reachable podcasts. - Episodes are returned in reverse chronological order based on their publication date. - The `username` query parameter is the unique slug of the podcast channel (e.g. `codenewbie`). It supports pagination, each page will contain 30 episodes by default.

A Users or organizations profile image Retrieve the profile image URL and configuration for a user or organization by username. ### Integration Details: - Bypasses authentication. - Convenient for quickly displaying avatars/icons in comments lists, headers, or sidebar elements without requesting the full user profile model.

Readinglist Retrieve the list of articles saved to the authenticated user's reading list. ### Integration Guidance: - Requires authentication. - Under the hood, this endpoint retrieves articles that the user has reacted to with the `"save"` reaction category. - Supports pagination, defaulting to 30 articles per page. - Returned objects conform to the standard `ArticleIndex` schema.

A manually managed audience segment Retrieve details of a single manually-managed audience segment specified by ID. ### Integration Tip: - Includes segment type (`manual`), configuration, and metadata. - Automatic/system-generated segments cannot be queried or updated via this endpoint.

Manually managed audience segments Retrieve a list of manually managed audience segments. ### Audience Segments Overview: - Audience Segments are cohorts of users grouped together for targeting announcements, features, or promotional campaign banners (Billboards). - This endpoint lists manual cohorts created and maintained by site administrators. - Requires administrator privileges. The endpoint supports pagination, and each page will contain `30` segments by default.

Supported tags Retrieve every tag supported on the platform (or current subforem), ordered by popularity. ### Integration Tips: - Bypasses authentication (can be accessed publicly). - Not paginated: returns the complete list of supported tags in a single response. - Edge cached; changes to a tag's supported status are purged from the cache automatically.

A survey with polls Retrieve a single survey (by ID or slug) with its nested structure. ### Nested Format Details: - Returns the target Survey object including all associated Polls, multiple choice options, and configuration states. - Requires Administrator authorization.

Survey poll text responses Retrieve free-text poll responses for a specific survey. ### Integration & Cursor Tip: - Fetches written user answers for text-input questions. - Uses cursor-based pagination (`after` query param) to stream responses. - Requires Administrator authorization.

Survey poll votes Retrieve multiple-choice poll votes for a specific survey. ### Cursor Pagination Tip: - Uses cursor-based pagination to safely stream high volumes of voting records. - Specify the `after` query parameter with the last retrieved record ID to get the next page. - Requires Administrator authorization.

List surveys Retrieve a list of surveys configured on the platform. ### Surveys Overview: - Surveys are admin-defined questionnaires consisting of multiple choice or text polls. - Requires Administrator authorization. - Supports standard pagination controls and active status filtering.

Tags Retrieve a list of tags used on the platform, ordered by popularity. ### Integration Tips: - Bypasses authentication (can be accessed publicly). - Ordered by overall popularity/usage metrics on the platform. - Useful for autocomplete inputs in article editors, tag selection screens in settings, or rendering global navigation/explore lists. It supports pagination, each page will contain 10 tags by default.

A Trend Retrieve details of a single trend using either its numeric ID or unique slug. ### Usage Guidance: - Useful for loading details of a trending topic (description, score, and slug details) to render header sections on trending tag or topic pages.

Articles in a Trend Retrieve a list of published articles belonging to a trend. ### Article Ordering & Proximity: - Articles are mapped to trends based on their embedding distance to the trend's centroid. - Returned articles are ordered by proximity/similarity (distance) first (most relevant posts first), and then by overall article engagement score. - Supports pagination, each page will contain 10 articles by default.

Trends Retrieve a list of active trends. ### Trends Overview & Score Calculation: - Trends represent hot topics or semantic themes currently being heavily discussed in the community. - They are computed by clustering semantic concept embeddings of recently published articles. - The `score` reflects the volume and engagement (views, comments, reactions) of articles associated with the trend. - Returned trends are ordered by score and recency. - Publicly accessible without authentication. It supports pagination, each page will contain 10 trends by default.