---
name: forem-api-v1
description: "Forem API V1 API skill. Use when working with Forem API V1 for api. Covers 131 endpoints."
version: 1.0.0
generator: lapsh
---

# Forem API V1
API version: 1.0.0

## Auth
ApiKey api-key in header

## Base URL
https://dev.to

## Setup
1. Set your API key in the appropriate header
2. GET /api/agent_sessions -- list the authenticated user's agent sessions
3. POST /api/agent_sessions -- create first agent_session

## Endpoints
131 endpoints across 1 group. See references/api-spec.lap for full details.

### Api
| Method | Path | Description |
|--------|------|-------------|
| GET | /api/agent_sessions | list the authenticated user's agent sessions |
| POST | /api/agent_sessions | upload a new agent session |
| GET | /api/agent_sessions/{id} | show details for an agent session |
| GET | /api/analytics/totals | Retrieve analytics totals |
| GET | /api/analytics/historical | Retrieve historical analytics |
| GET | /api/analytics/past_day | Retrieve analytics for the past day |
| GET | /api/analytics/referrers | Retrieve referrer analytics |
| GET | /api/analytics/top_contributors | Retrieve top contributors analytics |
| GET | /api/analytics/follower_engagement | Retrieve follower engagement analytics |
| GET | /api/analytics/dashboard | Retrieve dashboard analytics bundle |
| GET | /api/analytics/heatmap | Retrieve heatmap activity |
| POST | /api/articles | Publish article |
| GET | /api/articles | Published articles |
| GET | /api/articles/search | Search for articles |
| GET | /api/articles/latest | Published articles sorted by published date |
| GET | /api/articles/{id} | Published article by id |
| PUT | /api/articles/{id} | Update an article by id |
| GET | /api/articles/{username}/{slug} | Published article by path |
| GET | /api/articles/me | User's articles |
| GET | /api/articles/me/published | User's published articles |
| GET | /api/articles/me/unpublished | User's unpublished articles |
| GET | /api/articles/me/all | User's all articles |
| PUT | /api/articles/{id}/unpublish | Unpublish an article |
| GET | /api/articles/semantic_search | Perform a semantic fuzzy search on articles |
| GET | /api/segments | Manually managed audience segments |
| POST | /api/segments | Create a manually managed audience segment |
| GET | /api/segments/{id} | A manually managed audience segment |
| DELETE | /api/segments/{id} | Delete a manually managed audience segment |
| GET | /api/segments/{id}/users | Users in a manually managed audience segment |
| PUT | /api/segments/{id}/add_users | Add users to a manually managed audience segment |
| PUT | /api/segments/{id}/remove_users | Remove users from a manually managed audience segment |
| GET | /api/badge_achievements | Retrieve all badge achievements |
| POST | /api/badge_achievements | Create a badge achievement |
| GET | /api/badge_achievements/{id} | Retrieve a badge achievement's details |
| DELETE | /api/badge_achievements/{id} | Delete a badge achievement |
| GET | /api/badges | Retrieve all badges |
| POST | /api/badges | Create a badge |
| GET | /api/badges/{id} | Retrieve a badge's details |
| PATCH | /api/badges/{id} | Update a badge |
| DELETE | /api/badges/{id} | Delete a badge |
| GET | /api/billboards | Billboards |
| POST | /api/billboards | Create a billboard |
| GET | /api/billboards/{id} | A billboard (by id) |
| PUT | /api/billboards/{id} | Update a billboard by ID |
| PUT | /api/billboards/{id}/unpublish | Unpublish a billboard |
| GET | /api/comments | Comments |
| GET | /api/comments/{id} | Comment by id |
| GET | /api/concepts | Retrieve all accessible concepts |
| GET | /api/concepts/{id} | Retrieve details of a concept |
| PATCH | /api/concepts/{id} | Update a concept's metadata |
| GET | /api/concepts/{id}/articles | Retrieve articles mapped to a concept |
| GET | /api/admin/concepts | Retrieve all concepts (Admin) |
| POST | /api/admin/concepts | Create a concept (Admin) |
| GET | /api/admin/concepts/{id} | Retrieve concept detail (Admin) |
| PATCH | /api/admin/concepts/{id} | Update a concept (Admin) |
| DELETE | /api/admin/concepts/{id} | Delete a concept (Admin) |
| POST | /api/admin/concepts/{id}/trigger_lookback | Trigger concept lookback backfill (Admin) |
| GET | /api/concepts/search | Perform a semantic fuzzy search on concepts |
| PATCH | /api/feedback_messages/{id} | Update a feedback message's status (Admin) |
| GET | /api/follows/tags | Followed Tags |
| GET | /api/followers/users | Followers |
| POST | /api/follows | Follow users or organizations |
| GET | /api/health_checks/app | Check app health |
| GET | /api/health_checks/database | Check database connection |
| GET | /api/health_checks/cache | Check cache connection |
| GET | /api/instance | Retrieve instance configuration details |
| GET | /api/organizations/{username} | An organization (by username) |
| GET | /api/organizations/{organization_id_or_username}/users | Organization's users |
| GET | /api/organizations/{organization_id_or_username}/articles | Organization's Articles |
| GET | /api/organizations | Organizations |
| POST | /api/organizations | Create an Organization |
| GET | /api/organizations/{id} | An organization (by id) |
| PUT | /api/organizations/{id} | Update an organization by id |
| DELETE | /api/organizations/{id} | Delete an Organization by id |
| GET | /api/pages | show details for all pages |
| POST | /api/pages | pages |
| GET | /api/pages/{id} | show details for a page |
| PUT | /api/pages/{id} | update details for a page |
| DELETE | /api/pages/{id} | remove a page |
| GET | /api/podcast_episodes | Podcast Episodes |
| GET | /api/profile_images/{username} | A Users or organizations profile image |
| POST | /api/reactions/toggle | toggle reaction |
| POST | /api/reactions | create reaction |
| GET | /api/readinglist | Readinglist |
| GET | /api/recommended_articles_lists | Retrieve all recommended articles lists |
| POST | /api/recommended_articles_lists | Create or update a recommended articles list |
| GET | /api/recommended_articles_lists/{id} | Retrieve details of a recommended articles list |
| PATCH | /api/recommended_articles_lists/{id} | Update a recommended articles list |
| GET | /api/admin/request_redirects | Retrieve all request redirects (Admin) |
| POST | /api/admin/request_redirects | Create a request redirect (Admin) |
| GET | /api/admin/request_redirects/{id} | Retrieve a request redirect's details (Admin) |
| PATCH | /api/admin/request_redirects/{id} | Update a request redirect (Admin) |
| DELETE | /api/admin/request_redirects/{id} | Delete a request redirect (Admin) |
| GET | /api/subforems | Retrieve all discoverable subforems |
| GET | /api/surveys | List surveys |
| POST | /api/surveys | Create a survey |
| GET | /api/surveys/{id_or_slug} | A survey with polls |
| PATCH | /api/surveys/{id_or_slug} | Update a survey |
| DELETE | /api/surveys/{id_or_slug} | Delete a survey |
| GET | /api/surveys/{id_or_slug}/poll_votes | Survey poll votes |
| GET | /api/surveys/{id_or_slug}/poll_text_responses | Survey poll text responses |
| GET | /api/tags | Tags |
| GET | /api/trends | Trends |
| GET | /api/trends/{id_or_slug} | A Trend |
| GET | /api/trends/{trend_id_or_slug}/articles | Articles in a Trend |
| PUT | /api/users/{id}/suspend | Suspend a User |
| PUT | /api/users/{id}/limited | Add limited role for a User |
| DELETE | /api/users/{id}/limited | Remove limited for a User |
| PUT | /api/users/{id}/spam | Add spam role for a User |
| DELETE | /api/users/{id}/spam | Remove spam role from a User |
| PUT | /api/users/{id}/trusted | Add trusted role for a User |
| DELETE | /api/users/{id}/trusted | Remove trusted role from a User |
| GET | /api/users/me | The authenticated user |
| GET | /api/users/{id} | A User |
| GET | /api/users/search | Search for users |
| PUT | /api/users/{id}/unpublish | Unpublish a User's Articles and Comments |
| POST | /api/admin/users | Invite a User |
| GET | /api/admin/users | List all users (Admin) |
| GET | /api/admin/users/{id} | Get user detail (Admin) |
| PATCH | /api/admin/users/{id} | Update user profile (Admin) |
| PUT | /api/admin/users/{id}/email | Update user email (Admin) |
| PUT | /api/admin/users/{id}/status | Update user moderation status (Admin) |
| PUT | /api/admin/users/{id}/notification_settings | Update user notification settings (Admin) |
| POST | /api/admin/users/{id}/merge | Merge user into another (Admin) |
| GET | /api/admin/users/{user_id}/notes | List notes for a user (Admin) |
| POST | /api/admin/users/{user_id}/notes | Add a note to a user (Admin) |
| GET | /api/admin/users/{user_id}/identities | List identities for a user (Admin) |
| POST | /api/admin/users/{user_id}/identities | Link an identity to a user (Admin) |
| DELETE | /api/admin/users/{user_id}/identities/{id} | Unlink an identity from a user (Admin) |
| POST | /api/admin/users/identities/bulk | Bulk link identities (Admin) |
| GET | /api/videos | Articles with a video |

