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.

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).

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.

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.

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 real-time hourly analytics statistics for the last 24 hours. Used for live graphs.

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

Retrieve top organization contributors ordered by article engagement scores.

Retrieve stats detailing new follower growth and engagement over time.

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

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

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: A comma-separated list of tags (up to 4 tags). 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.

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.

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.

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.

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.

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, etc.
• Setting published: false on an already published article will revert it to draft status.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Remove the limited role, restoring the user to general privileges. Requires admin or moderator role.

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.

Unflag a user as spammer, restoring general permissions. Requires admin or moderator role.

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.

Revoke the trusted role, returning the user to general status. Requires admin or moderator role.

This endpoint allows the client to retrieve information about the authenticated user.

Usage Tips:

• Requires a valid api-key header to identify the user.
• Useful for checking permissions, verifying linking state, or retrieving user-specific profile settings.