DEV Community

Revoke a badge award by deleting the badge achievement. Requires administrator privileges. via DELETE /api/badge_achievements/{id}

Delete a badge configuration from the system by ID. Requires administrator privileges. via DELETE /api/badges/{id}

Delete an event. Requires administrator privileges. via DELETE /api/events/{id}

This endpoint allows the client to delete a single organization, specified by id via DELETE /api/organizations/{id}

Delete a custom page from the system by ID. Requires administrative privileges. via DELETE /api/pages/{id}

Delete an audience segment specified by ID. Constraints: - Audience segments cannot be deleted if they are currently assigned to any active or pending Billboards. via DELETE /api/segments/{id}

Delete an existing survey. Requires Administrator privileges. via DELETE /api/surveys/{id_or_slug}

Remove the limited role, restoring the user to general privileges. Requires admin or moderator role. via DELETE /api/users/{id}/limited

Unflag a user as spammer, restoring general permissions. Requires admin or moderator role. via DELETE /api/users/{id}/spam

Revoke the trusted role, returning the user to general status. Requires admin or moderator role. via DELETE /api/users/{id}/trusted

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. via GET /api/agent_sessions

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. via GET /api/agent_sessions/{id}

Retrieve a temporary presigned GET URL to download the original raw transcript file from S3. via GET /api/agent_sessions/{id}/raw_url

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

Retrieve stats detailing new follower growth and engagement over time. via GET /api/analytics/follower_engagement

Retrieve user activity heatmap metrics (commits, posts, reactions) grouped by weekdays and hours. via GET /api/analytics/heatmap

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. via GET /api/analytics/historical

Retrieve real-time hourly analytics statistics for the last 24 hours. Used for live graphs. via GET /api/analytics/past_day

Retrieve traffic referring domains and URL source tracking metrics for articles. via GET /api/analytics/referrers

Retrieve top organization contributors ordered by article engagement scores. via GET /api/analytics/top_contributors

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. via GET /api/analytics/totals

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. via GET /api/articles

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. via GET /api/articles/{id}

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. via GET /api/articles/{username}/{slug}

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. via GET /api/articles/latest

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. via GET /api/articles/me

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. via GET /api/articles/me/all

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. via GET /api/articles/me/published

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. via GET /api/articles/me/unpublished

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. via GET /api/articles/search

Allows authenticated clients to search articles using Forem's semantic embeddings database. via GET /api/articles/semantic_search

Retrieve a list of all badge achievements (awarded badges) in the system. Requires administrator privileges. via GET /api/badge_achievements

Retrieve details of a specific badge award/achievement by ID. via GET /api/badge_achievements/{id}

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. via GET /api/badges

Retrieve details of a single badge by unique numeric ID. via GET /api/badges/{id}

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. via GET /api/billboards

Retrieve full configurations of a single billboard by ID. Requires admin credentials. via GET /api/billboards/{id}

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. via GET /api/comments

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. via GET /api/comments/{id}

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. via GET /api/concepts

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. via GET /api/concepts/{id}

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. via GET /api/concepts/{id}/articles

Allows authenticated clients to search concepts using Forem's semantic embeddings database. via GET /api/concepts/search

Retrieve a list of events on the platform. Query Parameters: - type_of: Filter events by their type (live_stream, takeover, other, challenge). via GET /api/events

Retrieve a single event by ID. via GET /api/events/{id}

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. via GET /api/followers/users

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. via GET /api/follows/tags

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. Needs the Forem instance's own health-check token, which is a server configuration value (HEALTH_CHECK_TOKEN) rather than anything a DEV account can mint: measured 2026-09-16, dev.to answers 401 to this call with a valid DEV API key and no token, although the contract marks the header optional. Pass it as health_check_token if you operate the instance; Agentic Fabriq never stores it and sends it only on this call. via GET /api/health_checks/app

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. Needs the Forem instance's own health-check token, which is a server configuration value (HEALTH_CHECK_TOKEN) rather than anything a DEV account can mint: measured 2026-09-16, dev.to answers 401 to this call with a valid DEV API key and no token, although the contract marks the header optional. Pass it as health_check_token if you operate the instance; Agentic Fabriq never stores it and sends it only on this call. via GET /api/health_checks/cache

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. Needs the Forem instance's own health-check token, which is a server configuration value (HEALTH_CHECK_TOKEN) rather than anything a DEV account can mint: measured 2026-09-16, dev.to answers 401 to this call with a valid DEV API key and no token, although the contract marks the header optional. Pass it as health_check_token if you operate the instance; Agentic Fabriq never stores it and sends it only on this call. via GET /api/health_checks/database

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. via GET /api/instance

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