## Common Questions
Match user requests to endpoints in references/api-spec.lap. Key patterns:
- "List all agent_sessions?" -> GET /api/agent_sessions
- "Create a agent_session?" -> POST /api/agent_sessions
- "Get agent_session details?" -> GET /api/agent_sessions/{id}
- "List all totals?" -> GET /api/analytics/totals
- "List all historical?" -> GET /api/analytics/historical
- "List all past_day?" -> GET /api/analytics/past_day
- "List all referrers?" -> GET /api/analytics/referrers
- "List all top_contributors?" -> GET /api/analytics/top_contributors
- "List all follower_engagement?" -> GET /api/analytics/follower_engagement
- "List all dashboard?" -> GET /api/analytics/dashboard
- "List all heatmap?" -> GET /api/analytics/heatmap
- "Create a article?" -> POST /api/articles
- "List all articles?" -> GET /api/articles
- "Search search?" -> GET /api/articles/search
- "List all latest?" -> GET /api/articles/latest
- "Get article details?" -> GET /api/articles/{id}
- "Update a article?" -> PUT /api/articles/{id}
- "List all me?" -> GET /api/articles/me
- "List all published?" -> GET /api/articles/me/published
- "List all unpublished?" -> GET /api/articles/me/unpublished
- "List all all?" -> GET /api/articles/me/all
- "Search semantic_search?" -> GET /api/articles/semantic_search
- "List all segments?" -> GET /api/segments
- "Create a segment?" -> POST /api/segments
- "Get segment details?" -> GET /api/segments/{id}
- "Delete a segment?" -> DELETE /api/segments/{id}
- "List all users?" -> GET /api/segments/{id}/users
- "List all badge_achievements?" -> GET /api/badge_achievements
- "Create a badge_achievement?" -> POST /api/badge_achievements
- "Get badge_achievement details?" -> GET /api/badge_achievements/{id}
- "Delete a badge_achievement?" -> DELETE /api/badge_achievements/{id}
- "List all badges?" -> GET /api/badges
- "Create a badge?" -> POST /api/badges
- "Get badge details?" -> GET /api/badges/{id}
- "Partially update a badge?" -> PATCH /api/badges/{id}
- "Delete a badge?" -> DELETE /api/badges/{id}
- "List all billboards?" -> GET /api/billboards
- "Create a billboard?" -> POST /api/billboards
- "Get billboard details?" -> GET /api/billboards/{id}
- "Update a billboard?" -> PUT /api/billboards/{id}
- "List all comments?" -> GET /api/comments
- "Get comment details?" -> GET /api/comments/{id}
- "List all concepts?" -> GET /api/concepts
- "Get concept details?" -> GET /api/concepts/{id}
- "Partially update a concept?" -> PATCH /api/concepts/{id}
- "Create a concept?" -> POST /api/admin/concepts
- "Delete a concept?" -> DELETE /api/admin/concepts/{id}
- "Create a trigger_lookback?" -> POST /api/admin/concepts/{id}/trigger_lookback
- "Partially update a feedback_message?" -> PATCH /api/feedback_messages/{id}
- "List all tags?" -> GET /api/follows/tags
- "Create a follow?" -> POST /api/follows
- "List all app?" -> GET /api/health_checks/app
- "List all database?" -> GET /api/health_checks/database
- "List all cache?" -> GET /api/health_checks/cache
- "List all instance?" -> GET /api/instance
- "Get organization details?" -> GET /api/organizations/{username}
- "List all organizations?" -> GET /api/organizations
- "Create a organization?" -> POST /api/organizations
- "Update a organization?" -> PUT /api/organizations/{id}
- "Delete a organization?" -> DELETE /api/organizations/{id}
- "List all pages?" -> GET /api/pages
- "Create a page?" -> POST /api/pages
- "Get page details?" -> GET /api/pages/{id}
- "Update a page?" -> PUT /api/pages/{id}
- "Delete a page?" -> DELETE /api/pages/{id}
- "List all podcast_episodes?" -> GET /api/podcast_episodes
- "Get profile_image details?" -> GET /api/profile_images/{username}
- "Create a toggle?" -> POST /api/reactions/toggle
- "Create a reaction?" -> POST /api/reactions
- "List all readinglist?" -> GET /api/readinglist
- "Search recommended_articles_lists?" -> GET /api/recommended_articles_lists
- "Create a recommended_articles_list?" -> POST /api/recommended_articles_lists
- "Get recommended_articles_list details?" -> GET /api/recommended_articles_lists/{id}
- "Partially update a recommended_articles_list?" -> PATCH /api/recommended_articles_lists/{id}
- "List all request_redirects?" -> GET /api/admin/request_redirects
- "Create a request_redirect?" -> POST /api/admin/request_redirects
- "Get request_redirect details?" -> GET /api/admin/request_redirects/{id}
- "Partially update a request_redirect?" -> PATCH /api/admin/request_redirects/{id}
- "Delete a request_redirect?" -> DELETE /api/admin/request_redirects/{id}
- "List all subforems?" -> GET /api/subforems
- "List all surveys?" -> GET /api/surveys
- "Create a survey?" -> POST /api/surveys
- "Get survey details?" -> GET /api/surveys/{id_or_slug}
- "Partially update a survey?" -> PATCH /api/surveys/{id_or_slug}
- "Delete a survey?" -> DELETE /api/surveys/{id_or_slug}
- "List all poll_votes?" -> GET /api/surveys/{id_or_slug}/poll_votes
- "List all poll_text_responses?" -> GET /api/surveys/{id_or_slug}/poll_text_responses
- "List all trends?" -> GET /api/trends
- "Get trend details?" -> GET /api/trends/{id_or_slug}
- "Get user details?" -> GET /api/users/{id}
- "List all search?" -> GET /api/users/search
- "Create a user?" -> POST /api/admin/users
- "Partially update a user?" -> PATCH /api/admin/users/{id}
- "Create a merge?" -> POST /api/admin/users/{id}/merge
- "List all notes?" -> GET /api/admin/users/{user_id}/notes
- "Create a note?" -> POST /api/admin/users/{user_id}/notes
- "List all identities?" -> GET /api/admin/users/{user_id}/identities
- "Create a identity?" -> POST /api/admin/users/{user_id}/identities
- "Delete a identity?" -> DELETE /api/admin/users/{user_id}/identities/{id}
- "Create a bulk?" -> POST /api/admin/users/identities/bulk
- "List all videos?" -> GET /api/videos
- "How to authenticate?" -> See Auth section above

## Response Tips
- Check response schemas in references/api-spec.lap for field details
- Paginated endpoints accept limit/offset or cursor parameters
- Create/update endpoints return the modified resource on success
- Error responses include status codes and descriptions in the spec

## References
- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas

> Generated from the official API spec by [LAP](https://lap.sh)