This endpoint allows the client to retrieve a single organization by their id via GET /api/organizations/{id}

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. via GET /api/organizations/{organization_id_or_username}/articles

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. via GET /api/organizations/{organization_id_or_username}/users

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. via GET /api/organizations/{username}

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. via GET /api/pages

Retrieve details for a single Page object specified by ID. via GET /api/pages/{id}

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. via GET /api/podcast_episodes

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. via GET /api/profile_images/{username}

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. via GET /api/readinglist

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. via GET /api/recommended_articles_lists

Retrieve full details and nested article lists for a specific recommended articles list by ID. Requires Admin credentials. via GET /api/recommended_articles_lists/{id}

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. via GET /api/segments

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. via GET /api/segments/{id}

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. via GET /api/segments/{id}/users

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. via GET /api/subforems

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. via GET /api/surveys

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. via GET /api/surveys/{id_or_slug}

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. via GET /api/surveys/{id_or_slug}/poll_text_responses

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. via GET /api/surveys/{id_or_slug}/poll_votes

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. via GET /api/tags

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. via GET /api/trends

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. via GET /api/trends/{id_or_slug}

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. via GET /api/trends/{trend_id_or_slug}/articles

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. via GET /api/users/{id}

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. via GET /api/users/me

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. via GET /api/users/search

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. via GET /api/v1/openapi.json

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. via GET /api/videos

Update badge details (title, description, credits awarded, etc.) by unique ID. Requires administrator privileges. via PATCH /api/badges/{id}

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. via PATCH /api/concepts/{id}

Update an existing event. Requires administrator privileges. via PATCH /api/events/{id}

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). via PATCH /api/feedback_messages/{id}

Update an existing recommended articles list by ID. Requires Admin credentials. via PATCH /api/recommended_articles_lists/{id}

Update an existing survey, including its polls and options. Requires Administrator privileges. via PATCH /api/surveys/{id_or_slug}

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). via POST /api/agent_sessions

Generate an S3 presigned PUT URL and object key for uploading raw session transcripts directly to S3. via POST /api/agent_sessions/presign

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. - 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). via POST /api/articles

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. via POST /api/badge_achievements

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). via POST /api/badges

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. via POST /api/billboards

Create a new event. Requires administrator privileges. via POST /api/events

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. via POST /api/follows

This endpoint allows the client to create an organization with the provided parameters. It requires a token from a user with admin privileges. via POST /api/organizations

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). via POST /api/pages

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. via POST /api/reactions

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. via POST /api/reactions/toggle

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. via POST /api/recommended_articles_lists

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. via POST /api/segments

Create a new survey with optional nested polls and poll options. Requires Administrator privileges. via POST /api/surveys

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. via PUT /api/articles/{id}

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. via PUT /api/articles/{id}/unpublish

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. via PUT /api/billboards/{id}

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. via PUT /api/billboards/{id}/unpublish

This endpoint allows the client to update an existing organization. via PUT /api/organizations/{id}

Update an existing page's details by ID. Requires administrative privileges. via PUT /api/pages/{id}

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. via PUT /api/segments/{id}/add_users

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). via PUT /api/segments/{id}/remove_users

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. via PUT /api/users/{id}/limited

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. via PUT /api/users/{id}/spam

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. via PUT /api/users/{id}/suspend

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. via PUT /api/users/{id}/trusted

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. via PUT /api/users/{id}/unpublish